General Information

Payout API is a universal API for paying out funds from legal entities. Among the possible payment instruments are available:

Bank cards
Faster Payments System (SBP)
Other tools

API overview

The payout API is built on the REST architecture, where data and functionality are considered resources accessed via Uniform Resource Identifiers (URIs).

Resources are processed using a set of simple, well-defined operations. Clients and servers exchange representations of resources using a standardized interface and the HTTP protocol.

HTTP methods

GET — methods for getting information about existing objects.
PUT — methods for creating new objects, with assignment of an identifier on the client side.
POST — methods that operate on existing objects.

Content type

Resources are represented as JSON objects; when creating them (HTTP method PUT) you must specify Content-Type: application/json in the request headers.

Data transfer methods

path — as an element of the request URI. Unambiguously defines the resource with which the interaction takes place (partner ID, payouts, etc.).
query - as a request parameter. Determines the specificity of the request type, such as options for pagination.
header - as a request header. Specifies additional request options, such as a request signature.
body - as the body of the request, represented as a JSON object. Specifies the details of the resource to be created, only applicable to the HTTP PUT method.

Idempotency

Most of the methods provide physical or logical idempotence, i.e. repeating an action multiple times is equivalent to doing it once. Although idempotent operations produce the same result on the server, the response itself may not be the same (for example, the state of a resource may change between requests).

Authorization

As part of the technical interaction, only one types of authorization is available:

Using Bearer Token

Authorization using Bearer token

GET /partner/payout/v2/agents/acme/providers HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/providers

With this type of authorization, all partner requests, when calling methods, are authorized by the value of the Bearer token known only to the partner.

The token is specified in the Authorization HTTP header with the Bearer prefix, according to the specification RFC 6750. For example: Authorization: Bearer <Token-Value>.

Versioning

Method versioning is supported in the universal Payout API. The URL for calling the method contains a suffix that specifies the required version of the method:

https://b2b-api.qiwi.com/partner/payout/v<version>/<method>

Currently, two versions of the Payout API are supported - 1 and 2. The actual current version of the payout protocol is 2 version. Method descriptions explicitly specify which API versions to use.

API endpoints

Test environment

For calls to API methods in a test environment, depending on the type of encryption and authorization method, the following endpoints are used:

Encryption	Authorization	Endpoint
RSA	Token	`https://b2b-api-test.qiwi.com/`

Production environment

For calls to API methods in a production environment, depending on the type of encryption and authorization method, the following endpoints are used:

Encryption	Authorization	Endpoint
RSA	Token	`https://b2b-api.qiwi.com/`

Service methods

Methods for working with the list of available payout providers, their parameters, limits, as well as getting the agent's balance.

Main account balance

GET /partner/payout/v2/agents/acme/balance HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/balance

Gets the current balance of the main account.


HTTP method:	GET
Resource URI:	`/partner/payout/v2/agents/{agentId}/balance`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "balance": {
    "currency": "RUB",
    "value": "1000000.00"
  },
  "overdraft": {
    "currency": "RUB",
    "value": "500000.00"
  },
  "available": {
    "currency": "RUB",
    "value": "1500000.00"
  }
}

A successful response contains the current balance of the main account as a Balance object.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

Balance of all accounts

GET /partner/payout/v2/agents/acme/balances HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/balances

Gets the current balance of all accounts.


HTTP method:	GET
Resource URI:	`/partner/payout/v2/agents/{agentId}/balances`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "RUB": {
    "balance": {
      "currency": "RUB",
      "value": "1000000.00"
    },
    "available": {
      "currency": "RUB",
      "value": "1000000.00"
    }
  }
}

A successful response contains a set of balances of all accounts as a ratio of Currency and Balance.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

List of providers

GET /partner/payout/v2/agents/acme/providers HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/providers

Gets a list of available payout providers.


HTTP method:	GET
Resource URI:	`/partner/payout/v2/agents/{agentId}/providers`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "providerCode": "bank-card-russia",
    "name": "Банковские карты РФ"
  }
]

A successful response contains a sequential array of the Provider object's provider elements.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

Provider information

GET /partner/payout/v2/agents/acme/providers/bank-card-russia HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/providers/bank-card-russia

