Skip to main content

Paying out funds

On this page you will find the method and webhooks that the payment partner will need to refund the transferred funds.

Please note that the transferred funds can only be refunded in full.

The general order of requests is as follows:

  • The recipient contacts the payment partner with the passport and transfer code received when the transfer was made.
  • The payment partner initiates a payout session and sends to the Bank information on the Recipient.
  • 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 and recipient.
  • Once the ready_to_confirm webhook is received, confirm the transaction with session/confirm or cancel it with session/cancel.
  • To complete the transaction, wait for a payment_finished webhook.

POST…/api/v1/cash/payout/session/init method

This method is used to initiate the payout.

Note that the received transfer code must be wrapped in BASE64 and put in the tcn_code_encoded parameter.

Request parameters

NameMandatoryTypeDescription
tcn_code_encoded+stringTransaction code received from the recipient and wrapped in BASE64. Example: “MzU4MDctMjM1ODk=”
payment_method+objectPayment method
  type+stringPayment method name. Valid value: moneysend
  moneysend+objectDetails of payment via Moneysend
amount_details+objectPayment details
  amount+intPayout amount
  currency+stringPayment currency
participant_details+objectParticipant details
  recipient+objectRecipient details
    citizenship_country_iso3+stringRecipient's country of citizenship according to ISO3166-1 alpha-3
    first_name+stringRecipient's first name
    last_name+stringRecipient's last name
    middle_name-stringRecipient's middle name
    country_iso3+stringRecipient's country of registration according to ISO 3166-1 alpha-3
    state-stringState or region of the recipient's place of registration
    city+stringLocality of the recipient's place of registration
    postal_code-stringPostal code of the recipient's place of registration
    street-stringStreet of the recipient's place of registration
    building+stringBuilding number of the recipient's place of registration
    flat-stringApartment of the recipient's place of registration
    tax_reference-stringRecipient's INN (12 digits)
    date_of_birth+stringRecipient's date of birth in the YYYY-MM-DD format. Make sure the recipient is 18 years old or older
    contactsobjectRecipient's contacts
      phoneobjectRecipient'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
    identity_document+objectRecipient's identity document
      id_type+stringType of the recipient's identity document. Valid values:
- Passport of a foreign citizen
- Passport of a citizen of the Russian Federation
      id_number+stringRecipient's identity document series and number (without spaces)
      issue_date+stringRecipient's identity document issue date in the YYYY-MM-DD format
      id_expiration_date-stringRecipient'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 recipient's identity document. Required if available in the document
      issued_by-stringName of the division that issued the recipient's identity document. Required if available in the document
    documents_foreigner-objectNon-resident recipient's identity document details. Required for non-residents only
      id_type+stringType of the non-resident recipient's identity document. Valid values:
- Residence permit
- Temporary residence permit
- Migration card
- Visa
      issued_by-stringNon-resident recipient's identity document issuing authority
      issue_date+stringNon-resident recipient's identity document issue date in the YYYY-MM-DD format
      id_expiration_date+stringNon-resident recipient'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-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
  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 middle name
    contactsobjectSender's contacts
      phoneobjectSender'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
cash_details+objectAdditional information on the cash payment
shift+stringCash register shift

Request example

{
"tcn_code_encoded": "NTkyMjM3LTg5MjEzNDk5",
"payment_method": {
"type": "moneysend",
"moneysend": {}
},
"cash_details": {
"shift": "159"
},
"amount_details": {
"amount": 1000,
"currency": "rub"
},
"participant_details": {
"recipient": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Sidorov",
"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": "2008-01-01",
"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",
"contacts": {
"phone": {
"full_number": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"email": "test@test.com"
}
},
"sender": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
}
}

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 here
  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
  payments+arrayPayment details
    id+stringPayment ID
    status+stringCurrent payment status. See the available values here
    created_at+stringPayment creation date and time in the RFC 3339 format. Example: 2022-11-15T15:38:50.255803Z
payment_method+objectPayment method
  type+stringPayment method name. Valid value: moneysend
    participant_details+objectpayment_details sent in the request
  recipient+objectRecipient details
    citizenship_country_iso3+string Recipient's country of citizenship according to ISO3166-1 alpha-3
    first_name+stringRecipient's first name
    last_name+stringRecipient's last name
    middle_name-stringRecipient's middle name
    country_iso3+stringRecipient's country of registration according to ISO 3166-1 alpha-3
    state-stringState or region of the recipient's place of registration
    city+stringLocality of the recipient's place of registration
    postal_code-stringPostal code of the recipient's place of registration
    street-stringStreet of the recipient's place of registration
    building+stringBuilding number of the recipient's place of registration
    flat-stringApartment of the recipient's place of registration
    tax_reference-stringRecipient's INN (12 digits)
    date_of_birth+stringRecipient's date of birth in the YYYY-MM-DD format. Make sure the recipient is 18 years old or older
    contactsobjectRecipient's contacts
      phoneobjectRecipient'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
    identity_document+objectRecipient's identity document
      id_type+stringType of the recipient's identity document. Valid values:
