# Payments

TESTING

Before making combat requests, use the test environment and data from the sections:

Payments to card (by token, by card number, through the payment page) - Payment services: test cards, sandbox credentials and Postman collection.
Payments through SBP - Payments through SBP: test phones, banks and scenarios with and without full name.

# Authentication

All requests to the payout API (except check balance) are authenticated by the header x-auth. Formation of the value is in the Request Authentication.

# Payments to card

PLEASE ATTENTION!

MeaningorderIdmust be unique within successful card payment transactions.
In case when sending a payment request you did not receive a synchronous response with an HTTP code200Andidoperation, or received a response with an HTTP code other than200(For example,502or504) and want to request the same payment again, must use the same numberorderId.
Thus, if the initial request was completed successfully, or is in progress, you will receive a response with an HTTP code400and the error “Duplicate order id”, and the repayment will not be made. If the initial request is unsuccessful, the operation will proceed in standard mode.

Following these instructions will allow you to avoid duplicate payment transactions to the card if any network problems arise between your application server and the Mandarin server.
We also recommend that you set a timeout of 600 seconds when sending requests via the API.

For example, the initial payout request containedorderId, equal to "5f2fdcf6-0b78-4dd7-be9f-212c7c058001".

If it is completed successfully, then when you request a payment again with the same valueorderId, an error will be returned in the synchronous response. The payment will not be re-created.

Response in case of an attempt to create a payment with an existing valueorderId(400 Bad Request)

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

# Payout using card token

Within this API call, a block is added to the standard calltarget, where as the valuecardtransmittedidpreviously completed successful tokenization of full card data or [card number](./api_tokenization.md#tokenization-card number).

The transaction is carried out asynchronously. As a result of the request, you will synchronously receive id payout, and then callback-notification will arrive asynchronously.

Parameter	Required	Parameter	Required
payment	Yes	target	Yes
payment.action	Yes	target.card	Yes
payment.orderId	Yes	customValues[]	No
payment.price	Yes	customValues[].name	No

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}'

Response in case of successful transaction creation (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Answer if the transaction is not created (400 Bad request)

{
	"error": "Invalid request"  
}

Response in case of an attempt to create a payment with an existing valueorderId(400 Bad Request)

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

# Payout using card number

As part of this request, a block is added to the standard calltarget, where as the valueknownCardNumberthe number of the card to which the transfer is made is transmitted.

MeaningorderIdmust be unique within successful withdrawal operations. If you didn't get successfulcallbackand want to request the same payment again, we recommend using the same numberorderId. This will prevent duplicate payouts if the original payout was made but a successfulcallbackdidn't arrive.

The transaction is carried out asynchronously. As a result of the request, you will synchronously receive id payout, and then callback-notification will arrive asynchronously.

Parameter	Required	Parameter	Required
payment	Yes	target	Yes
payment.action	Yes	target.knownCardNumber	Yes
payment.orderId	Yes	customValues[]	No
payment.price	Yes	customValues[].name	No
customerInfo	Yes	customValues[].value	No
customerInfo.email	Yes	metadata	No
customerInfo.phone	Yes	urls	No

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"knownCardNumber": "4012888888881881"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}'

Response in case of successful transaction creation (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Answer if the transaction is not created (400 Bad request)

{
	"error": "Invalid request"  
}

Response in case of an attempt to create a payment with an existing valueorderId(400 Bad Request)

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

# Payment by entering the card on the payment page

The transaction is carried out asynchronously. As a result of the request, you will synchronously receive id payout, and then callback-notification will arrive asynchronously.

Parameter	Required	Parameter	Required
payment	Yes	customValues[]	No
payment.action	Yes	customValues[].name	No
payment.orderId	Yes	customValues[].value	No
payment.price	Yes	metadata	No
customerInfo	Yes	urls	No
customerInfo.email	Yes	urls.callback	No
customerInfo.phone	Yes	urls.return	No

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}'

Response in case of successful transaction creation (200 OK)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518"
}

Answer if the transaction is not created (400 Bad request)

{
	"error": "Invalid request"  
}

Response in case of an attempt to create a payment with an existing valueorderId(400 Bad Request)

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

# Payments via SBP

PLEASE ATTENTION!

In accordance with the requirements of NSPK No. 802-P and the AF SBP Standards, it is prohibited to carry out mass requests for personal data by sending the borrower’s phone number and receiving the full name in response. Therefore, we recommend that in order to avoid blocking of SBP services by NSPK, it is necessary to check the correspondence of the full name of the borrower and the account owner after conducting scoring procedures and before signing the loan agreement.

Fast Payment System (FPS) is a service that allows you to instantly transfer funds from an account using the recipient’s phone number.

Features of the SBP payment service:

To connect the SBP payment service, you must send a request to Support Service (opens new window) or to the client manager;
Payments are made with or without indicating the phone number and full name of the recipient, as well as selecting a bank from the list of banks;
Data binding for subsequent recurring payments and auto-debits via SBP is not currently provided.

# Getting a list of banks

In order to transfer a bank, you need to obtain its databankIdAndbankBicfrom the list of banks.

Parameter	Type	Required	Description
bankName	string	No	The name of the bank by which you want 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:

curl --request GET \
  --url https://secure.mandarinpay.com/api/sbp/banks/ \