Gets extended information about the provider.


HTTP method:	GET
Resource URI:	`/partner/payout/v2/agents/{agentId}/providers/{providerCode}`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier
providerCode	path	✓	ProviderCode	Provider unique identifier

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "Payouts to bank cards",
  "legalName": "",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "pan",
      "required": true,
      "description": "Unmasked card PAN",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "33441123453",
  "contactDetails": {
    "address": "string",
    "phoneNumber": "8-800-111-22-33"
  }
}

A successful response contains extended information about the provider in the form of a ProviderInfo object.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

Payment methods

Methods for working with payments, including creating, processing, and receiving information about a payment.

Creating a payment

PUT /partner/payout/v2/agents/acme/payments/0123456789 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <Token-Value>
Signature: <Sign-Value>
Host: b2b-api.qiwi.com

{
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234564543654321"
    }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <Token-Value>" \
     -H "Signature: <Sign-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789 \
     -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "recipientDetails": {
              "providerCode": "bank-card-russia",
              "fields": {
                "pan": "1234567890213456"
              }
            },
            "webhookUrl": "https://acme.inc/webhook",
            "customFields": {
              "user": "Wile E. Coyote"
            }
        }'

Creates a new payment.


HTTP method:	PUT
Resource URI:	`/partner/payout/v2/agents/{agentId}/payments/{paymentId}`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier
paymentId	path	✓	string	Unique payment identifier from 1 to 36 characters
Signature	header	✓	string	Payment request signature
payload	body	✓	PaymentPayload	Parameters of the created payment

The unique payment ID paymentId must be a 36-character string after URL decoding. Any character is allowed, including -, _, and .. A dimension of 36 characters allows you to pass a GUID as a payment identifier.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentId": "0123456789",
  "creationDateTime": "2023-01-17T15:05:51+03:00",
  "expirationDateTime": "2023-01-17T15:35:51+03:00",
  "status": {
    "value": "READY",
    "changedDateTime": "2023-01-17T15:05:51+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "2.00"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234567890213456"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

A successful response contains information on the created payment in the form of a Payment object.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

Payment request signature

To create a payment, a partner should sign the request and send the signature in Signature HTTP header.

To sign a request, make the following steps:

Create key pair with RSA-2048 algorithm.
Send corresponding public key.
Sign each payment request.

Steps 1 and 2 are performed once, step 3 is performed for each request.

Create key pair

openssl genrsa -out private-key.pem 2048

openssl rsa -in private-key.pem -pubout -out public-key.pem

Key pair is generated using the OpenSSL utility.

Generate the private key. Key size is strictly 2048 bit with PEM format.

Private key file with name private-key.pem is created in the folder where the command is executed.

Private key should be kept confidential, do not share it with third parties.
Obtain the corresponding public key.

Transfer public key

Partner should send the public key file obtained on step 2 of the key pair creation. Contact support manager to clarify a way to send the key.

Request signature calculation

SIGNATURE_STRING='{agentId}|{paymentId}|{amount.value}|{amount.currency}|{recipientDetails.providerCode}|{values of recipientDetails.fields in alphabet order of field names}'

SIGNATURE_RAW=$(echo -n $SIGNATURE_STRING | openssl dgst -sha256 -sign private-key.pem)

SIGNATURE_BASE64=$(echo -n $SIGNATURE_RAW | base64)

Prepare the string for signature with values of the selected request parameters (use delimiter | to concatenate parameters):
- agentId
- paymentId
- amount.value
- amount.currency
- recipientDetails.providerCode
- values of recipientDetails.fields in alphabet order of field names.
  You can use prepared templates for signing, they are different for each provider.
Make the digital signature with SHA256withRSA algorithm and private key private-key.pem obtained in Create key pair.
Base64-encode the digital signature.
Send the encoded digital signature in Signature HTTP header of the request.

Payment processing

POST /partner/payout/v2/agents/acme/payments/0123456789/execute HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X POST \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789/execute

Executes a payment.


HTTP method:	POST
Resource URI:	`/partner/payout/v2/agents/{agentId}/payments/{paymentId}/execute`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier
paymentId	path	✓	string	Unique payment identifier from 1 to 36 characters

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentId": "0123456789",
  "creationDateTime": "2023-01-17T15:05:51+03:00",
  "expirationDateTime": "2023-01-17T15:35:51+03:00",
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2023-01-17T15:06:00+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "2.00"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234567890213456"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

A successful response contains information on the completed payment in the form of a Payment object.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

List of payments

GET /partner/payout/v2/agents/acme/payments HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/payments

Gets a list of recent payments. Without specifying the from and to filters, payments are searched for the last 50 days.


HTTP method:	GET
Resource URI:	`/partner/payout/v2/agents/{agentId}/payments`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier
limit	query	×	integer	The limit on the number of payments returned in the response, default 20
offset	query	×	integer	Number of payments to skip, default 0
from	query	×	date	Search interval start date in `YYYY-MM-DD` format
to	query	×	date	Search interval end date in `YYYY-MM-DD` format

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "paymentId": "0123456789-01",
    "creationDateTime": "2023-01-17T15:05:51+03:00",
    "expirationDateTime": "2023-01-17T15:35:51+03:00",
    "status": {
      "value": "COMPLETED",
      "changedDateTime": "2023-01-17T15:06:00+03:00"
    },
    "amount": {
      "currency": "RUB",
      "value": "2.00"
    },
    "recipientDetails": {
      "providerCode": "bank-card-russia",
      "fields": {
        "pan": "1234567890213456"
      }
    },
    "commission": {
      "currency": "RUB",
      "value": "0.04"
    },
    "webhookUrl": "https://acme.inc/webhook",
    "customFields": {
      "user": "Wile E. Coyote"
    }
  },
  {
    "paymentId": "0123456789-02",
    "creationDateTime": "2023-01-18T15:05:51+03:00",
    "expirationDateTime": "2023-01-18T15:35:51+03:00",
    "status": {
      "value": "COMPLETED",
      "changedDateTime": "2023-01-18T15:06:00+03:00"
    },
    "amount": {
      "currency": "RUB",
      "value": "40.00"
    },
    "recipientDetails": {
      "providerCode": "bank-card-russia",
      "fields": {
        "pan": "1243567790213456"
      }
    },
    "commission": {
      "currency": "RUB",
      "value": "0.80"
    },
    "webhookUrl": "https://acme.inc/webhook",
    "customFields": {
      "user": "Wile E. Coyote"
    }
  }
]

