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.
ParameterTypeDescription
pattern_idstringPayment Pattern ID. Corresponds to the merchant’s scid (payment form number).
*stringPayment Pattern parameters required by the merchant.
Transferring funds to the accounts of other users
Request parameters:
ParameterTypeDescription
pattern_idstringConstant value: p2p.
tostringID of the transfer recipient (account number, phone number, or email).
amountamountAmount to pay (how much the sender will pay).
amount_dueamountAmount to be received (credited to the receipient’s account after payment).
commentstringPayment comment, displayed in the sender’s history.
messagestringComments on the transfer (displayed to the recipient).
labelstringThe 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:
ParameterTypeDescription
status
string
Operation result code. Possible values:
  • success — success;
  • refused — payment refused; the reason is explained in the error field. Final state.
errorstringOperation processing error code (additional description for the status field). Present only for errors.
money_sourceobjectPayment methods available to the application, see Available payment methods. Present only on success.
request_idstringID of the payment request. Present only on success.
contract_amountamountThe 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_typestringRecipient’s account type. This parameter is present if the method was successfully executed when transferring funds to another YooMoney user account.
account_unblock_uristringThe address to send the user to in order to unblock an account. This field is present if the account_blocked error occurred.
ext_action_uristringThe 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”.
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:
AttributeTypeDescription
allowedbooleanFlag indicating whether this payment method is allowed by the user.
Attributes of the method of payment with a bank card:
AttributeTypeDescription
allowedbooleanFlag indicating whether this payment method is allowed by the user.
csc_requiredbooleanIndicates whether the CVV2/CVC2 code is required for authorizing payment using a bank card.
itemobjectDescription of the bank card linked to the account.
Parameters for the bank card description:
AttributeTypeDescription
idstringIdentifier 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_fragmentstringA 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
}
Transfer recipient data
When a transfer to another user account is requested, the request-payment method returns the following fields:
CodeDescription
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:
CodeDescription
illegal_paramsRequired payment parameters are either missing or have invalid values.
illegal_param_labelInvalid value for the label parameter.
illegal_param_toInvalid value for the to parameter.
illegal_param_amountInvalid value for the amount parameter.
illegal_param_amount_dueInvalid value for the amount_due parameter.
illegal_param_commentInvalid value for the comment parameter.
illegal_param_messageInvalid value for the message parameter.
not_enough_fundsThe 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_refusedThe merchant refused to accept the payment (for example, the user tried to purchase an item that is not in stock).
payee_not_foundThe 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_blockedThe 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_closedUser’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 valuesTechnical error; repeat the operation again later.
Response example for refusal
JSON
{
  "status": "refused",
  "error": "payment_refused",
  "error_description": "Subscriber does not exist"
}
See also
Process-payment method Access token scope