Accepting funds

On this page you will find the method and webhooks that the payment partner will need to send a transfer. The general order of requests is as follows:

The payment partner initiates a payment session and sends to the Bank information on the Sender and Recipient using the POST.../api/v1/bpa/session/init/payment method.
The Bank creates a transaction and returns the creation results.
After receiving the response, wait for a ready_to_confirm webhook with detailed information on the payout amount, transaction fee, and conversion rate.
Once the ready_to_confirm webhook is received, confirm the transaction with session/confirm or cancel it with session/cancel.
If required, you can check the session status using the session/status method.
To complete the transaction, wait for a payment_finished webhook.

`POST.../api/v1/bpa/session/init/payment` method

This method is used to initiate the transfer.

Request parameters

Name	Mandatory	Type	Description
payment_details	+	object	Payment method
type	+	string	Payment method name. Valid value: `moneysend`
moneysend	+	object	Details of payment via Moneysend
amount_details	+	object	Payment details
amount	+	int	Amount in minor values (To transfer 100 rubles, specify 10000)
currency	+	string	Payment currency
participant_details	+	object	Participant details
sender	+	object	Sender details
citizenship_country_iso3	+	string	Sender's country of citizenship according to ISO 3166-1 alpha-3
first_name	+	string	Sender's first name
last_name	+	string	Sender's last name
middle_name	-	string	Sender's middle name
country_iso3	+	string	Sender's country of registration according to ISO 3166-1 alpha-3
state	-	string	State or region of the sender's place of registration
city	+	string	Locality of the sender's place of registration
postal_code	-	string	Postal code of the sender's place of registration
street	-	string	Street of the sender's place of registration
building	+	string	Building number of the sender's place of registration
flat	-	string	Apartment of the sender's place of registration
tax_reference	-	string	Sender's INN (12 digits)
date_of_birth	+	string	Sender's date of birth in the YYYY-MM-DD format. Make sure the sender is 18 years old or older
contacts		object	Sender's contacts
phone		object	Sender's phone number
full_number	+	string	Sender's full phone number in the `+<country code><number>` format
country_iso3	+	string	Sender's phone number country code according to ISO3
operator_code	+	string	Operator code of the sender's phone number
short_number	+	string	Sender's phone number without the operator code
email	-	string	Sender's email
identity_document	+	object	Sender's identity document
id_type	+	string	Type of the sender's identity document. Valid values: - Passport of a foreign citizen - Passport of a citizen of the Russian Federation
id_number	+	string	Sender's identity document series and number (without spaces)
issue_date	+	string	Sender's identity document issue date in the YYYY-MM-DD format
id_expiration_date	-	string	Sender's identity document expiry date in the YYYY-MM-DD format. Required if available in the document. Otherwise, do not send this field
division_code	-	string	Code of the division that issued the sender's identity document. Required if available in the document
issued_by	-	string	Name of the division that issued the sender's identity document. Required if available in the document
documents_foreigner	-	object	Non-resident sender's identity document details. Required for non-residents only
id_type	+	string	Type of the non-resident sender's identity document. Valid values: - Residence permit - Temporary residence permit - Migration card - Visa
issued_by	-	string	Non-resident sender's identity document issuing authority
issue_date	+	string	Non-resident sender's identity document issue date in the YYYY-MM-DD format
id_expiration_date	+	string	Non-resident sender's identity document expiry date in the YYYY-MM-DD format
service_point	-	object	Service point of accepting funds
id	-	string	Service point ID
name	-	string	Service point name
country	-	string	Service point country according to ISO 3166-1 alpha-3
state	-	string	Service point region/state
city	-	string	Service point locality
oktmo	+	string	Service point OKTMO
street	-	string	Service point street
house	-	string	Service point building
terminal_id	-	string	Terminal/cash register ID
source_of_money	-	string	Source of the sender's funds
description	-	string	Additional information
recipient	+	object	Recipient details
first_name	+	string	Recipient's first name
last_name	+	string	Recipient's last name
middle_name	-	string	Recipient's middle name
date_of_birth	-	string	Recipient's date of birth in the YYYY-MM-DD format. Make sure the recipient is 18 years old or older
currency	+	string	Payout currency. Valid values: `TRY`, `USD`
contacts	+	object	Recipient's contacts
phone	+	object	Recipient's phone number
full_number	+	string	Recipient's full phone number in the `+<country code><number>` format
country_iso3	+	string	Recipient's phone number country code according to ISO3
operator_code	+	string	Operator code of the recipient's phone number
short_number	+	string	Recipient's phone number without the operator code
email	-	string	Recipient's email
cash_details	+	object	Additional information on the cash payment
shift	+	string	Cash register shift

