request-payment method

Description

Creates a payment, checks parameters and verifies that the merchant can accept the payment, or that funds can be transferred to a Yandex.Money user account.

Permissions required for making a payment to a merchant: payment.to-pattern (“Payment Pattern”) or payment-shop.

Permissions required for transferring funds to the accounts of other users: payment.to-account (“payee ID,” “ID type”) or payment-p2p.

Arguments for making a payment to a merchant

The parameters for making a payment to a merchant are defined by the counterparty when connecting to Yandex.Checkout. Additional information about payment parameters is provided in the payment solution protocol for merchants and integration scenarios.

Parameter Type Description
pattern_id string Payment Pattern ID. Corresponds to the merchant's scid (payment form number).
* string Payment Pattern parameters required by the merchant.
Parameter Type Description
pattern_id string Payment Pattern ID. Corresponds to the merchant's scid (payment form number).
* string Payment Pattern parameters required by the merchant.

Arguments for transferring funds to the accounts of other users

Parameter Type Description
pattern_id string Constant value: p2p.
to string ID of the transfer recipient (account number, phone number, or email).
amount amount Amount to pay (how much the sender will pay).
amount_due amount Amount to be received (credited to the receipient's account after payment).
comment string Payment comment, displayed in the sender's history.
message string Comments on the transfer (displayed to the recipient).
label string The payment label. Optional parameter.
codepro boolean The true value indicates that the transfer is protected by a secret code. Omitted by default (normal transfer).
hold_for_pickup boolean Indicates that deferred transfer (sending a transfer and holding it until it can be credited) is allowed. If the parameter is present and is set to true, this is deferred transfer mode.
expire_period int Number of days during which:
  • A transfer recipient can enter the secret code and receive the transfer to the account.
  • A deferred transfer recipient can receive the transfer.
The parameter value must be between 1 and 365. Optional parameter. By default, 1.
Parameter Type Description
pattern_id string Constant value: p2p.
to string ID of the transfer recipient (account number, phone number, or email).
amount amount Amount to pay (how much the sender will pay).
amount_due amount Amount to be received (credited to the receipient's account after payment).
comment string Payment comment, displayed in the sender's history.
message string Comments on the transfer (displayed to the recipient).
label string The payment label. Optional parameter.
codepro boolean The true value indicates that the transfer is protected by a secret code. Omitted by default (normal transfer).
hold_for_pickup boolean Indicates that deferred transfer (sending a transfer and holding it until it can be credited) is allowed. If the parameter is present and is set to true, this is deferred transfer mode.
expire_period int Number of days during which:
  • A transfer recipient can enter the secret code and receive the transfer to the account.
  • A deferred transfer recipient can receive the transfer.
The parameter value must be between 1 and 365. Optional parameter. By default, 1.
Tip.

The transfer amount is credited to the recipient, minus the transfer commission. The sender can set only one of the following parameters:

  • amount — The amount for the sender to pay (includes the service's commission).
  • amount_due — The received amount that will be credited to the recipient's amount.
Tip.

After sending "request-payment", the user can be shown the commission for the payment. The response to the request will show the contract_amount. Use this formula to calculate the commission:

Commission = contract_amount - amount_due

The commission is rounded to the kopek (two decimal points). A commission that is less than one kopek is always rounded up to one kopek.

Tip.

Any transfer can have a payment label assigned to it. A payment label is a type of ID that is assigned by the application.

As a result, you can select transfers in the history using a certain label. For example, you can use a code or an item ID from your application as a payment label. Labels up to 64 symbols long are allowed. Label values are case-sensitive.

Input parameters for mobile phone service payment

Parameter Type Description
pattern_id string Constant value: phone-topup.
phone-number string

Phone number in ITU-T E.164 format: the full number, starting with 7.

Only numbers from mobile service providers in Russia are supported. Example: 79219990099
amount amount Payment amount. A fee can be subtracted from this amount; the fee depends on the operator.
Parameter Type Description
pattern_id string Constant value: phone-topup.
phone-number string

Phone number in ITU-T E.164 format: the full number, starting with 7.

Only numbers from mobile service providers in Russia are supported. Example: 79219990099
amount amount Payment amount. A fee can be subtracted from this amount; the fee depends on the operator.
Tip.

The phone number in ITU-T E.164 format is a string of digits up to 15 symbols long representing the full international number of the user's phone, without the '+' sign. For example, the phone number +7(921)999-00-99 is written as 79219990099

Test payment

Use a test payment to check how your application works, without making real payments.

In testing mode, you can make any type of payment by adding debugging parameters to the method parameters:

Parameter Type Description
test_payment boolean Indicates a test payment if the value of the field is true.
test_card string Optional field. Indicates there is a test bank card if the value of the field is available.
test_result string

Desired result of the test payment. Possible values:

  • success — Completed successfully.
  • Error code from the table — The method returns the specified error code.
  • Other value — The method returns the error illegal_params.
Parameter Type Description
test_payment boolean Indicates a test payment if the value of the field is true.
test_card string Optional field. Indicates there is a test bank card if the value of the field is available.
test_result string

Desired result of the test payment. Possible values:

  • success — Completed successfully.
  • Error code from the table — The method returns the specified error code.
  • Other value — The method returns the error illegal_params.
Tip.

The Yandex.Money server checks all the parameters of a method and can return an error if these parameters are invalid, regardless of the value of the test_result parameter.

Returns

The method returns the following parameters:

Parameter Type Description
status string Operation result code (see the table).
error string Operation processing error code (additional description for the status field). Present only for errors.
money_source object Payment methods available to the application, see Available payment methods. Present only on success.
request_id string ID of the payment request. Present only on success.
contract_amount amount The amount to deduct from the account in the payer's account currency (how much the user will pay including the commission). Present when the method was completed successfully or for the error not_enough_funds.
balance amount Current balance on the user's account. Present if the following conditions are met:
  • The method was executed successfully.
  • The access token has the account-info permission.
recipient_account_status string

The user's status. Possible values:

  • anonymous — Anonymous account.
  • named — Named account.
  • identified — Identified account.
recipient_account_type string Recipient's account type. This parameter is present if the method was successfully executed when transferring funds to another Yandex.Money user account.
protection_code string The secret code for this transfer. The parameter is present if the codepro=true input parameter was set. A string of 4 decimal digits that may include leading zeros. The parameter must be processed as a string.
account_unblock_uri string The address to send the user to in order to unblock an account. This field is present if the account_blocked error occurred.
ext_action_uri string The address to send the user to in order to complete necessary actions if the ext_action_required error occurs.
Parameter Type Description
status string Operation result code (see the table).
error string Operation processing error code (additional description for the status field). Present only for errors.
money_source object Payment methods available to the application, see Available payment methods. Present only on success.
request_id string ID of the payment request. Present only on success.
contract_amount amount The amount to deduct from the account in the payer's account currency (how much the user will pay including the commission). Present when the method was completed successfully or for the error not_enough_funds.
balance amount Current balance on the user's account. Present if the following conditions are met:
  • The method was executed successfully.
  • The access token has the account-info permission.
recipient_account_status string

The user's status. Possible values:

  • anonymous — Anonymous account.
  • named — Named account.
  • identified — Identified account.
recipient_account_type string Recipient's account type. This parameter is present if the method was successfully executed when transferring funds to another Yandex.Money user account.
protection_code string The secret code for this transfer. The parameter is present if the codepro=true input parameter was set. A string of 4 decimal digits that may include leading zeros. The parameter must be processed as a string.
account_unblock_uri string The address to send the user to in order to unblock an account. This field is present if the account_blocked error occurred.
ext_action_uri string The address to send the user to in order to complete necessary actions if the ext_action_required error occurs.

Operation processing result codes:

Code Description
success Success.
refused Payment refused; the reason is explained in the error field. Final state.
hold_for_pickup The payment recipient was not found, and funds will be sent when requested. Success.
Code Description
success Success.
refused Payment refused; the reason is explained in the error field. Final state.
hold_for_pickup The payment recipient was not found, and funds will be sent when requested. Success.

If an error occurred while processing the transaction, the error code is returned:

Code Description
illegal_params Required payment parameters are either missing or have invalid values.
illegal_param_label Invalid value for the label parameter.
illegal_param_to Invalid value for the to parameter.
illegal_param_amount Invalid value for the amount parameter.
illegal_param_amount_due Invalid value for the amount_due parameter.
illegal_param_comment Invalid value for the comment parameter.
illegal_param_message Invalid value for the message parameter.
illegal_param_expire_period Invalid value for the expire_period parameter.
not_enough_funds The payer's account does not have sufficient funds to make the payment. Additional funds should be credited to the account, and a new payment will need to be processed.
payment_refused The merchant refused to accept the payment (for example, the user tried to purchase an item that is not in stock).
payee_not_found The transfer recipient was not found. The specified account does not exist, or a phone number or email address was specified that is not linked to a user account or payee.
authorization_reject Authorization of the payment was refused. Possible reasons:
  • A transaction with the current parameters is forbidden for this user.
  • The user did not accept the User Agreement for the Yandex.Money service.
limit_exceeded One of the operation limits was exceeded:
  • For the total amount of operations for the access token granted.
  • For the total amount of operations over a period of time for the access token granted.
  • Yandex.Money restrictions for various types of operations.
account_blocked The user's account has been blocked. In order to unblock the account, the user must be redirected to the address specified in the account_unblock_uri field.
ext_action_required

This type of payment cannot be made at this time. To be able to make these types of payments, the user must go to the page with the ext_action_uri address and follow the instructions on that page. This may be any of the following actions:

  • Entering identification data.
  • Accepting the offer.
  • Performing other actions according to the instructions.
all other values Technical error; repeat the operation again later.
Code Description
illegal_params Required payment parameters are either missing or have invalid values.
illegal_param_label Invalid value for the label parameter.
illegal_param_to Invalid value for the to parameter.
illegal_param_amount Invalid value for the amount parameter.
illegal_param_amount_due Invalid value for the amount_due parameter.
illegal_param_comment Invalid value for the comment parameter.
illegal_param_message Invalid value for the message parameter.
illegal_param_expire_period Invalid value for the expire_period parameter.
not_enough_funds The payer's account does not have sufficient funds to make the payment. Additional funds should be credited to the account, and a new payment will need to be processed.
payment_refused The merchant refused to accept the payment (for example, the user tried to purchase an item that is not in stock).
payee_not_found The transfer recipient was not found. The specified account does not exist, or a phone number or email address was specified that is not linked to a user account or payee.
authorization_reject Authorization of the payment was refused. Possible reasons:
  • A transaction with the current parameters is forbidden for this user.
  • The user did not accept the User Agreement for the Yandex.Money service.
limit_exceeded One of the operation limits was exceeded:
  • For the total amount of operations for the access token granted.
  • For the total amount of operations over a period of time for the access token granted.
  • Yandex.Money restrictions for various types of operations.
account_blocked The user's account has been blocked. In order to unblock the account, the user must be redirected to the address specified in the account_unblock_uri field.
ext_action_required

This type of payment cannot be made at this time. To be able to make these types of payments, the user must go to the page with the ext_action_uri address and follow the instructions on that page. This may be any of the following actions:

  • Entering identification data.
  • Accepting the offer.
  • Performing other actions according to the instructions.
all other values Technical error; repeat the operation again later.
Important. When processing a payment, Yandex.Money normally connects to the merchant webserver, which is why the method response time may take up to 30 seconds. While the request-payment method is being processed, the application should display an informational message to the buyer, such as "waiting for a response from the merchant".
Important. Successful execution of the request-payment method does not guarantee that the payment process will be completed successfully, since payment authorization is performed when calling the process-payment method.

Available payment methods

The money_source field in the response contains a list of methods available for making this payment. Each method contains a set of attributes.

If none of the methods described below can be used for the payment, the money-source field will be empty.

Possible payment methods:

Code Description
wallet Payment using funds on the user's account.
cards Payment using bank cards that are linked to the account.
Code Description
wallet Payment using funds on the user's account.
cards Payment using bank cards that are linked to the account.

Attributes of the method of payment from the user's account:

Attribute Type Description
allowed boolean Flag indicating whether this payment method is allowed by the user.
Attribute Type Description
allowed boolean Flag indicating whether this payment method is allowed by the user.

Attributes of the method of payment with a bank card:

Attribute Type Description
allowed boolean Flag indicating whether this payment method is allowed by the user.
csc_required boolean Indicates whether the CVV2/CVC2 code is required for authorizing payment using a bank card.
item object Description of the bank card linked to the account.
Attribute Type Description
allowed boolean Flag indicating whether this payment method is allowed by the user.
csc_required boolean Indicates whether the CVV2/CVC2 code is required for authorizing payment using a bank card.
item object Description of the bank card linked to the account.

Parameters for the bank card description:

Attribute Type Description
id string Identifier of the bank card linked to the account. It must be specified in the process-payment method in order to complete payment using the selected card.
pan_fragment string A fragment of the bank card number. This field is only present for a linked bank card. May be omitted if unknown.
type string Card type. May be omitted if unknown. Possible values:
  • Visa
  • MasterCard
  • American Express
  • JCB
Attribute Type Description
id string Identifier of the bank card linked to the account. It must be specified in the process-payment method in order to complete payment using the selected card.
pan_fragment string A fragment of the bank card number. This field is only present for a linked bank card. May be omitted if unknown.
type string Card type. May be omitted if unknown. Possible values:
  • Visa
  • MasterCard
  • American Express
  • JCB

If the method is available for the given merchant and allowed by the user, the response will have the method name and the "allowed" flag set to "true".

For instance:

"wallet": {
  "allowed": true
},
"cards": {
  "allowed": true,
  "csc_required": true,
  "items": [
    {
      "id": "card-385244400",
      "pan_fragment": "5280****7918",
      "type": "MasterCard"
    },
    {
      "id": "card-385244401",
      "pan_fragment": "4008****7919",
      "type": "Visa"
    }
  ]
}

If the method is available but is not allowed by the user, the response will have the method name and the "allowed" flag set to "false".

For instance:

"wallet": {
  "allowed": false
},
"cards": {
  "allowed": false
}
Tip.

The application can request additional permissions for making payments. The request for additional permissions is made by repeating the request for user authorization of the application.

Transfer recipient data

When a transfer to another user account is requested, the request-payment method returns the following fields:

Code Description
recipient_account_status

The user's status. Possible values:

  • anonymous — Anonymous account.
  • named — Named account.
  • identified — Identified account.
recipient_account_type

Recipient's account type. Possible values:

  • personal — User account in Yandex.Money.
  • professional — Professional business account in Yandex.Money.
Code Description
recipient_account_status

The user's status. Possible values:

  • anonymous — Anonymous account.
  • named — Named account.
  • identified — Identified account.
recipient_account_type

Recipient's account type. Possible values:

  • personal — User account in Yandex.Money.
  • professional — Professional business account in Yandex.Money.

Examples

Request example for paying for mobile phone service:

POST /api/request-payment HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 61

pattern_id=phone-topup&phone-number=79219990099&amount=300.00

Request example for transferring funds to another user account:

POST /api/request-payment HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 234

pattern_id=p2p&to=41001101140&amount=1000.00&message=%D0%9D%D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%20%D0%BF%D0%BB%D0%B0%D1%82%D0%B5%D0%B6%D0%B0&comment=%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B5%20%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B0%D1%82%D0%B5%D0%BB%D1%8E

Request example for transferring funds to another user account using a linked phone number:

POST /api/request-payment HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 256

pattern_id=p2p&to=79219990099&identifier_type=phone&amount=1000.00&message=%d0%97%d0%b0+%d0%b2%d0%ba%d1%83%d1%81%d0%bd%d1%8b%d0%b9+%d0%b1%d1%83%d0%b1%d0%bb%d0%b8%d0%ba&comment=%d0%ba%d1%83%d0%bf%d0%b8%d1%82%d0%b5+%d0%b1%d1%83%d0%b1%d0%bb%d0%b8%d0%ba%d0%b8!

Successful payment response example:

{  "status": "success",  "wallet": {  "allowed": true  },  "cards": {    "allowed": true,    "csc_required": true,    "items": [      {        "id": "card-385244400",        "pan_fragment": "5280****7918",        "type": "MasterCard"      },      {        "id": "card-385244401",        "pan_fragment": "4008****7919",        "type": "Visa"      }    ]  },  "request_id": "1234567",  "contract": "Payment for services provided by Superphone Inc, phone number +7-9xx-xxx-xx-xx, amount 300.00 RUB",  "balance": 1000.00}

Response example for refusal:

{  "status": "refused",  "error": "payment_refused",  "error_description": "Subscriber does not exist"}