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:
|
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:
|
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.
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.
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. |
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:
|
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:
|
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:
|
recipient_account_status | string | The user's status. Possible values:
|
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:
|
recipient_account_status | string | The user's status. Possible values:
|
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:
|
limit_exceeded | One of the operation limits was exceeded:
|
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:
|
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:
|
limit_exceeded | One of the operation limits was exceeded:
|
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:
|
all other values | Technical error; repeat the operation again later. |
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:
|
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:
|
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
}
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:
|
recipient_account_type | Recipient's account type. Possible values:
|
Code | Description |
---|---|
recipient_account_status | The user's status. Possible values:
|
recipient_account_type | Recipient's account type. Possible values:
|
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"}