Money transfers without opening an account

This functionality allows individuals to transfer funds from Russia abroad without opening an account.

Countries to which you can make a transfer

Country	Country code	Transfer method	Transfer currency	Limitations
Turkey	TUR	Cash	US dollar (USD)	Available service point in Turkey
Turkey	TUR	By IBAN	Turkish lira (TRY)	No limitations
Kyrgyzstan	KGZ	By bank card number	Kyrgyzstani som (KGS)	Only transfers to MBANK cards are supported

The following terms are used in the documentation:

• Payment partner – an entity that accepts, transfers, and pays out (in case of a refund) funds.
• Sender – an individual who transfers funds.
• Recipient – an individual who receives the funds transferred from the Sender. Note that the Sender can be the Recipient too in case of a refund or transfer to yourself.
• Transfer code - transfer control number received from the payment partner. It is required to get the money.
• Payment – a transaction within which funds are accepted from the Sender.
• Payout – a transaction within which funds are paid out to the Recipient.

Note that:

• Money transfer operations are only available for individuals 18 years old or older.
• When filling in information on the Recipient, make sure the data you specify matches the passport the Recipient will use to receive the money (i.e. most likely using the Latin alphabet).
• All money transfer transactions are made within multi-sessions. A single multi-session can combine several transactions, such as a deposit (debiting from the Sender) and a payout (crediting to the Recipient).

info

Currency exchange rates can be lowered for promotions.

When conducting a transaction on a promotional rate, pass the identifier (id) of the corresponding promotional rate in X-PARTNER-PROJECT upon authentication.

Main scenario of money transfers

1. Before starting a transfer, you can query the rate for the last transaction using the bpa/calculate method.
2. To debit a bank card or make a payout to a bank card, you will need to tokenize the card.
3. Send a request to start the transfer using the bpa/session/multi/init/payment method.
4. Wait for a ready_to_confirm webhook indicating that the transaction can be processed at the specified rate. The response may contain other additional information.

   If the exchange rate changes after the payment is confirmed and before it is confirmed by the provider, the transaction will be canceled.

5. The Sender's funds will be frozen for transfer, the write-off should be confirmed with 3DS.
6. Once a ready_to_confirm webhook is received, confirm the transaction with session/confirm or cancel it with session/cancel.
7. Wait for an action_required webhook with a link to complete 3DS authentication, after which the funds will be debited and then credited to the Recipient.
8. Wait for a payment_finished webhook with transfer confirmation.

Bank card tokenization

In order to pass the Recipient's and Sender's bank card data in encrypted form, you can set up tokenization on the Bank 131 side. To do this, connect the tokenization widget and payment form widget.

The design of the widgets can be customized to fit your solution.

You can save the token received with the widget as a recurring token for future transfers, so that you don't have to pass your bank card information every time.
More about transfers with recurring token

Sequence diagram of a money transfer

POST.../api/v1/bpa/calculate method

This method is used to calculate currency exchange rates for money transfers.

A currency exchange can only be made from rub to another currency or from another currency to rub, so it is required to pass the currency = rub value either in source or in destination in the amounts object.

There are two ways to calculate the currency exchange rate for a money transfer:

• Direct rate: specify the amount to be sent in rubles and calculate the amount to be received in the target currency.
• Indirect rate: specify the amount to be received in the target currency and calculate the amount to be sent in rubles.

Endpoint

/api/v1/bpa/calculate

Request parameters

Name	Mandatory	Type	Description
amounts	+	object	Exchange amount and currency
source	+	object	Amount and currency to write off of the sender
amount	+	number	Amount in decimal format (kopecks) to calculate the direct exchange rate, or the null value to calculate the indirect exchange rate
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub, try, uzs
destination	+	object	Amount and currency to be paid to the recipient
amount	+	number	Amount in decimal format (kopecks) to calculate the indirect exchange rate, or the null value to calculate the direct exchange rate
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub, try, uzs

Request examples

Direct rate, from RUB to TRY

curl -X POST \
https://demo.bank131.ru/api/v1/bpa/calculate   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "amounts": {
    "source": {
      "amount": 357912,
      "currency": "RUB"
    },
    "destination": {
      "amount": null,
      "currency": "TRY"
    }
  }
}

Indirect rate, from UZS to RUB