A successful response contains a collection of payments Payment according to the specified search conditions.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

Payment information

GET /partner/payout/v2/agents/acme/payments/0123456789-02 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789-02

Gets payment's information. The payment is searched for the last 50 days.


HTTP method:	GET
Resource URI:	`/partner/payout/v2/agents/{agentId}/payments/{paymentId}`

Parameters

Parameter	Position	✓\×	Type	Description
agentId	path	✓	string	Agent unique identifier
paymentId	path	✓	string	Unique payment identifier from 1 to 36 characters

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "paymentId": "0123456789-02",
  "creationDateTime": "2023-01-18T15:05:51+03:00",
  "expirationDateTime": "2023-01-18T15:35:51+03:00",
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2023-01-18T15:06:00+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "40.00"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234567890213456"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.80"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

A successful response contains payment information in the form of a Payment object.

A response with an HTTP error code (4xx, 5xx) contains an Error object. See Error handling for details.

Notifications

Methods for working with partner notifications about changes in the system, including notifications about changes in payment status.

Payment status notification

POST /webhook HTTP/1.1
Accept: application/json
Content-Type: application/json
Signature: <Sign-Value>
Host: acme.inc

{
  "agentId": "acme",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
    "value": "FAILED",
    "changedDateTime": "2023-01-18T13:00:28Z",
    "errorCode": "INTERNAL_ERROR",
    "errorMessage": "Some reason"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId": "20221101000019",
    "rrn": "A123456",
    "accountNumber": "4950001122",
    "accountInfo": "Ivanov I.P.",
    "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
  }
}

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Signature: <Sign-Value>" \
     https://acme.inc/webhook \
     -d '{
           "agentId": "acme",
           "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
           "status": {
             "value": "FAILED",
             "changedDateTime": "2023-01-18T13:00:28Z",
             "errorCode": "INTERNAL_ERROR",
             "errorMessage": "Some reason"
           },
           "amount": {
             "value": "200.00",
             "currency": "RUB"
           },
           "billingDetails": {
             "transactionId": "20221101000019",
             "rrn": "A123456",
             "accountNumber": "4950001122",
             "accountInfo": "Ivanov I.P.",
             "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
           }
        }'