Request example

{
  "payment_details": {
    "type": "moneysend",
    "moneysend": {}
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "citizenship_country_iso3": "AUS",
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "middle_name": "Ivanovich",
      "country_iso3": "RUS",
      "state": "New York",
      "city": "Kazan",
      "postal_code": "420000",
      "street": "Nekrasova",
      "building": "1",
      "flat": "131",
      "tax_reference": "123456789012",
      "date_of_birth": "2010-01-01",
      "contacts": {
        "phone": {
          "full_number": "+79371234567",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "1234567"
        },
        "email": "test@test.com"
      },
      "identity_document": {
        "id_type": "Паспорт гражданина Российской Федерации",
        "id_number": "123456789",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01",
        "division_code": "165-065",
        "issued_by": "OVD Kazani"
      },
      "documents_foreigner": {
        "id_type": "Виза",
        "issued_by": "OVD Kazani",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01"
      },
      "service_point": {
        "id": "1",
        "name": "point_on_lenina",
        "country_iso3": "Russia",
        "state": "Moscow",
        "city": "Moscow",
        "oktmo": "36634436111",
        "street": "Lenin avenue",
        "house": "1",
        "terminal_id": "123124"
      },
      "source_of_money": "salary",
      "description": "salary transfers"
    },
    "recipient": {
      "first_name": "Ivan",
      "last_name": "Sidorov",
      "middle_name": "Ivanovich",
      "date_of_birth": "2010-01-01",
      "currency": "TRY",
 "contacts": {
   "phone": {
     "full_number": "+79377654321",
     "country_iso3": "RUS",
     "operator_code": "937",
     "short_number": "7654321"
   },
   "email": "test@test.com"
    }
   }
  },
  "cash_details": {
    "shift": "11"
  }
}

Response parameters

Name	Mandatory	Type	Description
status	+	string	Request status
session	+	object	Session details
id	+	string	Session ID. Remember it to use it to confirm/cancel the transaction or to get the transaction status
status	+	string	Current session status. See the available values here
created_at	+	string	Session creation date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
updated_at	+	string	Session update date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
error	-	object	Error details. Returned only if an error occurred
description	-	string	Error description
code	-	string	Error code
acquiring_payments	+	array	Payment details
id	+	string	Payment ID
status	+	string	Current payment status. See the available values here
created_at	+	string	Payment creation date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
payment_details	+	object	`payment_details` sent in the request
amount_details	+	object	`amount_details` sent in the request
participant_details	+	object	`participant_details` sent in the request
error	-	object	Error details. Returned only if an error occurred
description	-	string	Error description
code	-	string	Error code

Successful response example

