Mandarin

# Testing

# Testing of payment products

# Test cards

Card data for all payment requests on test (sandbox) environment.

Parameter Value Comment
Term of validity Any time later than the current month in MM/YYY format
CARD Holder name CARD HOLDER
CVV 123
Card number 4929509947106878 To simulate successful transactions without 3DSecure
Card number 4692065455989192 To simulate successful transactions with 3DSecure
Card number 4485913187374384 For simulating unsuccessful transactions without 3DSecure
Card number 4556058936309366 To simulate unsuccessful transactions with 3DSecure
Card number 5192618384533242 To simulate interactive payment with forced card transfer to payout-only

# Collection for Postman

To make the process of testing and getting acquainted with the possibilities of the payment API more convenient, we've prepared collections for Postman. To work with them you need to go through the following steps:

  1. Download and save as a file the mandarin_api (opens new window) collection.

  2. Install and run the [Postman] program (https://www.postman.com/downloads/).

  3. import the collection mandarin_api.postman_collection.json by selecting "File" -> "Import..."

File -> Import...

Then click the "Upload Files" button and select the saved collection file.

Upload Files

  1. Write your authorization information into the collection's variables. To do this, click the "breadcrumbs" next to the collection name, then select the "Edit" menu item.

Edit

In the window that opens, go to the "Variables" tab and type in the values "Merchant id" and "Secret" from your personal account against the merchant_id and ``secret` variables.

If you write the authorization data from the test personal account, the transaction will be executed on the test (sandbox) environment, and if you write it from the live one, it will be executed on the production one.

Editing Collection Variable Values

Finally, you must save the changes with the "Update" button.

  1. You can send inquiries!

We recommend that you run them in order (by pressing the "Send" button). Some requests are prefixed with an exclamation mark:

  • One-stage payment.
  • ! Two-stage payment - Authorization.
  • Tokenization of full card data.

To successfully complete such requests, you need to open a link in the browser which will return in the userWebLink response parameter. Otherwise, some subsequent requests will fail because they refer to their results.

Send request, receive

  1. Open the userWebLink link in your browser.

You will need to enter the card data:

  • For the test environment: use the card number 4692065455989192 for a successful transaction, the rest of the data - any.

  • For a production environment: enter the data of your real card. The card will be charged.

Then click on the "Payment" button.

Filling in the card data on the payment page

If you have requested tokenization, that is the end of the process.

If you have made a payment, a page will open with a successful payment status.

Successful status

  1. Test terminal does not support authorization using card token. Therefore, the request "% Two-step payments - Authorization using card token" will fail. You can discuss the possibility of authorization using a card token with your manager when you set up a battle terminal.

  2. If you are satisfied with the result of your Postman query, you can easily generate code to send the query in any programming language using Postman.

To do this, click on the "Code" button on the right side of the window (as in the figure below). In the window that opens, select the programming language and copy the source code.

Generating code snippet

# Check balance for payments

The query returns a constant 100500 on test (sandbox) environment.

GET https://secure.mandarinpay.com/api/account/channels/{name}/balance

As the value of {name} you must pass the parameter from the table below:

Parameter Parameter description
openbank_direct To inquire about the balance of a current account opened with PJSC Bank FC Otkritie (Otkritie)
psb_direct To inquire about the balance of the current account opened in PSB (PSB)

# Testing payments via SBP

Features of the SBP payment service in the test environment:

  • A request for a list of banks returns a list of 5 banks;

  • For a successful request with full NAME and receiving the payment status of success, you must use the phone number +79001234567, if using a different phone, the transaction status fail will be received;

  • For a successful request without full NAME and receiving the payment status of success, you must use the phone number +79007654321, if using a different phone, the transaction status fail will be received. The response to the status request returns the full name Ivan Ivanovich Ivanov;

# Getting a list of banks

Authorization - XAuth (opens new window).

Parameter Type Required Description
bankName string No The name of the bank by which to filter, you can specify an incomplete name, the method will return all suitable options. Case is ignored when filtering

Request for a list of banks:

GET https://secure.mandarinpay.com/api/sbp/banks/

Response if the request was successfully created:

{
    "banks": [
        {
            "bankId": "100000000008",
            "bankName": "Альфа-Банк",
            "bankBic": "044525593"
        },
        {
            "bankId": "100000000005",
            "bankName": "ВТБ",
            "bankBic": "044525187"
        },
        {
            "bankId": "100000000004",
            "bankName": "Т-Банк",
            "bankBic": "044525974"
        },
        {
            "bankId": "100000000007",
            "bankName": "Райффайзен Банк",
            "bankBic": "044525700"
        },
        {
            "bankId": "100000000111",
            "bankName": "Сбербанк",
            "bankBic": "044525225"
        }
    ]
}

Request to get a specific bank:

GET https://secure.mandarinpay.com/api/sbp/banks?bankName=Сбербанк

Response if the request was successfully created:

{
    "banks": [
        {
            "bankId": "100000000111",
            "bankName": "Сбербанк",
            "bankBic": "044525225"
        }
    ]
}

# Payment with full name

Parameter Required
customerInfo Yes
customerInfo.phone Yes
customerInfo.email Yes
customerInfo.firstName Yes
customerInfo.lastName Yes
customerInfo.middleName Yes
payment Yes
payment.action Yes
payment.orderId Yes
payment.price Yes
target Yes
target.sbp Yes
target.sbp.bankId Yes
target.sbp.bankBic Yes

Request:

POST https://secure.mandarinpay.com/api/transactions

{
    "customerInfo": {
        "phone": "+79001234567",
        "email": "test@test.com",
        "firstName": "Иванов",
        "lastName": "Иван",
        "middleName": "Иванович"
    },
    "payment": {
        "orderId": "your_unique_order_id",
        "price": "10.00",
        "action": "payout"
    },
    "target": {
        "sbp": {
            "bankId": "100000000111",
            "bankBic": "044525225"
        }
    }
}

Response in case of successful transaction creation (200 OK):

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Response in case of transaction not created (400 Bad request):

{
	"error": "Invalid request"  
}

Response in case of attempt to create payment with already existing value orderId (400 Bad Request):

{
    "error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
    "errorCode": -2
}

# Payment without full name

Payments without full name require confirmation or cancellation after transaction creation.

Parameter Required
customerInfo Yes
customerInfo.phone Yes
customerInfo.email Yes
payment Yes
payment.action Yes
payment.orderId Yes
payment.price Yes
target Yes
target.sbp Yes
target.sbp.bankId Yes
target.sbp.bankBic Yes

Request:

POST https://secure.mandarinpay.com/api/transactions

{
    "customerInfo": {
        "phone": "+79007654321",
        "email": "test@test.com"
    },
    "payment": {
        "orderId": "your_unique_order_id",
        "price": "10.00",
        "action": "payout"
    },
    "target": {
        "sbp": {
            "bankId": "100000000111",
            "bankBic": "044525225"
        }
    }
}

Response in case of successful transaction creation (200 OK):

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Response in case of transaction not created (400 Bad request):

{
	"error": "Invalid request"  
}

Response in case of attempt to create payment with already existing value orderId (400 Bad Request):

{
    "error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
    "errorCode": -2
}

# Checking the status of a request without full name

Request for status check:

After creating a payment without a full name, you need to check the status. If the phone number specified is a test one from the documentation, the status will be success. If something else is specified, the status request will be fail.

GET https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/status

Response if successful:

{
    "status": "success",
    "fio": "Иван Иванович Иванов"
}

Response in case of failure:

{
    "status": "fail",
    "fio": null
}

# Payment confirmation without full name

Request for payment confirmation:

After receiving a successful status, you must confirm the payment so that the recipient receives the funds.

POST https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/confirm

Response in case of successful payment confirmation (200 OK):

# Cancellation of payment without full name

Payment can be cancelled if the confirmation request confirm has not yet been sent.

Request to cancel payment:

POST https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/reject

Response in case of successful cancellation of payment (200 OK):

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

# Simplified identification testing

Testing the SMZ service is only possible in sandbox mode. To enable this mode, please contact Support Service (opens new window).

**Data for simplified identification queries on test (sandbox) environment.

In this case, the SMS message with the code to confirm the phone number is not sent. You must use the code from the table below.

Parameter Value Comment
firstName Полиграф
patronymic Полиграфович
lastName Шариков
smsCode 000000 All digits are zeros. The number of digits in the smsCode
is set in the merchant settings

The rest of the parameters can be any.

Example of a request for identification by SNILS:

POST https://secure.mandarinpay.com/api/personidentification

{
    "firstName": "Полиграф",
    "lastName": "Шариков",
    "patronymic": "Полиграфович",
    "passportSeries": "1111",
    "passportNumber": "111111",
    "snils": "",
    "inn": "501716749325",
    "phone": "+79001234567"
}

An example of a request with an SMS code for verification:

PUT https://secure.mandarinpay.com/api/personidentification/{id}

{
	"smsCode": "000000"
}

Example Response:

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

Request for identification status:

GET https://secure.mandarinpay.com/api/personidentification/{id}

Example Response:

The data of Шариков Полиграф Полиграфович is indicated. A request has not yet been made to send the code for verification.

{
    "id": "485fc237-a8b8-45f9-816d-fb7de3715e2b",
    "phoneVerified": null,
    "phoneVerificationFinished": false,
    "personVerified": true,
    "personVerificationFinished": true,
    "personVerificationError": "Sandbox mode"
}

The data of Шариков Полиграф Полиграфович is indicated. The code has been sent for verification.

{
    "id": "485fc237-a8b8-45f9-816d-fb7de3715e2b",
    "phoneVerified": true,
    "phoneVerificationFinished": true,
    "personVerified": true,
    "personVerificationFinished": true,
    "personVerificationError": "Sandbox mode"
}

The data is different from the Шариков Полиграф Полиграфович. The code has been sent for verification.

{
    "id": "d3552b7c-80a6-4e0e-bf1f-ad0c7ff2d705",
    "phoneVerified": true,
    "phoneVerificationFinished": true,
    "personVerified": false,
    "personVerificationFinished": true,
    "personVerificationError": "Sandbox mode"
}

# Possible errors

error code 401 - The authorization of the request was not completed, check the correctness of the authorization.

{
    "error": "Authentication error: "
}

error code 400 - The id value is not specified for requesting the identification status.

{
    "sessionId": [
        "The value '{id}\n' is not valid."
    ]
}

error code 400 - The snils parameter is not specified in the identification request.

{
    "snils": [
        "Required property 'snils' not found in JSON. Path '', line 9, position 1."
    ]
}

error code 400 - The snils parameter contains invalid characters or exceeds the field size.

{
    "snils": [
        "The field Snils must match the regular expression '[0-9]{11}'."
    ]
}

Errors 5xx - An error on the server side. (Extremely rare)

# Testing the service Self-employed

Testing the SMZ service is only possible in sandbox mode. To enable this mode, please contact Support Service (opens new window).

To obtain a specific check status, you must use one of the two test TINs:

Parameter Description
185796979287 the status is set to SUCCESS when the check is registered.
058104954632 the status is set to FAILED when the check is registered.

# Connecting a self-employed person by TIN

Request Parameters::

Parameter Required Description
inn Yes Individual taxpayer identification number.
callback_url Yes URL to which the response will be sent.
is_sandbox Yes Test mode parameter: true;1;yes

Example Request:

curl --location 'https://api.psp.io/self-employed/v1/tin/bind' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "is_sandbox": true,
    "inn": "185796979287",
    "callback_url": "https://webhook.site/28b30c34-9fbd-4e98-b1b7-e20a999d530b"
}'

If successful, the response will include:

  • id: the unique request ID.
  • inn: the associated taxpayer ID.

Example Response:

{
  "id": "3ab4e73d-a197-4a2f-9b92-69ef07468b04",
  "inn": "185796979287"
}

Callback:

PLEASE NOTE!

Please provide the url for sending callbacks in Mandarin in advance!

{
   "id": "80cf6b02-795f-486f-a515-562a41a87429",
   "inn": "185796979287",
   "status": 0,
   "message": null
}

Callback Parameters:

Parameter Type Description
id uuid Request ID
inn string INN
status integer Status of the response from SMZ, possible options:
0 - success;
1 - completed with an error;
8 - the permanent request to the Federal Tax Service has expired;
408 - timeout error (long wait for a response from the Federal Tax Service)
message string Error text for statuses: 1, 8, 408

# Check State

When calling the status verification method (opens new window) self-employed, you need to pass parameters to the querystring with the results you want to get:

Query Params Value Description
is_sandbox true;
1;
да;
yes		 Test mode parameter, you can use any of the listed values
state ACTIVE;
NOT_SELF_EMPLOYEE		 SMZ status, you can specify any of this list (opens new window)

Example Request:

curl --location 'https://api.psp.io/self-employed/v1/tin/185796979287?is_sandbox=true&state=ACTIVE' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123'

Example Response:

{
    "id": "test-d4dc85c1-765a-4865-bea6-01b215a333ed",
    "inn": "185796979287",
    "status": "ACTIVE"
}

# Creating a test receipt

Request Parameters::

Parameter Obligatory Description
inn Yes The TIN (taxpayer identification number) associated with the check.
price Yes The price of the product/service
title Yes The name of the product/service in the check
is_sandbox Yes Test mode parameter: true;1;yes

Example Request:

curl --location 'https://api.psp.io/self-employed/v1/receipts' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "is_sandbox": true,
    "inn": "185796979287",
    "price": 100,
    "title": "Order payment №1234"
}'

Response with test TIN 185796979287:

{
  "cheque_id": "20172zyc8z",
  "inn": "185796979287",
  "message": "",
  "session_id": "edccadd7-e5f9-4de2-8088-64e6adf0959b",
  "status": "success",
  "url": "https://lknpd.nalog.ru/api/v1/receipt/623406197779/20172zyc8z/print",
  "title": "Order payment №1234"
}

Response with test TIN 058104954632:

{
  "cheque_id": null,
  "inn": "058104954632",
  "message": "Inactive TIN 058104954632 failed/ACTIVE",
  "session_id": "edccadd7-e5f9-4de2-8088-64e6adf0959b",
  "status": "failed",
  "url": null,
  "title": "Order payment №1234"
}

Response Parameters:

  • cheque_id - unique identifier of the created cheque.
  • inn - INN associated with the cheque.
  • message - additional information or error message.
  • session_id - id of the created cheque.
  • status - status of the request, see the list of statuses below.
  • url - URL for printing the created cheque.
  • title - Title of the product/service specified in the request.

Status list:

Status Description
success The check was successfully created
failed Failed to create the check. The error details can be found in the response (message).

← Operation types →