curl -X POST \
https://demo.bank131.ru/api/v1/bpa/calculate   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "amounts": {
    "source": {
      "amount": null,
      "currency": "RUB"
    },
    "destination": {
      "amount": 46943404,
      "currency": "UZS"
    }
  }
}

Response parameters

Name	Mandatory	Type	Description
amounts	+	object	Conversion rate calculation
source	+	object	Amount and currency to write off of the sender
amount	+	number	Amount calculated in the sender's currency (rubles)
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub
destination	+	object	Amount and currency to be paid to the recipient
amount	+	number	Calculated amount to be received
currency	+	string	ISO 4217 currency code. Case insensitive. Options: try, uzs
transfer_fee	+	object	Sender's fee for money transfer
amount	+	number	Fee amount to be paid by the sender for the money transfer
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub
sms_fee	+	object	Sender's fee for SMS notification to the recipient
amount	+	number	Fee amount to be paid for SMS notification to the recipient
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub
payment	+	object	Total amount to write off of the sender
amount	+	number	Total amount to be written off the sender including all fees. Calculated as source + transfer_fee + sms_fee
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub
exchanges	+	object	Exchange rate data
source	+	object	Amount and currency to write off of the sender passed in the request
amount	+	number	Amount in decimal format (kopecks) to calculate the direct exchange rate, or the null value to calculate the indirect exchange rate
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub, try, uzs
destination	+	object	Amount and currency to be paid to the recipient passed in the request
amount	+	number	Amount in decimal format (kopecks) to calculate the indirect exchange rate, or the null value to calculate the direct exchange rate
currency	+	string	ISO 4217 currency code. Case insensitive. Options: rub, try, uzs
rate	+	object	Exchange rate
fx_rate	+	number	Ratio of the currency to ruble (of the target currency to the write-off currency)
quantity	+	number	Quantity of currency units. Some currencies are calculated in tens, hundreds or thousands of units, the current rates are available on the Bank of Russia website
error	-	object	Error

Response examples

Direct rate, from RUB to TRY

{
  "amounts": {
    "source": {
      "amount": 357913,
      "currency": "RUB"
    },
    "destination": {
      "amount": 131426,
      "currency": "TRY"
    },
    "transfer_fee": {
      "amount": 0,
      "currency": "RUB"
    },
    "sms_fee": {
      "amount": 0,
      "currency": "RUB"
    },
    "payment": {
      "amount": 5400,
      "currency": "RUB"
    }
  },
  "exchanges": {
    "source": {
      "amount": 357912,
      "currency": "RUB"
    },
    "destination": {
      "amount": null,
      "currency": "TRY"
    },
    "rate": {
      "fx_rate": 2.7233,
      "quantity": 1
    }
  }
}

Indirect rate, from UZS to RUB

{
  "amounts": {
    "source": {
      "amount": 357912,
      "currency": "RUB"
    },
    "destination": {
      "amount": 46943404,
      "currency": "UZS"
    },
    "transfer_fee": {
      "amount": 0,
      "currency": "RUB"
    },
    "sms_fee": {
      "amount": 0,
      "currency": "RUB"
    },
    "payment": {
      "amount": 9193,
      "currency": "RUB"
    }
  },
  "exchanges": {
    "source": {
      "amount": null,
      "currency": "RUB"
    },
    "destination": {
      "amount": 46943404,
      "currency": "UZS"
    },
    "rate": {
      "fx_rate": 76.2433,
      "quantity": 10000
    }
  }
}

Unsuccessful response example

{
    "status": "error",
    "error": {
        "description": "Invalid request",
        "code": "invalid_request"
    }
}

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

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": "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"
            }
          }
        }
      }
    ],
    "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 method

This method is used to confirm the payment after a 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	+	int	Amount in minor values
currency	+	string	Currency
destination	+	object	Payout details
amount	+	int	Amount in minor values
currency	+	string	Currency
fx_rate	+	string	Conversion rate
commission	+	object	Fee details
amount	+	int	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"
    }
  }
}

action_required webhook

The Bank is waiting for you or your users to take the necessary action.

The Bank sends this webhook to you when you or your users need to carry out certain actions to proceed with the operation. For example, a user might need to go through 3D Secure authentication when paying via bank card.

More about the webhook

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.
More about the payment session

Available 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.
More about the webhook