{
 "status": "ok",
 "session": {
   "id": "ps_592245",
   "status": "in_progress",
   "created_at": "2022-11-15T15:38:50.255803Z",
   "updated_at": "2022-11-15T15:38:50.336303Z",
   "acquiring_payments": [
     {
       "id": "pm_296251",
       "status": "in_progress",
       "created_at": "2022-11-15T15:38:50.357833Z",
       "payment_details": {
         "type": "moneysend",
         "moneysend": {}
       },
       "amount_details": {
         "amount": 978,
         "currency": "rub"
       },
       "participant_details": {
         "sender": {
           "citizenship_country_iso3": "AUS",
           "first_name": "Ivan",
           "last_name": "Ivanov",
           "middle_name": "Ivanovich",
           "country_iso3": "RUS",
           "state": "New York",
           "city": "Kazan",
           "postal_code": "420000",
           "street": "Nerkasova",
           "building": "1",
           "flat": "131",
           "tax_reference": "123456789012",
           "date_of_birth": "2010-01-01",
           "contacts": {
             "phone": {
               "full_number": "+79371234567",
               "country_iso3": "RUS",
               "operator_code": "937",
               "short_number": "1234567"
             },
            "email": "test@test.com"
          },
          "identity_document": {
            "id_type": "Паспорт гражданина Российской Федерации",
            "id_number": "123456789",
            "issue_date": "2020-01-01",
            "id_expiration_date": "2030-01-01",
            "division_code": "165-065",
            "issued_by": "OVD Kazani"
          },
          "documents_foreigner": {
            "id_type": "Виза",
            "issued_by": "OVD Kazani",
            "issue_date": "2020-01-01",
            "id_expiration_date": "2030-01-01"
          },
          "service_point": {
            "id": "1",
            "name": "point_on_lenina",
            "country_iso3": "Russia",
            "state": "Moscow",
            "city": "Moscow",
            "oktmo": "36634436111",
            "street": "Lenin avenue",
            "house": "1",
            "terminal_id": "123124"
          },
          "source_of_money": "salary",
          "description": "salary transfers"
        },
        "recipient": {
          "first_name": "Ivan",
          "last_name": "Sidorov",
          "middle_name": "Ivanovich",
          "date_of_birth": "2010-01-01",
          "currency": "TRY",
          "contacts": {
            "phone": {
              "full_number": "+79376151530",
              "country_iso3": "RUS",
              "operator_code": "937",
              "short_number": "7654321"
            },
            "email": "test@test.com"
          }
        }
      }
    }
  ]
 }
}

Unsuccessful response example

{
"error": {
 "code": "invalid_request",
 "description": "participant_details.recipient.full_name.not_blank"
  },
"status": "error"
}

`ready_to_confirm` webhook

Bank 131 sends this webhook when everything is ready for the transaction and the Bank is waiting for session/confirm or session/cancel. The confirm_information object in the webhook will contain detailed information on the payout amount, transaction fee, and conversion rate.

`confirm_information`

The object contains the following information:
● Source — amount in the payment currency
● Destination — payout amount and currency
● Fx_rate — conversion rate
● Commission — transaction fee charged in addition to Source

The confirm_information object needs to be sent within the session/confirm method.

Also, the webhook will contain the tcn_code_encoded parameter with the transaction code. This code must be made known to the Recipient, it will be needed to get the money. tcn_code_encoded is wrapped in BASE64 and needs to be decoded.

Webhook example

