RU | EN
API docs by Redocly

API of the Mobile Cashier application (1.1.7)

Download OpenAPI specification:Download

The API description is provided in OpenAPI 3.0.0 format.

General Information

Interaction with the service follows a request-response scheme. Requests are sent in JSON format using the POST method. Secure access to all methods in the service is provided using a JWT token, which is generated by the POST request to /public/login, accessToken parameter. The project supports idempotency. In case of a network error, the response to a duplicate request will be identical to the first one. And the duplicate request will not be processed. Idempotency is ensured within a 60-minute time interval by passing a unique value in the x-req-id header.

Order Statuses

Status Description Final
CREATED Order created Yes
DECLINED Order declined Yes
EXPIRED Order validity time has expired Yes
IN_PROCESS Order status is not determined, clarification is needed No
PAYOUT_IN_PROGRESS Order status is not determined, clarification is needed No
QRCDATA_IN_PROGRESS Order status is not determined, clarification is needed No
IPS_ACCEPTED Successful payment via IPS Yes
CHARGE_IN_PROGRESS Fund debit transaction has started No
CHARGE_DECLINED Fund debit has been declined No
CHARGED Funds have been debited Yes
QRCDATA_CREATED QR code retrieval was successful No
PAID Payout has been made Yes
REFUNDED Order has been refunded Yes
PARTIALLY_REFUNDED Order has been partially refunded Yes
AUTHORIZATION Hold transaction has started No
AUTHORIZED Order has been authorized Yes
VOID_IN_PROGRESS Hold reversal transaction has started No
VOID_DECLINED Hold reversal has been declined No
VOIDED Funds have been released Yes
PRE_AUTHORIZED_3DS Awaiting 3-D Secure authentication results No

Notification Service

Notifications (webhook, callback) are POST requests sent by the system upon a change in the order status 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 retry sending notifications until it receives an HTTP 200 code or the time limit expires. The payment-sign parameter is passed in the HTTP request header - a signature, which is the result of signing the raw notification body (Body from the HTTP request) with the private key, encoded in base64. To validate the signature, you must use the public key:

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtlD5ORxXDUgnnD9Ri2IB
UcT2Ru1fMi9kub8errQdLaXdFRDZJ1mNHlMJx+CHkhM5GNkMmidAhPcYRs4h/yIb
YLiRSsR+Zl6krjcrEvrTIZ1BySNAxEuCzWGFM27Ef01xNOSPEgtptAmop6vRuaiS
ha2vB5rHN1hSks1td/7xDcFG+C4cnDsTYp39rUvSSMtkW6FCbBoxNPrNOSlZGykx
OFBhOYd/uOK4z/zFSy07f4rA32KNn3zJE5eb6tzNMRNa6lOL96x0OYzw/P6oaS5b
sugVehAM1TGBCzm4Xmz1VZVBhxd3V7VoJuf/0C0W2Yfer+E/G0s3DDWmjzqhbvrc
Eb0y1kOZn4Z39jswv5Bkk8NyqHfNe0dE4pX+dSnfhC/9J5xFZy/CknclEM/0waY8
36iYIy+MaRsQdWXjbvP1AVk/yq2RlXCaOnK7GPvxAP1qjcgt56cGUOks9H9X6lba
PcJd+KDWde1aZZJLUpxu7JDIVTruDy/KrxDtJYi7Mz40Y6pnsKXzPHzVr0km9LI9
zK1j24OS1RIbO2fMM9D2zNQnSUV//aR+/xb7W2UgL2L0GRl7nDzqQL2dLvStHG9O
yUtnH5R/hPuIZqIDZx1N52F1JwArfDY0j9t5suAqN0VXJe2N77cYJ0x2LDeg+rLl
KsdjLKRDtKpXormCUTs/V+0CAwEAAQ==
-----END PUBLIC KEY-----

An example of signature verification using openssl tools. Run the following command in the command line:

Decode base64:

 certutil -decode catsign.txt sign.txt.dec

Verify the signature:

openssl dgst -sha1 -verify PublicStage.key -signature sign.txt.dec callback.txt

Where catsign.txt is the signature from the Payment-Sign header, PublicStage.key is the public key, callback.txt is the callback body.

If verification is successful, the message 'Verified OK' will appear.

Checking the order status via get is mandatory after the order's lifetime expires. Notification may be delivered in 30 minutes after order creation, but not guaranteed.

Payment Form

The scenario involving entering card details on the PaymentForm does not require the Merchant to comply with PCIDSS requirements, unlike the scenario with entering card data on the Merchant's side.

