Interaction with the service is carried out according to the request-response scheme. Requests are sent in JSON format using the POST method. For secure access to the service, a JWT token is used in all methods, which is generated by a GET request to /public/login, accessToken parameter. The project has the property of Idempotency. In case of a network error, the response to a duplicate request will be similar to the first one. However, the duplicate request will not be processed. Idempotency is ensured by passing a unique value in the x-req-id header in the request.
Mobile Cashier API (1.1.7)
📄 Download OpenAPI specificationAPI description is provided in OpenAPI 3.0.0 format.
General Information
Order Statuses
| Status | Description | Final |
|---|---|---|
CREATED |
Order created | Yes |
DECLINED |
Order declined | Yes |
EXPIRED |
Order validity time expired | Yes |
IN_PROCESS |
Order status is not determined, clarification required | No |
PAYOUT_IN_PROGRESS |
Order status is not determined, clarification required | No |
QRCDATA_IN_PROGRESS |
Order status is not determined, clarification required | No |
SBP_ACCEPTED |
Successful payment via SBP (Fast Payment System) | Yes |
CHARGED |
Funds charged | Yes |
QRCDATA_CREATED |
QR code generation successful | No |
PAID |
Payout completed | Yes |
REFUNDED |
Order refunded | Yes |
Notifications Service
Notifications (webhook, callback) are POST requests sent by the system upon order status change to the address specified in the CallbackUrl parameter of the order method. The notification format corresponds to the response to the order data request. The system will make repeated attempts to send notifications until receiving http-code 200 or timeout expiration.
The http request header contains the payment-sign parameter - a signature, the result of signing the original notification body (Body from http request) with a private key, in base64 encoding.
For signature validation, use the public key:
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2pVj7Lz0DBfpQECtW5lHktgv+
xEYxcLG1lmQGl8k0G2xGrLSi2oy+lFl8uCqUc7QpY5HLnfY/+HzpZhSz3gJJ
PiMwEd7bm6L5VzQ6jYdS+9p8uBwQ+xYJG2pM7LkV2Y5W7gANq4/+q6pJ+pHGH5E
xtJqVXhbr1v1MrCUMBIz1t8QIDAQAB
-----END PUBLIC KEY-----
Example for signature verification during integration using openssl tools. Execute command in command line:
Decode base64:
echo "base64signature" | base64 -d > catsign.txt
Verify signature:
openssl dgst -sha256 -verify PublicStage.key -signature catsign.txt callback.txt
Where
catsign.txt is the signature from Payment-Sign header, PublicStage.key is the public key, callback.txt is the callback body.
In case of successful verification, you will get the message "Verified OK".
Important:
Order status check is mandatory after the order lifetime expires. Notification delivery is not guaranteed 30 minutes after order creation.
Payment Form
The scenario with entering card data on PaymentForm does not require TSP compliance with PCIDSS security requirements, unlike the scenario with entering card data on the TSP side.
Opening the payment form is performed by a POST request to the address:
https://domain/payment/ExternalOrderID
where:
- payment - fixed value
- domain - address for sending requests
- ExternalOrderID - order number received in response to the payment form creation method
Opening the form with a POST request allows passing additional parameters, such as the address for redirect after payment.
To call the form with redirect capability:
- Use native html form with POST method
- In action specify form URL supporting redirect functionality
- Specify redirect links in two hidden fields (successUrl, failUrl)
- In enctype specify application/x-www-form-urlencoded
- Submit native form with standard submit call (POST request with redirect)
Example:
<form action="https://domain/paymentWithRedirect/ExternalOrderID" method="POST" enctype="application/x-www-form-urlencoded">
<input type="hidden" name="successUrl" value="https://merchant.site/success">
<input type="hidden" name="failUrl" value="https://merchant.site/fail">
<input type="submit" value="Pay">
</form>
Authorization
GET
/public/login
System Access
Request Body Schema: application/json
loginrequired
string
User login
passwordrequired
string
User password
Responses
200 Successful operation
400 Bad Request
401 Unauthorized
Request samples
Response samples
{
"login": "string",
"password": "string"
}
{
"accessToken": "string",
"permissions": [
"string"
]
}
Orders
GET
/order
Get Orders List
Authorization Required
Authorization-Token
Query Parameters
orderDateFrom
string($date)
Order date from
orderDateTo
string($date)
Order date to
offset
integer
Offset for pagination
count
integer
Number of records to return
Responses
200 Success
400 Bad Request
401 Unauthorized
Response samples
[
{
"id": "string",
"status": "CREATED",
"merchantOrderId": "string",
"orderAmount": 100,
"orderCurrency": "RUB",
"paymentCurrency": "RUB",
"created": "2023-01-01T10:00:00.000Z"
}
]
POST
/order
Create Order
You can create an order in two ways:
- Using orderAmount field
- You pass the order amount in the selected currency
- After creation, the amount is automatically converted to rubles, and payment will be accepted in rubles
- All commissions are included in the final amount
- The amount must be specified in minimum currency units (kopecks/cents/eurocents, etc.)
- Using paymentAmount field
- Payment amount remains in rubles
- System converts it to currency and deducts commissions
- Amount must be specified in kopecks
Important:
- To create a payout order, you must specify type "PayOut"
- When creating an income order (e.g., for sale), the type can be omitted; "PayIn" will be used by default
Authorization Required
Authorization-Token
Request Body Schema: application/json
merchantOrderIdrequired
string
Unique identifier for the order in the merchant system
orderAmountrequired
integer
Order amount in minimum currency units (kopecks)
orderCurrencyrequired
string
Order currency code (ISO 4217)
tspIdrequired
integer
TSP identifier in the system
description
string
Order description
callbackUrl
string
URL for order status notifications
Responses
200 Successful operation
400 Bad Request
401 Unauthorized
Request samples
Response samples
{
"merchantOrderId": "merchantOrderId",
"orderAmount": 100,
"orderCurrency": "RUB",
"tspId": 1,
"description": "comment",
"callbackUrl": "callback.com"
}
{
"success": true,
"description": "string",
"order": {
"id": "string",
"status": "CREATED",
"externalOrderId": "string",
"merchantOrderId": "string",
"orderAmount": 100,
"orderCurrency": "RUB",
"paymentCurrency": "RUB",
"type": "payIn"
}
}
GET
/order/{id}
Get Order Data
Authorization Required
Authorization-Token
Path Parameters
idrequired
integer
Order identifier in the system
Responses
200 Success
400 Not Found
403 Forbidden
Response samples
{
"success": true,
"description": "string",
"order": {
"id": "string",
"status": "CREATED",
"externalOrderId": "string",
"merchantOrderId": "string",
"orderAmount": 100,
"orderCurrency": "RUB",
"paymentCurrency": "RUB",
"created": "2023-01-01T10:00:00.000Z",
"type": "payIn"
}
}
POST
/order/{id}/refund
Refund Order
Authorization Required
Authorization-Token
Path Parameters
idrequired
integer
Order identifier in the system
Request Body Schema: application/json
amount
integer
Optional parameter. If absent, refund will be for the full amount.
Responses
200 Success
400 Not Found
403 Forbidden
Request samples
Response samples
{
"amount": 300
}
{
"success": true,
"description": "string",
"order": {
"id": "string",
"status": "Refunded"
}
}
GET
/status/{id}
Order Status
Get current order status
Path Parameters
idrequired
integer <unit64>
Order identifier in the system
Responses
200 Success
403 Forbidden
500 Internal Server Error
Response samples
{
"success": true,
"description": "string",
"order": {
"id": "string",
"status": "CHARGED",
"merchantOrderId": "merchant_order_123",
"orderAmount": 100,
"orderCurrency": "RUB",
"paymentCurrency": "RUB",
"created": "2023-01-01T10:00:00.000Z"
}
}
SBP (Fast Payment System)
POST
/order/qrcData/{id}
qrcData - QR Code Registration in SBP
Authorization Required
Authorization-Token
Path Parameters
idrequired
integer
Order identifier in the system
Responses
200 Success
400 Not Found
403 Forbidden
500 Internal Server Error
Response samples
{
"success": true,
"description": "string",
"order": {
"qrcId": "string",
"payload": "string",
"externalOrderId": "string"
}
}
POST
/order/sbpPayout/{id}
SBP Payout
SBP (Fast Payment System)
SBP is Russia's national fast payment system that enables instant transfers between different banks using phone numbers or bank details.
Authorization Required
Authorization-Token
Path Parameters
idrequired
integer
Order identifier in the system
Request Body Schema: application/json
accountNumberrequired
string
Recipient phone number
bankIdrequired
integer
Bank identifier
firstName
string
Recipient first name
lastName
string
Recipient last name
middleName
string
Recipient middle name
Responses
200 Success
400 Bad Request
403 Forbidden
500 Internal Server Error
Request samples
Response samples
{
"accountNumber": 79011234567,
"bankId": 100000000001,
"firstName": "John",
"lastName": "Doe",
"middleName": "William"
}
{
"success": true,
"description": "string",
"order": {
"externalOrderId": "string",
"status": "PAYOUT_IN_PROGRESS"
}
}
GET
/bankList
Get Bank List for Payout
Responses
200 Success
Response samples
{
"BankList": [
{
"BankId": 100000000001,
"BankName": "Gazprombank"
}
]
}
SberPay
POST
/order/sberPay/{id}
SberPay Payment
Authorization Required
Authorization-Token
Path Parameters
idrequired
integer
Order identifier in the system
Request Body Schema: application/json
BackUrl
string
Address for redirect after payment
phoneNumber
string
Phone number for sending push notification to transition to SBOL
Responses
200 Success
500 Internal Server Error
Request samples
Response samples
{
"BackUrl": "https://merchant.site/success",
"phoneNumber": "+79123456789"
}
{
"success": true,
"description": "string",
"order": {
"redirectUrl": "https://sberbank.ru/pay/...",
"status": "IN_PROCESS"
}
}
Card Methods
POST
/order/cardPayout/{id}
Card Payout
Authorization Required
Authorization-Token
Path Parameters
idrequired
integer
Order identifier in the system
Request Body Schema: application/json
CardNumberrequired
string
Recipient card number
Responses
200 Success
400 Bad Request
403 Forbidden
Request samples
Response samples
{
"CardNumber": "4111111111111111"
}
{
"success": true,
"description": "Payout initiated successfully",
"order": {
"id": "string",
"status": "PAYOUT_IN_PROGRESS"
}
}
POST
/paymentFormRequest
Payment Form Request
Create payment form for card payment
Authorization Required
Authorization-Token
Request Body Schema: application/json
OrderIdrequired
string
Order index in Payment API
Responses
200 Successful operation
Request samples
Response samples
{
"OrderId": "ExternalOrderId"
}
{
"success": true,
"description": "Form created successfully",
"paymentUrl": "https://payment.domain.com/form/12345"
}
POST
/charge
Charge Funds
In subsequent requests, externalOrderId should be passed in the OrderId field.
Authorization Required
None or None or None
Request Body Schema: application/json
OrderIdrequired
string
Order index in Payment API
Responses
200 Successful operation
Request samples
Response samples
{
"OrderId": "ExternalOrderId"
}
{
"success": true,
"description": "Charge successful",
"order": {
"id": "12345",
"status": "CHARGED",
"externalOrderId": "ExternalOrderId"
}
}
POST
/void
Void Order
In subsequent requests, externalOrderId should be passed in the OrderId field.
Authorization Required
None or None or None
Request Body Schema: application/json
OrderIdrequired
string
Order index in Payment API
Responses
200 Successful operation
Request samples
Response samples
{
"OrderId": "ExternalOrderId"
}
{
"success": true,
"description": "Void successful",
"order": {
"id": "12345",
"status": "VOIDED",
"externalOrderId": "ExternalOrderId"
}
}