{
 "type": "ready_to_confirm",
 "session": {
   "id": "ps_1",
   "status": "in_progress",
   "created_at": "2022-11-15T13:22:31.847352Z",
   "updated_at": "2022-11-15T13:22:32.638464Z",
   "acquiring_payments": [
     {
       "id": "pm_1",
       "status": "pending",
       "created_at": "2022-11-15T13:22:32.132993Z",
       "payment_details": {
         "type": "moneysend",
         "moneysend": {}
       },
       "amount_details": {
         "amount": 9782,
         "currency": "RUB"
       },
       "participant_details": {
         "sender": {
           "full_name": "Ivan Ivanov Ivanovich",
           "first_name": "Ivan",
           "last_name": "Ivanov",
           "middle_name": "Ivanovich",
           "tax_reference": "123456789012",
           "country_iso3": "RUS",
           "city": "Kazan",
           "postal_code": "420000",
           "building": "1",
           "date_of_birth": "2008-01-01",
           "street": "Nerkasova",
           "flat": "131",
           "state": "New York",
           "description": "salary transfers",
           "identity_document": {
             "id_type": "Паспорт гражданина Российской Федерации",
             "id_number": "123456789",
             "issue_date": "2020-01-01",
             "division_code": "165-065",
             "issued_by": "OVD Kazani",
             "id_expiration_date": "2030-01-01"
           },
           "citizenship_country_iso3": "AUS",
           "documents_foreigner": {
             "id_type": "Виза",
             "issue_date": "2020-01-01",
             "issued_by": "OVD Kazani",
             "id_expiration_date": "2030-01-01"
           },
           "service_point": {
             "id": "1",
             "name": "point_on_lenina",
             "country_iso3": "Russia",
             "state": "Moscow",
             "city": "Moscow",
             "oktmo": "36634436111",
             "street": "lenin avenue",
             "house": "1",
             "terminal_id": "123124"
           },
           "source_of_money": "salary"
         },
         "recipient": {
           "full_name": "Ivan Sidorov Ivanovich",
           "first_name": "Ivan",
           "last_name": "Sidorov",
           "middle_name": "Ivanovich",
           "date_of_birth": "2008-11-08",
           "currency": "TRY",
           "contacts": {
             "phone": {
               "full_number": "+79377654321",
               "country_iso3": "RUS",
               "operator_code": "937",
               "short_number": "7654321"
             },
             "email": "test@test.com"
           }
         }
       }
     }
   ],
   "next_action": "confirm"
  },
 "confirm_information": {
   "exchanges": [
     {
       "id": "pm_1",
       "source": {
         "amount": 1000,
         "currency": "RUB"
       },
       "destination": {
         "amount": 300,
         "currency": "TRY"
       },
       "fx_rate": "0.3000",
       "commission": {
         "amount": 100,
         "currency": "RUB"
       }
     }
   ]
 },
 "details": {
   "tcn_code_encoded": "NTkyMTc0LTY5NDEyMjEx"
 }
}

`POST.../api/v1/session/confirm` payment_method

This method is used to confirm the payment after the ready_to_confirm webhook is received meaning that the sender agreed with the payment amount, conversion rate, and fee. The method should contain the confirm_information object as it is passed in the ready_to_confirm webhook.

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session ID from the response to `session/init`
confirm_information	+	object	`confirm_information` object from the `ready_to confirm` webhook as is
exchanges	+	object	Additional details
id	+	string	Transaction ID
source	+	object	Payment details
amount	+	float	Amount in minor values
currency	+	string	Currency
destination	+	object	Payout details
amount	+	float	Amount in minor values
currency	+	string	Currency
fx_rate	+	string	Conversion rate
commission	+	object	Fee details
amount	+	float	Amount in minor values
currency	+	string	Currency

Request example

{
  "session_id": "ps_1",
  "confirm_information": {
    "exchanges": [
      {
        "id": "pm_1",
        "source": {
          "amount": 1000,
          "currency": "RUB"
        },
        "destination": {
          "amount": 300,
          "currency": "TRY"
        },
        "fx_rate": "0.3000",
        "commission": {
          "amount": 100,
          "currency": "RUB"
        }
      }
    ]
  }
}

Response parameters

The response contents are identical to the contents of the response to bpa/session/init/payment.

Response example