The payment form is opened via POST request to the address:

https://payment.{domain}/{ExternalOrderID}

where payment is a fixed value

domain is the address for sending requests

ExternalOrderID is the order number received in response to the payment form creation method.

Opening the form via a POST request allows passing additional parameters, such as the address for redirect back based on the payment result.

To call the form with redirect capability, you need to:

  1. Use a native HTML form with the POST method

  2. Specify the form URL in the action attribute

  3. Specify redirect links in two hidden fields (successUrl, failUrl)

  4. Specify application/x-www-form-urlencoded in enctype attribute

  5. Submit the form using the standard submit call (POST request with navigation)

Example:

<form
   action="https://payment.{domain}/{ExternalOrderID}"
   method="POST"
   enctype="application/x-www-form-urlencoded"
 >
   <input type="hidden" name="successUrl" value="https://domain.test/{ExternalOrderID}/success" placeholder="successUrl">
   <input type="hidden" name="failUrl" value="https://domain.test/{ExternalOrderID}/fail" placeholder="failUrl">

   <button type="submit">Pay</button>
</form>

Authorization

Obtaining access to the system

Request Body schema: application/json
login
string

Cashier's login (email) in the system

password
string

Cashier's password in the system

Responses

Request samples

Content type
application/json
{
  • "login": "mail@email.com",
  • "password": "Password123"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "login success",
  • "accessToken": "string",
  • "expiresAccess": "string",
  • "refreshToken": "string",
  • "expiresRefresh": "string"
}

Orders

getting a list of orders

Authorizations:
Authorization-Token
query Parameters
tspId
integer <unit64>

Shop Id for which the payment is being processed

dateFrom
string <date-time>

start date of the order tracking period

dateTo
string <date-time>

end date of the order tracking period

status
string

current order status

limit
number

Limit count orders. Default 30

offset
number

Offset of orders. Default 0

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "string",
  • "orders": [
    ],
  • "meta": {
    }
}

Creating an order

An order can be created in two ways

  • Using the orderAmount field
    • Order amount is specified in the selected currency.
    • After creation, the amount is automatically converted to rubles, and the payment will be accepted in rubles.
    • All fees are included in the final amount.
    • The amount must be specified in kopecks (or cents, eurocents, etc.).
    • For example, if you pass 100 in orderAmount, the total amount to be paid will be 100 plus fees.
  • Using the paymentAmount field
    • The amount to be paid remains in rubles.
    • The system converts it to the selected currency and deducts fees.
    • The amount must be specified in kopecks.
    • For example, if you pass 100 in paymentAmount, the amount to be paid will be 100, and orderAmount will be the 100 minus fees.
  • Important
    • To create a payout order, you must specify the PayOut type. Without this type, you will not be able to proceed.
    • When creating an acceptance order (e.g., for a sale), the type can be omitted; the PayIn type will be used by default.
Authorizations:
Authorization-Token
Request Body schema: application/json
One of
merchantOrderId
string

Merchant's order identifier, can be filled with the order number from the merchant's system

paymentAmount
required
integer

Amount to be paid by the customer, passed in kopecks

orderCurrency
required
string

Original order currency, available currencies USD, EUR, AED, THB, RUB, TRY

paymentCurrency
string

Final order currency in which the payment will be made

tspId
required
integer

Shop Id for which the payment is being processed

description
string

Order description, a note field for the order

callbackUrl
string

Address to which the callback will be sent

Responses

Request samples

Content type
application/json
Example
{
  • "merchantOrderId": "merchantOrderId",
  • "orderAmount": 100,
  • "orderCurrency": "EUR",
  • "tspId": 1,
  • "description": "comment",
  • "callbackUrl": "callback.com"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "description": "",
  • "order": {
    }
}

retrieving order data

Authorizations:
Authorization-Token
path Parameters
id
required
integer

Order identifier in the system

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "string",
  • "order": {
    }
}

order refund

Authorizations:
Authorization-Token
path Parameters
id
required
integer

Order identifier in the system

Request Body schema: application/json
amount
integer

Refund amount in the minimum currency unit (kopecks). Optional parameter. If not provided, a full refund is processed.

Responses

Request samples

Content type
application/json
{
  • "amount": 300
}

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "string",
  • "order": {
    }
}

order status

Retrieving the current order status

path Parameters
id
required
integer <unit64>

Order identifier in the system

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "string",
  • "order": {
    }
}

IPS

