Basic Contracts

Gateway Connect Contracts

Incoming Request: POST /pay

Business Service sends JSON. Method is passed in the method_name field.

{
  "method_name": "pay",
  "params": {
    "customer": {
      "email": "test@test.com",
      "ip": "192.168.1.1",
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "phone": "+12345678"
    },
    "pan": "4111111111111111",
    "cvv": "123",
    "expires": "12/25",
    "card": { "pan": "4111111111111111" },
    "bank_account": {
      "account_number": "IE1234567890123456",
      "bank_code": "BOFI",
      "requisite_type": "card"
    },
    "extra_return_param": "tbank",
    "recurring": true,
    "need_confirmation": true,
    "custom_request_field": "foo"
  },
  "payment": {
    "token": "tok_xxxx",
    "merchant_private_key": "mkey_xxx",
    "gateway_amount": 10000,
    "gateway_currency": "USD",
    "product": "Premium Plan",
    "lead_id": 12345,
    "order_number": "ORD-001",
    "extra_return_param": "user_data"
  },
  "settings": {
    "api_key": "provider_api_token",
    "sign_key": "jwt_secret_key"
  },
  "processing_url": "https://pay.host/...",
  "callback_url": "https://api.business/..."
}

Fields params

Field	Type	Required	Description
customer	object	yes	Payer data
customer.email	string	yes	Email
customer.ip	string	yes	IP address
customer.first_name	string	no	First name
customer.last_name	string	no	Last name
customer.phone	string	no	Phone
customer.address	string	no	Address
customer.postcode	string	no	Postal code
customer.city	string	no	City
customer.state	string	no	State
customer.country	string	no	Country (ISO 3166-1)
customer.birthday	string	no	Birthday
pan	string	no	Card number (H2H)
cvv	string	no	CVV/CVC (H2H)
expires	string	no	Card expiration date MM/YY (H2H)
card	object	no	Recipient card data (Payout)
card.pan	string	no	Recipient card number
card.card_token_from	string	no	Token of saved card for PAN recovery
bank_account	object	no	Bank account details
bank_account.account_number	string	no	Account number
bank_account.bank_code	string	no	Bank code
bank_account.requisite_type	string	no	Requisite type: card, sbp, account, link, url
extra_return_param	string	no	Additional parameter, saved in payment.extra_return_param
recurring	boolean	no	Recurring payment flag
need_confirmation	boolean	no	Two-step payment flag
custom_request_field	string	no	Custom extra field passed by the merchant

Fields payment

Field	Type	Required	Description
token	string	yes	Unique payment token
merchant_private_key	string	yes	Merchant private key (encrypted in callback)
gateway_amount	integer	yes	Amount in minor units (10000 = 100.00)
gateway_currency	string	yes	Currency (ISO 4217)
product	string	no	Merchant product name
lead_id	integer	no	Lead ID (unique id of the payer’s email)
order_number	string	no	Merchant order number
card_brand_name	string	no	Detected card brand, see Possible Card Brand Values
extra_return_param	string	no	Additional return parameter

Fields settings

See full reference in Settings and Statuses.

Request Fields

Field	Type	Required	Description
method_name	string	yes	Method name: pay, payout, status
processing_url	string	yes	Return URL for user after payment
callback_url	string	yes	URL for provider callbacks

Gateway Response: POST /pay (success)

HTTP 200. Depending on result — one of three response formats.

Success / pending (3DS, Redirect, P2P):

{
  "result": true,
  "status": "pending",
  "gateway_token": "bank_transaction_123",
  "amount": 10000,
  "currency": "USD",
  "redirect_request": {
    "url": "https://3ds.bank.com/challenge",
    "type": "post",
    "params": { "creq": "eyJhb..." }
  },
  "requisites": {
    "card": "461761****3933",
    "holder": "IVAN I.",
    "bank_name": "BankOfBaku",
    "phone": "+77001234567",
    "account": "IE1234567890123456",
    "link": "https://...",
    "deeplink": true,
    "qr_data": "..."
  },
  "recurring_gateway_token": "rec_tok_xxx",
  "gateway_details": {},
  "provider_response_data": {},
  "logs": [...]
}

Field	Type	Required	Description
result	boolean	yes	true — successful processing
status	string	yes	approved, pending, declined
gateway_token	string	yes	Provider transaction identifier
amount	integer	no	Amount in kopecks
currency	string	no	Currency
redirect_request	object	no	Redirect data (see section 3)
requisites	object	no	P2P transfer details
recurring_gateway_token	string	no	Token for recurring payments
gateway_details	object	no	Additional gateway data (saved in payment.gateway_details)
provider_response_data	object	no	Provider data for P2P (wrapped_json_response)
details	string	no	Result description
logs	array	yes	Interaction logs (see section 4)

System error:

{
  "result": false,
  "error": "Provider returned HTTP 502",
  "logs": [...]
}

Structure redirect_request

"redirect_request": {
  "url": "https://3ds.bank.com/challenge",
  "type": "post",
  "params": {
    "creq": "eyJhb..."
  }
}

Field	Type	Description
url	string	Redirect URL
type	string	Redirect type
params	object	Parameters to pass

Redirect Types (type)

Type	Description
get	Simple GET redirect
post	Auto-submit POST form
post_iframes	POST to iframe
get_with_processing	GET redirect with intermediate processing page
redirect_html	HTML redirect

Both redirect_request and redirectRequest (camelCase) keys are supported.

Possible Card Brand Values

card_brand_name
Visa
MasterCard
American Express
Maestro
Rupay
Elo
Mir
Discover
China UnionPay
JCB
Dankort
Hipercard

Log Format (logs)

Array of objects recording all network interactions with provider.

"logs": [
  {
    "request": {
      "url": "https://api.provider.com/v1/pay",
      "body": "{\"amount\": 100, \"currency\": \"USD\"}"
    },
    "status": 200,
    "response": "{\"state\": \"OK\"}",
    "kind": "pay",
    "duration": 0.35
  }
]

Field	Type	Description
request.url	string	Request URL
request.body	string/object	Request body
status	integer	Provider response HTTP status
response	string/object	Provider response body
kind	string	Operation type
duration	float	Request duration in seconds

Values kind

Value	Description
pay	Payment request
payout	Payout request
status	Status check
callback	Callback processing
refund	Refund
confirm_request	Two-step payment confirmation
decline_request	Two-step payment decline
confirm_secure_code	3DS/OTP confirmation
next_payment_step	Next payment step