Notifies the partner of a payment status change.


HTTP method:	POST
Resource URI:	`{webhookAddressUrl}`

Parameters

Parameter	Position	✓\×	Type	Description
webhookAddressUrl	path	✓	string	Partner Notification URL
Signature	header	✓	string	Request signature, see calculation algorithm
payload	body	✓	Webhook	Payment Information

Request signature calculation algorithm

The following algorithm is used to calculate the Signature signature:

Generate a signature string like this:

{agentId}|{paymentId}|{status.value}|{amount.value}|{amount.currency}

where each of the {param} is the value of the corresponding parameter in the Webhook notification body, and then all values stuck together with the | character.
Compute HMAC with SHA256 hash function from generated string and private key as encryption key.
Pass the resulting signature in the request header to the Signature field.

Response

The response body is not parsed, the system only looks at HTTP status codes.

Any code other than 2xx is considered an error and the system will continue to repeat the notification.

Error handling

According to the REST architecture, high-level request processing errors are reported in the HTTP status code RFC 2068. The following HTTP codes are used in the universal payout API:

Code	Description
200	Successful or Conditionally Successful
400	Request parameters are invalid, request not processed
401	Token or signature not provided or invalid
403	Insufficient rights to complete the request
404	The resource with the requested id was not found
5xx	Request processing error

Detailed interpretation of the request processing result can be passed in the errorCode field of the requested (returned) object. If the request is processed and it is impossible to return a correct response, the API returns an Error object with detailed information about the error.

Important! Errors with 5xx codes can also occur if the request is successfully completed.

Important! In case of an error from the 5xx list, an unformatted response is possible.

If you receive an error from the 5xx list as a result of processing payment methods, especially the payment processing request, check the processing result using the payment information.

Error model

{
  "serviceName": "payout-api",
  "errorCode": "internal.error",
  "userMessage": "Описание ошибки для отображения пользователя",
  "description": "Описание ошибки",
  "traceId": "aa99e984dd230404",
  "dateTime": "2023-01-01T00:23:46+03:00",
  "cause": {
    "amount": ["Payout's amount is greater than maximum available"]
  }
}

Summary information about the error.

Parameter	✓\×	Type	Description
serviceName	✓	string	Service ID
errorCode	✓	ErrorCode	Error code
userMessage	✓	string	Description of the error for the user
description	✓	string	Error description
traceId	✓	string	Request Unique ID
dateTime	✓	dateTime	The date the error occurred in the format `YYYY-MM-DDThh:mm:ssTZD`
cause	×	map[string, array[string]]	Additional error details

ErrorCode model

The value of errorCode has a domain structure, separated by . (dot). From left to right, the level of the cause (system) that caused the error decreases.

Authorization level errors

Value	Description
auth.error	General authorization error
auth.failed	Authorization error: token/certificate not provided or not found
auth.forbidden	Access denied: no permissions to access the requested resource

Validation level errors

Value	Description
payout.bad.request	Invalid request: required parameters are missing or incorrect
payout.resource.exists	Resource already exists: the resource with the requested id already exists
payout.payment.not-found	Payment not found: payment for the requested id was not found
payout.provider.not-found	Provider not found: provider with the requested identifier was not found
validation.error	Request validation error, invalid JSON

Payment level errors

Value	Description
payout.provider.forbidden	Provider prohibited: payments to the specified provider are prohibited
payout.provider.unavailable	Provider unavailable: payments to the specified provider are temporarily unavailable
payout.billing.declined	Payment declined: the recipient's information system refused to accept the payment
payout.billing.timeout	Request timeout: no response received from recipient's information system

Financial and legislative risks level errors

Value	Description
payout.fraud.violated	Payment prohibited: violations of financial rules or fraud monitoring
payout.legislation.prohibited	Payment is prohibited in accordance with the requirements of the Russian legislation