qrcData - Registering a QR code in the IPS

Authorizations:
Authorization-Token
path Parameters
id
required
integer

Order identifier in the system

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "string",
  • "order": {
    }
}

payout via IPS

Authorizations:
Authorization-Token
path Parameters
id
required
integer
Request Body schema: application/json
accountNumber
required
string

Recipient's phone number in international format without the + sign

bankId
required
string

Recipient's bank identifier in IPS

firstName
string

Recipient's first name

lastName
string

Recipient's last name

middleName
string

Recipient's middle name

Responses

Request samples

Content type
application/json
{
  • "accountNumber": 79011234567,
  • "bankId": 100000000001,
  • "firstName": "Ivanov",
  • "lastName": "Ivan",
  • "middleName": "Ivanovich"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "description": "string",
  • "order": {
    }
}

Retrieving the list of banks for payout

Responses

Response samples

Content type
application/json
{
  • "BankList": [
    ]
}

SberPay

Payment via SberPay

Authorizations:
Authorization-Token
path Parameters
id
required
integer
Request Body schema: application/json
BackUrl
string

Redirect address after payment

phoneNumber
string

Phone number for sending a push notification to redirect to SBOL

Responses

Request samples

Content type
application/json
{
  • "deepLink": "android-app://ru.testbankmobile/main",
  • "phoneNumber": "+79876543210"
}

Response samples

Content type
application/json
{
  • "succes": true,
  • "description": "string",
  • "order": {
    }
}

Card Methods

payout to card

to create a payout, the order must be created with the PayOut type parameter. Upon receiving the IN_PROCESS status, clarification is required.

Authorizations:
Authorization-Token
path Parameters
id
required
integer
Request Body schema: application/json
pan
required
string

Recipient's card number

holder
string

Recipient's first and last name

phone
string

Recipient's phone number

Responses

Request samples

Content type
application/json
{
  • "pan": 4189732800687140,
  • "holder": "Ivan Ivanov",
  • "phone": 79998887766
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "description": "",
  • "order": {
    }
}

request to create an order via payment form

to open the payment form, you must call it with the externalOrderId received in the response

path Parameters
id
required
integer

Order identifier in the system

tspCode
required
string

Shop code in the system

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "externalOrderId": "string"
}

authorize - Hold funds

For card operations of type PayIn, the first step is to create an order using the POST /order method. After receiving the id, you need to obtain the externalOrderId via the /form method. In subsequent requests, the externalOrderId must be passed in the OrderId field.

Authorizations:
NoneNoneNone
Request Body schema: aplication/json
One of
required
Auth-request-card (object) or Auth-request-token (object) or Auth-request-encrypted (object)

Card parameters

OrderId
required
string

Order identifier ExternalOrderID

PaymentType
string

One-stage(SMS)/Two-stage (DMS) payment. Possible values SMS/DMS. Defaults to DMS. If SMS is passed, the charge will be made automatically.

object

Data for 3-D Security authorization. Optional for non-3DS payments.

object

Metadata - additional information

Responses

Request samples

Content type
aplication/json
Example
{
  • "OrderId": "ExternalOrderId",
  • "Card": {
    }
}

Response samples

Content type
application/json
Example
{
  • "Response": {
    },
  • "Order": {
    },
  • "Authorize": {
    },
  • "Card": {
    }
}

charge - Capture funds

For card operations of type PayIn, the first step is to create an order using the POST /order method. After receiving the id, you need to obtain the externalOrderId using the /form method. In subsequent requests, the externalOrderId must be passed in the OrderId field.

Authorizations:
NoneNoneNone
Request Body schema: aplication/json
OrderId
required
string

Order identifier ExternalOrderID

Responses

Request samples

Content type
aplication/json
{
  • "OrderId": "ExternalOrderId"
}

Response samples

Content type
application/json
Example
{
  • "Response": {
    },
  • "Order": {
    },
  • "Charge": {
    }
}

void - Cancel hold

For card operations of type PayIn, the first step is to create an order using the POST /order method. After receiving the id, you need to obtain the externalOrderId via the /form method. In subsequent requests, the externalOrderId must be passed in the OrderId field.

Authorizations:
NoneNoneNone
Request Body schema: aplication/json
OrderId
required
string

Order index ExternalOrderID

Responses

Request samples

Content type
aplication/json
{
  • "OrderId": "ExternalOrderId"
}

Response samples

Content type
application/json
Example
{
  • "Response": {
    },
  • "Order": {
    },
  • "Void": {
    }
}