{
    "status": "ok",
    "session": {
        "id": "ps_1634163",
        "status": "in_progress",
        "created_at": "2023-12-20T10:08:08.807876Z",
        "updated_at": "2023-12-20T10:08:40.947967Z",
        "acquiring_payments": [
            {
                "id": "pm_1062803",
                "status": "in_progress",
                "created_at": "2023-12-20T10:08:08.924899Z",
                "customer": {
                    "reference": "customer_reference"
                },
                "payment_details": {
                    "type": "moneysend",
                    "moneysend": {}
                },
                "amount_details": {
                    "amount": 45000,
                    "currency": "RUB"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Gabriil Akulov",
                        "first_name": "Gabriil",
                        "last_name": "Akulov",
                        "middle_name": "",
                        "country_iso3": "RUS",
                        "city": "Кашира",
                        "postal_code": "761290",
                        "building": "39",
                        "date_of_birth": "1998-03-15",
                        "street": "наб. Будапештсткая",
                        "flat": "1",
                        "state": "Свердловская область",
                        "description": "описание описания",
                        "identity_document": {
                            "id_type": "Паспорт гражданина Российской Федерации",
                            "id_number": "7012 244588",
                            "issue_date": "2020-03-01",
                            "division_code": "",
                            "issued_by": "ОВД ПО Кировскому району"
                        },
                        "citizenship_country_iso3": "RUS",
                        "service_point": {
                            "id": "1",
                            "name": "точка на Ленина",
                            "country_iso3": "RUS",
                            "state": "Москва",
                            "city": "Москва",
                            "street": "Ленина",
                            "house": "1",
                            "oktmo": "36634436111",
                            "terminal_id": "345"
                        },
                        "source_of_money": "зарплата",
                        "contacts": {
                            "phone": {
                                "full_number": "+79376151530",
                                "country_iso3": "RUS",
                                "operator_code": "937",
                                "short_number": "6151530"
                            }
                        }
                    },
                    "recipient": {
                        "full_name": "samidov burac",
                        "first_name": "samidov",
                        "last_name": "burac",
                        "middle_name": "",
                        "date_of_birth": "2005-03-15",
                        "currency": "TRY",
                        "contacts": {
                            "phone": {
                                "full_number": "+43523452345",
                                "country_iso3": "TUR",
                                "operator_code": "352",
                                "short_number": "3452345"
                            }
                        }
                    }
                }
            }
        ],
        "actions": {
            "confirm": "2023-12-20T10:09:01.904212Z"
        }
    }
}

`POST../api/v1/session/cancel` method

The method is used to cancel a payment.

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session ID from the response to `session/init`

Request example

"session_id": "ps_1"

Response parameters

The response contents are identical to the contents of the response to bpa/session/init/payment.

Response example

{
    "status": "ok",
    "session": {
        "id": "ps_1634164",
        "status": "in_progress",
        "created_at": "2023-12-20T10:09:30.979373Z",
        "updated_at": "2023-12-20T10:09:47.084110Z",
        "acquiring_payments": [
            {
                "id": "pm_1062804",
                "status": "pending",
                "created_at": "2023-12-20T10:09:31.100292Z",
                "customer": {
                    "reference": "customer_reference"
                },
                "payment_details": {
                    "type": "moneysend",
                    "moneysend": {}
                },
                "amount_details": {
                    "amount": 45000,
                    "currency": "RUB"
                },
                "participant_details": {
                    "sender": {
                        "full_name": "Gabriil Akulov",
                        "first_name": "Gabriil",
                        "last_name": "Akulov",
                        "middle_name": "",
                        "country_iso3": "RUS",
                        "city": "Кашира",
                        "postal_code": "761290",
                        "building": "39",
                        "date_of_birth": "1998-03-15",
                        "street": "наб. Будапештсткая",
                        "flat": "1",
                        "state": "Свердловская область",
                        "description": "описание описания",
                        "identity_document": {
                            "id_type": "Паспорт гражданина Российской Федерации",
                            "id_number": "7012 244588",
                            "issue_date": "2020-03-01",
                            "division_code": "",
                            "issued_by": "ОВД ПО Кировскому району"
                        },
                        "citizenship_country_iso3": "RUS",
                        "service_point": {
                            "id": "1",
                            "name": "точка на Ленина",
                            "country_iso3": "RUS",
                            "state": "Москва",
                            "city": "Москва",
                            "street": "Ленина",
                            "house": "1",
                            "oktmo": "36634436111",
                            "terminal_id": "345"
                        },
                        "source_of_money": "зарплата",
                        "contacts": {
                            "phone": {
                                "full_number": "+79376151530",
                                "country_iso3": "RUS",
                                "operator_code": "937",
                                "short_number": "6151530"
                            }
                        }
                    },
                    "recipient": {
                        "full_name": "samidov burac",
                        "first_name": "samidov",
                        "last_name": "burac",
                        "middle_name": "",
                        "date_of_birth": "2005-03-15",
                        "currency": "TRY",
                        "contacts": {
                            "phone": {
                                "full_number": "+43523452345",
                                "country_iso3": "TUR",
                                "operator_code": "352",
                                "short_number": "3452345"
                            }
                        }
                    }
                }
            }
        ]
    }
}

