request-payment method — YooMoney wallet API

Request-payment method

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

Required permissions:

for making a payment to a merchant: payment.to-pattern (“Payment Pattern”) or payment-shop.
for transferring funds to the accounts of other users: payment.to-account (“payee ID”, “ID type”) or payment-p2p.

Request

Making a payment to a merchant

The parameters for making a payment to a merchant are defined by the counterparty when connecting to YooMoney for Business. Additional information about payment parameters is provided in the payment solution protocol for merchants.

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.

Transferring funds to the accounts of other users

Request parameters:

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.

Request example for transferring funds to another user account

POST /api/request-payment HTTP/1.1
Host: yoomoney.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: yoomoney.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!

Transfer commission

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 account.

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.

Payment label

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.

Response

The method returns the following parameters:

Parameter	Type	Description
status	string	Operation result code. Possible values: `success` — success; `refused` — payment refused; the reason is explained in the `error` field. Final state.
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 YooMoney user account.
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.

When processing a payment, YooMoney 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”.

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:

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.

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.

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`.

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: `anonymous` — anonymous account; `named` — named account; `identified` — identified account.
recipient_account_type	Recipient’s account type. Possible values: `personal` — user account in YooMoney; `professional` — professional business account in YooMoney.

Successful payment response example

JSON
{
  "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
}

Error codes

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.
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 YooMoney 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; YooMoney 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.
account_closed	User’s account closed.
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.

Response example for refusal

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