--header 'x-auth: {{x_auth}}'
```**Response if the request was created successfully:**

```json
{
    "banks": [
        {
            "bankId": "100000000111",
            "bankName": "Сбербанк",
            "bankBic": "044525225"
        },
        {
            "bankId": "100000000008",
            "bankName": "Альфа-Банк",
            "bankBic": "044525593"
        },
        {
            "bankId": "100000000010",
            "bankName": "Промсвязьбанк",
            "bankBic": "044525555"
        }
    ]
}

Request for a specific bank:

curl --request GET \
  --url https://secure.mandarinpay.com/api/sbp/banks?bankName=Сбербанк \
--header 'x-auth: {{x_auth}}'
```**Response if the request was created successfully:**

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

If banks are not found, the response will be returned:

{
    "banks": []
}

# Creating a payment with full name

Within this API call, a block is added to the standard calltarget, where as the valuesbpbank parameters are transferredbankIdAndbankBic.

The transaction is carried out asynchronously. As a result of the request, you will synchronously receive id payout, and then callback-notification will arrive asynchronously.

Parameter	Required
customerInfo	Yes
customerInfo.phone	Yes
customerInfo.email	Yes
customerInfo.firstName	Yes
customerInfo.lastName	Yes
customerInfo.middleName	Yes, if the recipient's passport contains a middle name
payment	Yes
payment.action	Yes
payment.orderId	Yes
payment.price	Yes
target	Yes
target.sbp	Yes
target.sbp.bankId	Yes
target.sbp.bankBic	Yes

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
    "customerInfo": {
        "phone": "+79111111111",
        "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"
}

Answer if the transaction is not created (400 Bad request)

{
	"error": "Invalid request"  
}

Response in case of an attempt to create a payment with an existing valueorderId(400 Bad Request)

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

# Creating a payment without full name

Within this API call, a block is added to the standard calltarget, where as the valuesbpbank parameters are transferredbankIdAndbankBic.

The transaction is carried out asynchronously. As a result of the request, you will synchronously receive id payout, and then callback-notification will arrive asynchronously.

Payments without full name require confirmation or cancellation after the transaction is created and successful status is received from the bank.

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

Synchronous response and asynchronous callback-notification can contain a wider set of parameters compared to the example.

Request

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
    "customerInfo": {
        "phone": "+79111111111",
        "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"
}

Answer if the transaction is not created (400 Bad request)

{
	"error": "Invalid request"  
}

Response in case of an attempt to create a payment with an existing valueorderId(400 Bad Request)

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

# Checking request status without full name

Request to check status

After creating a payment without full name, you need to check the status; it will be possible to confirm the payment only after the status issuccess.

curl --request GET \
  --url https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/status \
--header 'x-auth: {{x_auth}}'

Response in case of successful transaction creation (200 OK)

{
    "status": "success",
    "fio": "Петр Иванович С."
}

Response in case of waiting for verification of the recipient by the bank

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

# Confirmation of payment without full name

Request for confirmation of payment

After receiving a successful status, you must confirm the payment in order for the funds to go to the recipient.

curl --request POST \
  --url https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/confirm \
--header 'x-auth: {{x_auth}}'

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

# Cancellation of payment without full name

The payment can be canceled if a confirmation request has not yet been sentconfirm.

Request to cancel payment

curl --request POST \
  --url https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/reject \
--header 'x-auth: {{x_auth}}'

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

# Checking balance for payments

# Authentication

Requests are authenticated using the OAuth 2.0 protocol (Bearer). For more details, see the Request Authentication section. Required scope: pay_bank_account_balance.read, which must be requested when obtaining a token.

The method allows you to obtain information on the balance of funds in the account for payments. In the response you will receive all the current balances of the banks that you have connected to, as well as the date and time of the last balance update.

Request

curl --request GET \
  --url https://api.psp.io/balance/v3/client/{client_id}/balance \
--header 'Authorization: Bearer {{access_token}}'

As a value{client_id}you need to pass your client id.

For more information about the response format, see the Method for requesting balance.

# Getting transaction status

The API method makes it possible to obtain its status, as well as information about the card, using the transaction identifier.

Request: operationId — id payment.

curl --request GET \
  --url https://secure.mandarinpay.com/api/operations/{operationId} \
--header 'x-auth: {{x_auth}}'

Sample answer:```json { "operationType": "Transaction", "state": "Success", "card": { "cardNumber": "519261XXXXXX3242", "cardHolder": "CARD HOLDER", "expireDate": "25/01", "cardId": "a3a5c49e1385e5096d05075d636f7baf", "country": "TUR", "productName": "Standard Mastercard Card", "productCode": "MCS", "brand": "mastercard", "bank": "ODEA BANK A.S.", "cardType": "Credit" } }


| Parameter | Description |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| operationType | operation type, transaction/binding |
| state | Operation status: success, failed, payout-only, pendingExecution/none/unknown - the operation has not been completed and is being processed (reconciliation with the acquiring bank may be required). Only the success status clearly indicates the success of the operation! |
| cardNumber | masked card number |
| cardHolder | card holder |
| expireDate | card expiration date |
| cardId | unique hash of the full card number |
| country | country of issue |
| productName | card product/card category |
| productCode | card product/card category code |
| brand | card payment system |
| bank | bank that issued the card |
| cardType | card type (debit/credit) |

← Tokenization BaaS →