`POST../api/v1/session/status` method

If required, the payment partner can use this method to get session information. To learn more about the payment session, follow the link.

Available session statuses

Session statuses

Request parameters

Name	Mandatory	Type	Description
session_id	+	string	Session ID from the response to `session/init`

Request example

"session_id": "ps_1"

Response example

{
  "status": "ok",
  "session": {
    "id": "ps_1",
    "status": "in_progress",
    "created_at": "2022-11-15T15:38:50.255803Z",
    "updated_at": "2022-11-15T15:38:50.336303Z",
    "acquiring_payments": [
      {
        "id": "pm_1",
        "status": "in_progress",
        "created_at": "2022-11-15T15:38:50.357833Z",
        "payment_details": {
          "type": "moneysend",
          "moneysend": {}
        },
        "amount_details": {
          "amount": 1000,
          "currency": "rub"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanov Ivanovich",
            "first_name": "Ivan",
            "last_name": "Ivanov",
            "middle_name": "Ivanovich",
            "tax_reference": "123456789012",
            "country_iso3": "RUS",
            "city": "Kazan",
            "postal_code": "420000",
            "building": "1",
            "date_of_birth": "2008-01-01",
            "contacts": {
              "phone": {
                "full_number": "+79371234567",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "1234567"
              },
              "email": "test@test.com"
            },
            "street": "Nerkasova",
            "flat": "131",
            "state": "New York",
            "description": "salary transfers",
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "123456789",
              "issue_date": "2020-01-01",
              "division_code": "165-065",
              "issued_by": "OVD Kazani",
              "id_expiration_date": "2030-01-01"
            },
            "citizenship_country_iso3": "AUS",
            "documents_foreigner": {
              "id_type": "Виза",
              "issue_date": "2020-01-01",
              "issued_by": "OVD Kazani",
              "id_expiration_date": "2030-01-01"
            },
            "service_point": {
              "id": "1",
              "name": "point_on_lenina",
              "country_iso3": "RUS",
              "state": "Moscow",
              "city": "Moscow",
              "oktmo": "36634436111",
              "street": "Lenin avenue",
              "house": "1",
              "terminal_id": "123124"
            },
            "source_of_money": "salary"
          },
          "recipient": {
            "full_name": "Ivan Sidorov Ivanovich",
            "first_name": "Ivan",
            "last_name": "Sidorov",
            "middle_name": "Ivanovich",
            "date_of_birth": "2008-11-08",
            "currency": "TRY",
            "contacts": {
              "phone": {
                "full_number": "+79377654321",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "7654321"
              },
              "email": "test@test.com"
            }
          }
        }
      }
    ]
  }
}

`payment_finished` webhook

The Bank sends this webhook to finalize a transaction. The webhook body contains all the transaction parameters including its status (in the status field). If the session status is succeeded, the payment was successful. To learn more about the webhook, please see here.

POST.../api/v1/bpa/session/init/payment method​

Request parameters​

Request example​

Response parameters​

Successful response example​

Unsuccessful response example​

ready_to_confirm webhook​

Webhook example​

POST.../api/v1/session/confirm payment_method​

Request parameters​

Request example​

Response parameters​

Response example​

POST../api/v1/session/cancel method​

Request parameters​

Request example​

Response parameters​

Response example​

POST../api/v1/session/status method​

Available session statuses​

Request parameters​

payment_finished webhook​

`POST.../api/v1/bpa/session/init/payment` method

Request parameters

Request example

Response parameters

Successful response example

Unsuccessful response example

`ready_to_confirm` webhook

Webhook example

`POST.../api/v1/session/confirm` payment_method

Request parameters

Request example

Response parameters

Response example

`POST../api/v1/session/cancel` method

Request parameters

Request example

Response parameters

Response example

`POST../api/v1/session/status` method

Available session statuses

Request parameters

`payment_finished` webhook