General level errors

Value	Description
payout.insufficient-funds	Insufficient funds: insufficient funds on the partner's balance
payout.internal.error	Internal error
internal.error	Internal error

Test details

After joining the test environment and acquiring your agentId you can create and execute test payments in a "sandbox" - without interacting with your Bank. You can use the following options:

Create/Execute payment to any provider without additional parameters (but the specified below) results to success payment status.
Create/Execute payment to any provider with status control through customFields.
- for FAILED payment status (on create): "customFields.create_result": "<Any value != [success, in_progress]>", for example "customFields.create_result": "failed",
- for FAILED payment status (on execute): "customFields.execute_result": "<Any value != [success, in_progress]>", for example "customFields.execute_result": "failed",
- for IN_PROGRESS payment status (on execute): "customFields.execute_result": "in_progress",
Create/Execute payment with status control through preset requisites:

Provider	Payment status	Payment stage	Requisite	Value
bank-card-russia bank-card-russia-fio bank-card-russia-gph	COMPLETED	Проведение	`pan`	`2201380000000009`
bank-card-russia bank-card-russia-fio bank-card-russia-gph	FAILED	Создание	`pan`	`4444440000000004`
bank-card-russia bank-card-russia-fio bank-card-russia-gph	FAILED	Проведение	`pan`	`5555550000000002`
bank-card-russia bank-card-russia-fio bank-card-russia-gph	IN_PROGRESS	Проведение	`pan`	`2201380000000017`
sbp-b2c	COMPLETED	Execute	`bankId`	`sbp_bank_id_success`
sbp-b2c	FAILED	Create	`bankId`	`sbp_bank_id_create_failed`
sbp-b2c	FAILED	Execute	`bankId`	`sbp_bank_id_execute_failed`
sbp-b2c	IN_PROGRESS	Execute	`bankId`	`sbp_bank_id_execute_in_progress`
bank-card-token	COMPLETED	Execute	`account`	`token_success`
bank-card-token	FAILED	Create	`account`	`token_create_failed`
bank-card-token	FAILED	Execute	`account`	`token_execute_failed`
bank-card-token	IN_PROGRESS	Execute	`account`	`token_execute_in_progress`

customFields values have higher priority than preset values.

To test the whole payment flow with your Bank, please contact your Support Manager and you will be provided with special agentId.

Data models

Description of the data models used in the API.

Balance model

{
  "balance": {
    "currency": "RUB",
    "value": "1000000.00"
  },
  "overdraft": {
    "currency": "RUB",
    "value": "500000.00"
  },
  "available": {
    "currency": "RUB",
    "value": "1500000.00"
  }
}

Account balance information.

Parameter	✓\×	Type	Description
balance	×	Money	Current balance
overdraft	×	Money	Allowed excess balance
available	✓	Money	Total available limit

Money model

{
  "currency": "RUB",
  "value": "1000000.00"
}

Information about the amount indicating the currency.

Parameter	✓\×	Type	Description
currency	✓	Currency	Currency code
value	✓	string	Amount in number format with `.` (dot) separator and two digits after

Currency model

List of available currency codes according to ISO 4217 specification (alpha-3 code).

Value	Description
RUB	Russian ruble

Provider model

{
  "code" : "bank-card-russia",
  "name" : "Выплаты на карты банков РФ"
}

Brief information about the provider.

Parameter	✓\×	Type	Description
code	✓	ProviderCode	Provider unique identifier
name	✓	string	Provider name

ProviderInfo model

{
  "name": "Bank card payouts",
  "legalName": "",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "pan",
      "required": true,
      "description": "Unmasked card PAN",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3111453720",
  "contactDetails": {
    "address": "address",
    "phoneNumber": "8-800-111-22-33"
  }
}

Extended information about the provider.

Parameter	✓\×	Type	Description
name	✓	string	Provider name
legalName	✓	string	Legal name of the provider
amountLimits	✓	map[Currency, Limit]	A set of allowed amounts by available currencies
parameters	✓	set of Parameter	Parameters used when calling payment methods
inn	×	string	Provider's TIN
contactDetails	×	Contact	Provider contact details

Parameter model