- Passport of a foreign citizen
- Passport of a citizen of the Russian Federation
      id_number+stringRecipient's identity document series and number (without spaces)
      issue_date+stringRecipient's identity document issue date in the YYYY-MM-DD format
      id_expiration_date-stringRecipient'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 recipient's identity document. Required if available in the document
      issued_by-stringName of the division that issued the recipient's identity document. Required if available in the document
    documents_foreigner-objectNon-resident recipient's identity document details. Required for non-residents only
      id_type+stringType of the non-resident recipient's identity document. Valid values:
- Residence permit
- Temporary residence permit
- Migration card
- Visa
      issued_by-stringNon-resident recipient's identity document issuing authority
      issue_date+stringNon-resident recipient's identity document issue date in the YYYY-MM-DD format
      id_expiration_date+stringNon-resident recipient'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-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
  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 middle name
    contactsobjectSender's contacts
      phoneobjectSender'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
    customer_verificationobjectRecipient details specified when the payment transaction was created
      first_name+stringRecipient's first name
      last_name+stringRecipient's last name
      middle_name-stringRecipient's middle name
      date_of_birth+stringRecipient's date of birth. Make sure the recipient is 18 years old or older
      contactsobjectRecipient's contacts
        phoneobjectRecipient'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
amount_details+objectPayout details
  amount+intPayout amount
  currency+stringPayout currency
error-objectError details. Returned only if an error occurred
  description-stringError description
  code-stringError code

Successful response example

The response will contain the customer_verification object with information on the sender. Compare the data sent within customer_verification with the data in the recipient's identity document. If the data mismatches, the funds must not be paid out.


{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"updated_at": "2022-11-01T02:03:00.000000Z",
"payments": [
{
"id": "po_2018",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"payment_method": {
"type": "moneysend"
},
"participant_details": {
"recipient": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Sidorov",
"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": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"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",
"customer_verification": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
},
"sender": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"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

Wait for this webhook to confirm or cancel the payout. The webhook contents are identical to the contents of the response to cash/payout/session/init.

Webhook example


"type": "ready_to_confirm",
{
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"updated_at": "2022-11-01T02:03:00.000000Z",
"payments": [
{
"id": "po_2018",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"payment_method": {
"type": "moneysend"
},
"participant_details": {
"recipient": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Sidorov",
"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": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"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",
"customer_verification": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
},
"sender": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
}
}
]
}
}

POST.../api/v1/session/confirm method

This method is used to confirm the payout after the ready_to_confirm webhook is received meaning that the recipient agreed with the payout amount.

Once the payment partner calls this method, the payout gets confirmed and cannot be revoked or canceled.

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 cash/payout/session/init.

Response example

  {
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"updated_at": "2022-11-01T02:03:00.000000Z",
"payments": [
{
"id": "po_2018",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"payment_method": {
"type": "moneysend"
},
"participant_details": {
"recipient": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Sidorov",
"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": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"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",
"customer_verification": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
},
"sender": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
}
}
]
}
}

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

The method is used to cancel the payout.

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 cash/payout/session/init.

Response example

  {
"status": "ok",
"session": {
"id": "3230",
"status": "in_progress",
"created_at": "2022-11-01T02:03:00.000000Z",
"updated_at": "2022-11-01T02:03:00.000000Z",
"payments": [
{
"id": "po_2018",
"status": "pending",
"created_at": "2022-11-01T02:03:00.000000Z",
"payment_method": {
"type": "moneysend"
},
"participant_details": {
"recipient": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Sidorov",
"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": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"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",
"customer_verification": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
},
"sender": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"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). The webhook contents are identical to the contents of the response to cash/payout/session/init. To learn more about the webhook, please see here.

Webhook example

"type": "payment_finished",
{
"status": "ok",
"session": {
"id": "3230",
"status": "accepted",
"created_at": "2022-11-01T02:03:00.000000Z",
"updated_at": "2022-11-01T02:03:00.000000Z",
"payments": [
{
"id": "po_2018",
"status": "succeeded",
"created_at": "2022-11-01T02:03:00.000000Z",
"payment_method": {
"type": "moneysend"
},
"participant_details": {
"recipient": {
"citizenship_country_iso3": "AUS",
"first_name": "Ivan",
"last_name": "Sidorov",
"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": "+79377654321",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "7654321"
},
"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",
"customer_verification": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"date_of_birth": "2010-01-01",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
}
},
"sender": {
"first_name": "Ivan",
"last_name": "Ivanov",
"middle_name": "Ivanovich",
"contacts": {
"phone": {
"full_number": "+79371234567",
"country_iso3": "RUS",
"operator_code": "937",
"short_number": "1234567"
},
"email": "test@test.com"
}
}
}
]
}
}