Skip to main content

Accepting funds

On this page you will find the methods 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 a 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​

NameMandatoryTypeDescription
payment_details+objectPayment method
  type+stringPayment method name. Valid value: moneysend
  moneysend+objectDetails of payment via Moneysend
amount_details+objectPayment details
  amount+intAmount in minor values (To transfer 100 rubles, specify 10000)
  currency+stringPayment currency
participant_details+objectParticipant details
  sender+objectSender details
    citizenship_country_iso3+stringSender's country of citizenship according to ISO 3166-1 alpha-3
    first_name+stringSender's first name
    last_name+stringSender's last name
    middle_name-stringSender's patronymic
    country_iso3+stringSender's country of registration according to ISO 3166-1 alpha-3
    state-stringState or region of the sender's place of registration
    city+stringLocality of the sender's place of registration
    postal_code-stringPostal code of the sender's place of registration
    street-stringStreet of the sender's place of registration
    building+stringBuilding number of the sender's place of registration
    flat-stringApartment of the sender's place of registration
    tax_reference-stringSender's INN (12 digits)
    date_of_birth+stringSender's date of birth in the YYYY-MM-DD format. Make sure the sender is 18 years old or older
    contacts+objectSender's contacts
      phone+objectSender's phone number
        full_number+stringSender's full phone number in the +<country code><number> format
        country_iso3+stringSender's phone number country code according to ISO3
        operator_code+stringOperator code of the sender's phone number
        short_number+stringSender's phone number without the operator code
      email-stringSender's email
    identity_document+objectSender's identity document
      id_type+stringType of the sender's identity document. Valid values:
— Passport of a foreign citizen
— Passport of a citizen of the Russian Federation
      id_number+stringSender's identity document series and number (without spaces)
      issue_date+stringSender's identity document issue date in the YYYY-MM-DD format
      id_expiration_date-stringSender'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-stringCode of the division that issued the sender's identity document. Required if available in the document
      issued_by-stringName of the division that issued the sender's identity document. Required if available in the document
    documents_foreigner-objectNon-resident sender's identity document details. Required for non-residents only
      id_type+stringType of the non-resident sender's identity document. Valid values:
— Residence permit
— Temporary residence permit
— Migration card
— Visa
      issued_by-stringNon-resident sender's identity document issuing authority
      issue_date+stringNon-resident sender's identity document issue date in the YYYY-MM-DD format
      id_expiration_date+stringNon-resident sender's identity document expiry date in the YYYY-MM-DD format
    service_point+objectService point of accepting funds
      id-stringService point ID
      name-stringService point name
      country_iso3+stringService point country according to ISO 3166-1 alpha-3
      state-stringService point region/state
      city+stringService point locality
      oktmo+stringService point OKTMO
      street-stringService point street
      house-stringService point building
      terminal_id-stringTerminal/cash register ID
    source_of_money-stringSource of the sender's funds
    description-stringAdditional information
  recipient+objectRecipient details
    first_name+stringRecipient's first name
    last_name+stringRecipient's last name
    middle_name-stringRecipient's patronymic
    date_of_birth-stringRecipient's date of birth in the YYYY-MM-DD format. Make sure the recipient is 18 years old or older
    currency+stringPayout currency. Valid values: TRY, USD
    contacts+objectRecipient's contacts
      phone+objectRecipient's phone number
        full_number+stringRecipient's full phone number in the +<country code><number> format
        country_iso3+stringRecipient's phone number country code according to ISO3
        operator_code+stringOperator code of the recipient's phone number
        short_number+stringRecipient's phone number without the operator code
      email-stringRecipient's email
cash_details+objectAdditional information on the cash payment
  shift+stringCash 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": "RUS",
        "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​

NameMandatoryTypeDescription
status+stringRequest status
session+objectSession details
  id+stringSession ID. Remember it to use it to confirm/cancel the transaction or to get the transaction status
  status+stringCurrent session status. See the available values
  created_at+stringSession creation date and time in the RFC 3339 format. Example: 2022-11-15T15:38:50.255803Z
  updated_at+stringSession update date and time in the RFC 3339 format. Example: 2022-11-15T15:38:50.255803Z
  error-objectError details. Returned only if an error occurred
    description-stringError description
    code-stringError code
  acquiring_payments+arrayPayment details
    id+stringPayment ID
    status+stringCurrent payment status. See the available values
    created_at+stringPayment creation date and time in the RFC 3339 format. Example: 2022-11-15T15:38:50.255803Z
    payment_details+objectpayment_details sent in the request
    amount_details+objectamount_details sent in the request
    participant_details+objectparticipant_details sent in the request
error-objectError details. Returned only if an error occurred
  description-stringError description
  code-stringError 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": "RUS",
              "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": "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 payment_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​

NameMandatoryTypeDescription
session_id+stringSession ID from the response to session/init
confirm_information+objectconfirm_information object from the ready_to confirm webhook as is
  exchanges+objectAdditional details
    id+stringTransaction ID
    source+objectPayment details
      amount+floatAmount in minor values
      currency+stringCurrency
    destination+objectPayout details
      amount+floatAmount in minor values
      currency+stringCurrency
    fx_rate+stringConversion rate
    commission+objectFee details
      amount+floatAmount in minor values
      currency+stringCurrency
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​

NameMandatoryTypeDescription
session_id+stringSession 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. Learn more about the payment session.

Available session statuses​

Session statuses

Request parameters​

NameMandatoryTypeDescription
session_id+stringSession 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.