{
  "extKey": "account",
  "required": true,
  "description": "QW user's account",
  "validationPattern": "7\\d{10}"
}

Description of the payment parameter for the provider.

Parameter	✓\×	Type	Description
extKey	✓	string	Parameter code
required	✓	boolean	Mandatory sign
description	✓	string	Parameter description
validationPattern	×	string	Fill pattern

Contact model

{
  "address": "Russia, 117648, Moscow, md. Chertanovo Severnoe, 1A, bldg. 1",
  "phoneNumber": "8-800-707-77-59"
}

Counterparty contact details.

Parameter	✓\×	Type	Description
address	×	string	Postal address
phoneNumber	×	string	Telephone number

CurrencyLimit model

{
  "currency": "RUB",
  "min": "1.00",
  "max": "600000.00"
}

Restrictions on the payment amount with currency indication.

Parameter	✓\×	Type	Description
currency	✓	Currency	Currency code
min	✓	string	Minimum allowed amount (inclusive)
max	✓	string	Maximum allowed amount (inclusive)

Limit model

{
  "min": "1.00",
  "max": "600000.00"
}

Restrictions on the amount of payment without specifying the currency.

Parameter	✓\×	Type	Description
min	✓	string	Minimum allowed amount (inclusive)
max	✓	string	Maximum allowed amount (inclusive)

PaymentPayload model

{
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234564543654321"
    }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

Parameters of the created payment

Parameter	✓\×	Type	Description
amount	✓	Money	Payment amount
recipientDetails	✓	RecipientDetails	Payment recipient's parameters
webhookUrl	×	string	Notification URL
customFields	×	map[string, string]	Additional options for accompanying a payment

RecipientDetails model

{
  "providerCode": "bank-card-russia",
  "fields": {
    "pan": "1234567890213456"
  }
}

Recipient's parameters (payout direction).

Parameter	✓\×	Type	Description
providerCode	✓	Provider.code	Provider unique identifier
fields	✓	map[Parameter.extKey, string]	Set of recipient parameters

ProviderCode model

List of possible provider codes.

Value	Description
bank-card-russia	Payouts to Russian cards
bank-card-russia-fio	Payouts to Russian cards with mandatory recipient's full name
bank-card-russia-gph	Payment to Russian cards by GPH contract
bank-card-token	Payouts to Russian cards by token
sbp-b2c	SBP payments
sbp-fio	SBP payments with mandatory recipient's full name

ProviderFields model

Information about payment parameters by provider.

Payouts to Russian cards `"providerCode": "bank-card-russia"`

{
  "providerCode": "bank-card-russia",
  "fields": {
    "pan": "4111111111111111"
  }
}

Parameter	✓\×	Type	Description
pan	✓	string	Recipient's card number
cardholder_name	×	string	Recipient's name
cardholder_lastname	×	string	Recipient's last name
description	×	string	Description of the service provided

For Signature header you can use a template:

{agentId}|{paymentId}|{amount.value}|{amount.currency}|bank-card-russia|{cardholder_lastname}|{cardholder_name}|{description}|{pan}

Use delimiter | to concatenate parameters.

If you don't send some optional parameters in a request, don't use them for a sign
For example, if you don't send parameter "3" in a request then you should use string "1|2|4" for a sign instead of "1|2||4".

Payouts to Russian cards with mandatory recipient's full name `"providerCode": "bank-card-russia-fio"`

{
  "providerCode": "bank-card-russia-fio",
  "fields": {
    "pan": "4111111111111111",
    "lastName": "Иванов",
    "firstName": "Иван"
  }
}

Parameter	✓\×	Type	Description
pan	✓	string	Recipient's card number
lastName	✓	string	Recipient's last name
firstName	✓	string	Recipient's name
middleName	×	string	Recipient's middle name
description	×	string	Description of the service provided

For Signature header you can use a template:

{agentId}|{paymentId}|{amount.value}|{amount.currency}|bank-card-russia-fio|{description}|{firstName}|{lastName}|{middleName}|{pan}

Payment to Russian cards by GPH contract `providerCode: "bank-card-russia-gph"`

