General Information

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

Bank cards
Electronic wallets
Faster Payments System (SBP)
Legal entity bank account
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, two types of authorization are available:

Using Bearer Token
Using a client certificate

Authorization using Bearer token

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://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>.

Authorization using a client certificate

GET /partner/payout/v2/agents/acme HTTP/1.1
Accept: application/json
Host: private-api.qiwi.com

curl -X GET \
     --key private.key \
     --cert certificate.crt \
     --cacert ca.pem \
     https://private-api.qiwi.com/partner/payout/v2/agents/acme/providers

When using a client certificate, all partner requests, when calling methods, are supplemented by transferring a certificate and a private key known only to the partner.

In this case, the Authorization header is not formed on the client side and the request is accompanied by a digital certificate in the X.509 v3 format, according to the specification RFC 5280.

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://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://api-test.qiwi.com/`
RSA	Certificate	`https://private-api-test.qiwi.com/`
ГОСТ	Token	`https://api-gost-test.qiwi.com/`
ГОСТ	Certificate	`https://private-api-gost-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://api.qiwi.com/`
RSA	Certificate	`https://private-api.qiwi.com/`
ГОСТ	Token	`https://api-gost.qiwi.com/`
ГОСТ	Certificate	`https://private-api-gost.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: api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://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

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: api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://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

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: api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://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

Response

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

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

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/qiwi-wallet HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: api.qiwi.com

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

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

Response

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

{
  "name": "Qiwi Wallet",
  "legalName": "Qiwi Bank JSC",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "account",
      "required": true,
      "description": "QW user's account",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3123011520",
  "contactDetails": {
    "address": "Russia, 117648, Moscow, md. Chertanovo Severnoe, 1A, bldg. 1",
    "phoneNumber": "8-800-707-77-59"
  }
}

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>
Host: api.qiwi.com

{
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789 \
     -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "recipientDetails": {
              "providerCode": "qiwi-wallet",
              "fields": {
                "account": "79010001122"
              }
            },
            "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
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

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": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "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 processing

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

curl -X POST \
     -H "Authorization: Bearer <Token-Value>" \
     https://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

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": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "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: api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://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

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": "qiwi-wallet",
      "fields": {
        "account": "79010001122"
      }
    },
    "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": "qiwi-wallet",
      "fields": {
        "account": "79010001122"
      }
    },
    "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: api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://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

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": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "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
QIWI-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 "QIWI-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
QIWI-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 QIWI-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 QIWI-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 certificate 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

For test payment requests, use the following datasets:

For providers bank-card-russia, self-employed-bank-card, self-employed-bank-card-tax-payment, bank-card-ruslom:
- Card number: 4874154455550061,
- Card number for COMPLETED payment status: 1000000000000001,
- Card number for FAILED payment status: 1000000000000002,
- Card number for IN_PROGRESS payment status: 1000000000000003.
For providers bank-card-token, self-employed-card-token:
- Card number token: 969cb317-ef77-4a4d-8977-0d30c5d89e3d,
- Card number token for COMPLETED payment status: taccount-case-test-resp-success00000,
- Card number token for FAILED payment status: taccount-case-test-resp-failed000000,
- Card number token for IN_PROGRESS payment status: taccount-case-test-resp-suspended000.
For payments to the self-employed for providers self-employed-bank-card, self-employed-card-token, and self-employed-bank-card-tax-payment:
- TIN: 123456789012.
For payments to the self-employed for recyclable materials provider self-employed-bank-card-recycling:
- TIN: 123456789012.
For SBP payments to providers sbp-b2c, sbp-mfo, and self-employed-sbp:
- Phone number: 70070310009,
- Payee's bank: 1crt88888881,
- Amount of payment: 10007.03,
- Recipient's last name: Петров,
- Recipient's name: Петр,
- Recipient's patronymic: Петрович.
For recycling SBP payments to provider sbp-recycling
- Phone number: 70070310009,
- Payee's bank: 1crt88888881,
- Amount of payment: 10007.03,
- Recipient's last name: Петров,
- Recipient's name: Петр,
- Recipient's patronymic: Петрович,
- Acceptance certificate or other description: ПСА 123.

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" : "qiwi-wallet",
  "name" : "Qiwi кошелек"
}

Brief information about the provider.

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

ProviderInfo model

{
  "name": "Qiwi Wallet",
  "legalName": "Qiwi Bank JSC",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "account",
      "required": true,
      "description": "QW user's account",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3123011520",
  "contactDetails": {
    "address": "Russia, 117648, Moscow, md. Chertanovo Severnoe, 1A, bldg. 1",
    "phoneNumber": "8-800-707-77-59"
  }
}

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": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "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": "qiwi-wallet",
  "fields": {
    "account": "79010001122"
  }
}

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-token	Payouts to Russian cards by token
self-employed-bank-card	Payouts to cards for the self-employed
self-employed-card-token	Payouts to cards for the self-employed by token
self-employed-bank-card-tax-payment	Payouts to cards for the self-employed with tax payment
self-employed-bank-card-recycling	Payouts to cards for the self-employed for recyclable materials
self-employed-bank-card-qmm	Payouts to QIWI Mir Metal cards for the self-employed
self-employed-sbp	SBP payments for the self-employed with tax registration
qiwi-wallet	Payouts to QIWI Wallet
wl-topup	Replenishment of the White Label product client account
bank-card-ruslom	Payouts to cards for scrap metal
bank-card-ruslom-qmm	Payouts to QIWI Mir Metal cards for scrap metal
sbp-b2c	SBP payments
sbp-mfo	SBP payments with full name verification for MFIs
sbp-recycling	Recycling SBP payments with required description
legal-entity-bank-account	Payouts to legal entity bank account

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

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

{
  "providerCode": "bank-card-token",
  "fields": {
    "account": "ac465705-16f9-477d-a194-6641e0e8e90e"
  }
}

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

Payouts to cards for the self-employed `"providerCode": "self-employed-bank-card"`

{
  "providerCode": "self-employed-bank-card",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Recipient's card number
description	✓	string	Description of the service provided
inn	✓	string	TIN of the self-employed
incomeType	✓	enum	Source of income (`FROM_LEGAL_ENTITY`, `FROM_INDIVIDUAL`)
name	×	string	Recipient's name
lastname	×	string	Recipient's last name
customerInn	×	string	TIN of the organization paying for the service
customerOrganization	×	string	Name of the organization paying for the service

Payouts to cards for the self-employed by token `providerCode: "self-employed-card-token"`

{
  "providerCode": "self-employed-card-token",
  "fields": {
    "inn": "111111111111",
    "account": "ac465705-16f9-477d-a194-6641e0e8e90e",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Recipient's card number token
description	✓	string	Description of the service provided
inn	✓	string	TIN of the self-employed
incomeType	✓	enum	Source of income (`FROM_LEGAL_ENTITY`, `FROM_INDIVIDUAL`)
name	×	string	Recipient's name
lastname	×	string	Recipient's last name
customerInn	×	string	TIN of the organization paying for the service
customerOrganization	×	string	Name of the organization paying for the service

Payouts to cards for the self-employed with tax payment `providerCode: "self-employed-bank-card-tax-payment"`

{
  "providerCode": "self-employed-bank-card-tax-payment",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Recipient's card number
description	✓	string	Description of the service provided
inn	✓	string	TIN of the self-employed
incomeType	✓	enum	Source of income (`FROM_LEGAL_ENTITY`, `FROM_INDIVIDUAL`)
name	×	string	Recipient's name
lastname	×	string	Recipient's last name
customerInn	×	string	TIN of the organization paying for the service
customerOrganization	×	string	Name of the organization paying for the service

Payouts to cards of the self-employed for recyclable materials `providerCode: "self-employed-bank-card-recycling"`

{
  "providerCode": "self-employed-bank-card-recycling",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "ПСА 1001",
    "firstName": "Имя получателя",
    "lastName": "Фамилия получателя",
    "middleName": "Отчество получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Recipient's card number
description	✓	string	Acceptance act or other description of the service provided
inn	✓	string	TIN of the self-employed
incomeType	✓	enum	Source of income (`FROM_LEGAL_ENTITY`, `FROM_INDIVIDUAL`)
firstName	✓	string	Recipient's first name
lastName	✓	string	Recipient's last name
middleName	×	string	Recipient's middle name
customerInn	×	string	TIN of the organization paying for the service
customerOrganization	×	string	Name of the organization paying for the service

Payouts to QIWI Mir Metal cards for the self-employed `"providerCode": "self-employed-bank-card-qmm"`

{
  "providerCode": "self-employed-bank-card-qmm",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Recipient's card number (only Qiwi Mir Metal cards)
description	✓	string	Description of the service provided
inn	✓	string	TIN of the self-employed
incomeType	✓	enum	Source of income (`FROM_LEGAL_ENTITY`, `FROM_INDIVIDUAL`)
name	×	string	Recipient's name
lastname	×	string	Recipient's last name
customerInn	×	string	TIN of the organization paying for the service
customerOrganization	×	string	Name of the organization paying for the service

SBP payments for the self-employed with tax registration `providerCode: "self-employed-sbp"`

{
  "providerCode": "self-employed-sbp",
  "fields": {
    "inn": "111111111111",
    "account": "79098087755",
    "bankId": "100000000001",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}

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
inn	✓	string	TIN of the self-employed
incomeType	✓	enum	Source of income (`FROM_LEGAL_ENTITY`, `FROM_INDIVIDUAL`)
name	×	string	Recipient's name
lastname	×	string	Recipient's last name
customerInn	×	string	TIN of the organization paying for the service
customerOrganization	×	string	Name of the organization paying for the service

Payouts to QIWI Wallet `providerCode: "qiwi-wallet"`

{
  "providerCode": "qiwi-wallet",
  "fields": {
    "account": "79123456789",
    "comment": "Comment"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Phone number
comment	×	string	Comment

Replenishment of the White Label product client account `providerCode: "wl-topup"`

{
  "providerCode": "wl-topup",
  "fields": {
    "account": "21646",
    "product_id": "company-id"
  }
}

Parameter	✓\×	Type	Description
account	✓	string	Client ID in WL
product_id	✓	string	Product ID in WL

Payouts to cards for scrap metal `"providerCode": "bank-card-ruslom"`

{
  "providerCode": "bank-card-ruslom",
  "fields": {
      "pan": "4111111111111111",
      "lastname": "Фамилия получателя",
      "name": "Имя получателя",
      "patronymic": "Отчество получателя",
      "acceptanceCertificate": "Номер приемо-сдаточного акта"
  }
}

Parameter	✓\×	Type	Description
pan	✓	string	Recipient's card number
name	✓	string	Recipient's name
lastname	✓	string	Recipient's last name
patronymic	×	string	Recipient's patronymic
acceptanceCertificate	✓	string	Acceptance certificate number

Payouts to QIWI Mir Metal cards for scrap metal `"providerCode": "bank-card-ruslom-qmm"`

{
  "providerCode": "bank-card-ruslom-qmm",
  "fields": {
      "pan": "4111111111111111",
      "lastname": "Фамилия получателя",
      "name": "Имя получателя",
      "patronymic": "Отчество получателя",
      "acceptanceCertificate": "Номер приемо-сдаточного акта"
  }
}

Parameter	✓\×	Type	Description
pan	✓	string	Recipient's card number (only Qiwi Mir Metal cards)
name	✓	string	Recipient's name
lastname	✓	string	Recipient's last name
patronymic	×	string	Recipient's patronymic
acceptanceCertificate	✓	string	Acceptance certificate number

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

SBP payments with full name verification for MFIs `"providerCode": "sbp-mfo"`

{
  "providerCode": "sbp-mfo",
  "fields": {
    "phone": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван",
    "middleName": "Иванович"
  }
}

Parameter	✓\×	Type	Description
phone	✓	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 patronymic

SBP payments for recycling `"providerCode": "sbp-recycling"`

{
  "providerCode": "sbp-recycling",
  "fields": {
    "phone": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван",
    "middleName": "Иванович",
    "description": "ПСА 123"
  }
}

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 patronymic
description	×	string	Payment acceptance certificate or other description

Payouts to legal entity bank account `providerCode: "legal-entity-bank-account"`

{
  "providerCode": "legal-entity-bank-account",
  "fields": {
    "account": "50537928100000002463",
    "bik": "304754657",
    "inn": "1111111111",
    "kpp": "389244830",
    "name": "Qiwi PLC",
    "remarks": "Payment for services #454"
  }
}

Parameter	Type	Description
account	string	Required. Recipient's bank account
bik	string	Required. Recipient's bank identification code
inn	string	Required. Recipient's legal entity INN
name	string	Required. Recipient's legal entity name
remarks	string	Required. Payment purpose
kpp	string	Recipient's legal entity KPP (required for LLC)

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": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "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

Authorization using a client certificate

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 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 by token "providerCode": "bank-card-token"

Payouts to cards for the self-employed "providerCode": "self-employed-bank-card"

Payouts to cards for the self-employed by token providerCode: "self-employed-card-token"

Payouts to cards for the self-employed with tax payment providerCode: "self-employed-bank-card-tax-payment"

Payouts to cards of the self-employed for recyclable materials providerCode: "self-employed-bank-card-recycling"

Payouts to QIWI Mir Metal cards for the self-employed "providerCode": "self-employed-bank-card-qmm"

SBP payments for the self-employed with tax registration providerCode: "self-employed-sbp"

Payouts to QIWI Wallet providerCode: "qiwi-wallet"

Replenishment of the White Label product client account providerCode: "wl-topup"

Payouts to cards for scrap metal "providerCode": "bank-card-ruslom"

Payouts to QIWI Mir Metal cards for scrap metal "providerCode": "bank-card-ruslom-qmm"

SBP payments "providerCode": "sbp-b2c"

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

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

Payouts to cards for the self-employed `"providerCode": "self-employed-bank-card"`

Payouts to cards for the self-employed by token `providerCode: "self-employed-card-token"`

Payouts to cards for the self-employed with tax payment `providerCode: "self-employed-bank-card-tax-payment"`

Payouts to cards of the self-employed for recyclable materials `providerCode: "self-employed-bank-card-recycling"`

Payouts to QIWI Mir Metal cards for the self-employed `"providerCode": "self-employed-bank-card-qmm"`

SBP payments for the self-employed with tax registration `providerCode: "self-employed-sbp"`

Payouts to QIWI Wallet `providerCode: "qiwi-wallet"`

Replenishment of the White Label product client account `providerCode: "wl-topup"`

Payouts to cards for scrap metal `"providerCode": "bank-card-ruslom"`

Payouts to QIWI Mir Metal cards for scrap metal `"providerCode": "bank-card-ruslom-qmm"`

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

SBP payments with full name verification for MFIs `"providerCode": "sbp-mfo"`

SBP payments for recycling `"providerCode": "sbp-recycling"`

Payouts to legal entity bank account `providerCode: "legal-entity-bank-account"`