{
  "providerCode": "bank-card-russia-gph",
  "fields": {
    "pan": "2201380000000009",
    "lastName": "Иванов",
    "firstName": "Иван",
    "purpose": "Выплата по договору ГПХ №2 от 01.01.2025, за оказанные услуги, за период 02.2025"
  }
}

Parameter	✓\×	Type	Description
pan	✓	string	Recipient's card number
lastName	✓	string	Recipient's last name
firstName	✓	string	Recipient's name
middleName	×	string	Recipient's middle name
purpose	✓	string	Purpose of the service provided

For Signature header you can use a template:

{agentId}|{paymentId}|{amount.value}|{amount.currency}|bank-card-russia-gph|{firstName}|{lastName}|{middleName}|{pan}|{purpose}

SBP payments `"providerCode": "sbp-b2c"`

{
  "providerCode": "sbp-b2c",
  "fields": {
    "account": "79098087755",
    "bankId": "100000000001"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	The recipient's phone number in international format without the `+` sign
bankId	✓	string	Beneficiary's bank identifier in SBP
description	×	string	Description of the service provided

For Signature header you can use a template:
{agentId}|{paymentId}|{amount.value}|{amount.currency}|sbp-b2c|{account}|{bankId}|{description}
Use delimiter | to concatenate parameters.

If you don't send some optional parameters in a request, don't use them for a sign
For example, if you don't send parameter "3" in a request then you should use string "1|2|4" for a sign instead of "1|2||4".

SBP payments `"providerCode": "sbp-fio"`

{
  "providerCode": "sbp-fio",
  "fields": {
    "account": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	The recipient's phone number in international format without the `+` sign
bankId	✓	string	Beneficiary's bank identifier in SBP
lastName	✓	string	Recipient's last name
firstName	✓	string	Recipient's name
middleName	×	string	Recipient's middle name
description	×	string	Description of the service provided

For Signature header you can use a template:

{agentId}|{paymentId}|{amount.value}|{amount.currency}|sbp-fio|{account}|{bankId}|{description}|{firstName}|{lastName}|{middleName}

Use delimiter | to concatenate parameters.
The middle name is required if available.

If you don't send some optional parameters in a request, don't use them for a sign
For example, if you don't send parameter "3" in a request then you should use string "1|2|4" for a sign instead of "1|2||4".

Payouts to Russian cards via token `"providerCode": "bank-card-token"`

{
  "providerCode": "bank-card-token",
  "fields": {
    "account": "17b985ce-5677-49f8-b88f-5ac2ef2cbc52"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Recipient's card token
cardholder_name	×	string	Recipient's name
cardholder_lastname	×	string	Recipient's last name
description	×	string	Description of the service provided

For Signature header you can use a template:

{agentId}|{paymentId}|{amount.value}|{amount.currency}|bank-card-token|{account}|{cardholder_lastname}|{cardholder_name}|{description}

BillingDetails model

{
  "transactionId": "20221101000019",
  "rrn": "A123456",
  "accountNumber": "4950001122",
  "accountInfo": "Ivanov I.P.",
  "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
}

Additional information from the payee billing system.

Parameter	✓\×	Type	Description
transactionId	×	string	Payment ID on the recipient's side
rrn	×	string	Payment acceptance code on the recipient's side
accountNumber	×	string	Account number for payment confirmation
accountInfo	×	string	Additional information for payment confirmation
receiptUrl	×	string	URL address to document with payment information

Payment model

{
  "paymentId": "0123456789",
  "creationDateTime": "2023-01-17T15:05:51+03:00",
  "expirationDateTime": "2023-01-17T15:35:51+03:00",
  "status": {
    "value": "READY",
    "changedDateTime": "2023-01-17T15:05:51+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "2.00"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234564543654321"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  },
  "billingDetails": {
    "transactionId": "20221101000019",
    "rrn": "A123456",
    "accountNumber": "4950001122",
    "accountInfo": "Ivanov I.P.",
    "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
  }
}

Detailed information about the payment with the current status.

Parameter	✓\×	Type	Description
paymentId	✓	string	Unique payment identifier
creationDateTime	✓	dateTime	Payment creation date in the format `YYYY-MM-DDThh:mm:ssTZD`
expirationDateTime	✓	dateTime	Payment expiration date in the format `YYYY-MM-DDThh:mm:ssTZD`
status	✓	Status	Payment status
amount	✓	Money	Payment amount
recipientDetails	✓	RecipientDetails	Payment recipient's parameters
commission	✓	Money	Calculated commission amount for payment
webhookUrl	×	string	Notification URL
customFields	×	map[string, string]	Additional options for accompanying a payment
billingDetails	×	BillingDetails	Additional information from the payee billing system

Status model

{
  "value": "READY",
  "changedDateTime": "2023-01-17T15:05:51+03:00"
}

Detailed information about the payment status.

Parameter	✓\×	Type	Description
value	✓	StatusCode	Payment status
changedDateTime	✓	dateTime	Payment status change date in the format `YYYY-MM-DDThh:mm:ssTZD`
errorCode	×	StatusErrorCode	Error code
errorMessage	×	string	Error description

StatusCode model

List of possible payment statuses.

Value	Description
CREATED	Payment created but not ready to be processed
READY	Payment created and ready to be processed
EXPIRED	Payment has expired
IN_PROGRESS	Payment in progress
FAILED	Payment failed
COMPLETED	Payment completed successfully

StatusErrorCode model

List of possible error codes.

Value	Description
INTERNAL_ERROR	Internal error
INSUFFICIENT_FUNDS	Not processed due to lack of funds
BILLING_DECLINED	Payment declined by recipient's billing
FRAUD_SUSPECTED	Rejected due to suspicion of fraud monitoring
LIMIT_ERROR	Rejected due to exceeding limits
EXPIRED	Payment has expired

Webhook model

{
  "agentId": "acme",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
    "value": "FAILED",
    "changedDateTime": "2023-01-18T13:00:28Z",
    "errorCode": "INTERNAL_ERROR",
    "errorMessage": "Some reason"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId": "20221101000019",
    "rrn": "A123456",
    "accountNumber": "4950001122",
    "accountInfo": "Ivanov I.P.",
    "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
  }
}

Notification of a change in payment status for a partner.

Parameter	✓\×	Type	Description
agentId	✓	string	Agent unique identifier
paymentId	✓	string	Unique payment identifier
status	✓	Status	Payment status
amount	✓	Money	Payment amount
billingDetails	×	BillingDetails	Additional information from the payee billing system

General Information

API overview

HTTP methods

Content type

Data transfer methods

Idempotency

Authorization

Authorization using Bearer token

Versioning

API endpoints

Test environment

Production environment

Service methods

Main account balance

Parameters

Response

Balance of all accounts

Parameters

Response

List of providers

Parameters

Response

Provider information

Parameters

Response

Payment methods

Creating a payment

Parameters

Response

Payment request signature

Create key pair

Transfer public key

Request signature calculation

Payment processing

Parameters

Response

List of payments

Parameters

Response

Payment information

Parameters

Response

Notifications

Payment status notification

Parameters

Request signature calculation algorithm

Response

Error handling

Error model

ErrorCode model

Authorization level errors

Validation level errors

Payment level errors

Financial and legislative risks level errors

General level errors

Test details

Data models

Balance model

Money model

Currency model

Provider model

ProviderInfo model

Parameter model

Contact model

CurrencyLimit model

Limit model

PaymentPayload model

RecipientDetails model

ProviderCode model

ProviderFields model

Payouts to Russian cards "providerCode": "bank-card-russia"

Payouts to Russian cards with mandatory recipient's full name "providerCode": "bank-card-russia-fio"

Payment to Russian cards by GPH contract providerCode: "bank-card-russia-gph"

SBP payments "providerCode": "sbp-b2c"

SBP payments "providerCode": "sbp-fio"

Payouts to Russian cards via token "providerCode": "bank-card-token"

BillingDetails model

Payment model

Status model

StatusCode model

Payouts to Russian cards `"providerCode": "bank-card-russia"`

Payouts to Russian cards with mandatory recipient's full name `"providerCode": "bank-card-russia-fio"`

Payment to Russian cards by GPH contract `providerCode: "bank-card-russia-gph"`

SBP payments `"providerCode": "sbp-b2c"`

SBP payments `"providerCode": "sbp-fio"`

Payouts to Russian cards via token `"providerCode": "bank-card-token"`