process-payment method — YooMoney wallet API

Process-payment method

Confirms a payment that was created using the request-payment method. Specifies the method for making the payment.

Request

Parameter	Type	Description
request_id	string	Payment request ID assigned by YooMoney, copied from the request-payment response.
money_source	string	The requested method for making a payment: `wallet` — using funds on the user’s account ID linked to the card’s account (value of the `id` field in the bank card description) Default: `wallet`
csc	string	Card Security Code, the CVV2/CVC2 code of the user’s linked bank card. This parameter should be set only if payment is being made using a linked bank card.
ext_auth_success_uri	string	Address of the page to return to when card payment has been successfully authenticated using 3‑D Secure technology. Shown if the application supports 3‑D Secure authentication. Required parameter for this type of authentication.
ext_auth_fail_uri	string	Address of the page to return to when card payment has failed authentication using 3‑D Secure technology. Shown if the application supports 3‑D Secure authentication. Required parameter for this type of authentication.

Request example for payment from a user’s account

POST /api/process-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 18

request_id=1234567

Request example for payment with the user’s linked bank card

POST /api/process-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 44

request_id=1234567&money_source=card&csc=123

Response

The method returns the following parameters:

Parameter	Type	Description
status	string	Operation result code. Possible values: `success` — success (payment processed). Final state. `refused` — payment processing was refused. The reason for refusal is returned in the `error` field. Final state. `in_progress` — payment authorization was not completed. The application should repeat the request with the same parameters later. `ext_auth_required` — in order to complete authorization of payment by card, additional authentication using 3‑D Secure technology is required. all other values — the payment status is unknown. The application should repeat the request with the same parameters later.
error	string	Operation processing error code (additional description for the `status` field). Present only for errors.
payment_id	string	Processed payment ID. Present only on success. This parameter corresponds to the `operation_id` parameter in operation-history and operation-details for the payer’s history.
balance	amount	Balance left on the user account after processing the payment. Present only if the following conditions are met: the method was executed successfully; the access token has the `account-info` permission.
invoice_id	string	The merchant’s transaction number in YooMoney. Present when payment to the merchant has been completed successfully.
payer	string	Payer’s account number. Present when funds were successfully transferred to the account of another YooMoney user.
payee	string	Account number of the user receiving the payment. Present when funds were successfully transferred to the account of another YooMoney user.
credit_amount	amount	The amount credited to the payee’s account. Present when funds were successfully transferred to the account of another YooMoney user.
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.
acs_uri	string	Address of the 3‑D Secure bank card authentication page on the issuing bank’s side. This field is present if 3‑D Secure authentication is required in order to complete a transaction using a bank card.
acs_params	object	Authentication parameters for 3‑D Secure technology in the form of a “name-value” collection. This field is present if 3‑D Secure authentication is required in order to complete a transaction using a bank card.
next_retry	long	Recommended time interval to wait before repeating a request, in milliseconds. This field is present when `status=in_progress`
digital_goods	object	Data about a digital product (PIN codes and bonuses for games, iTunes, XBox, etc). This field is present for a successful payment to merchants of digital goods.

The method response may return other internal fields that do not need to be processed.

Response example for successful authorization of the payment

JSON
{
  "status": "success",
  "payment_id": "2ABCDE123456789",
  "balance": 1000.00
}

Error codes

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

Code	Description
contract_not_found	There is no existing unconfirmed payment with the specified `request_id`.
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.
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.
money_source_not_available	The requested payment method (`money_source`) is not available for this payment.
illegal_param_csc	The `csc` parameter has a missing or invalid value.
payment_refused	The payment was refused. Possible reasons: the merchant refused to accept the payment (`checkOrder` request); the transfer to a YooMoney user is not possible (for example, the recipient’s wallet has reached the maximum amount allowed).
authorization_reject	Authorization of the payment was refused. Possible reasons: the bank card expired; the issuing bank refused to perform the transaction for the card; exceeds the limit for this user; a transaction with the current parameters is forbidden for this user; the user did not accept the User Agreement for the YooMoney service.
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.
illegal_param_ext_auth_success_uri	The `ext_auth_success_uri` parameter has a missing or invalid value.
illegal_param_ext_auth_fail_uri	The `ext_auth_fail_uri` parameter has a missing or invalid value.
all other values	Authorization of the payment was refused. The application should make a new payment request later.

Response example for refusal

JSON
{
  "status": "refused",
  "error": "not_enough_funds"
}

Payments via linked bank cards

Conditions for processing a payment using a linked bank card:

the user’s YooMoney account has a bank card linked to it;
the user granted permission for the application to use this bank card for payments;
the payment is being made to a merchant;
the merchant is able to accept payments using bank cards.

The time required for processing a payment using a linked bank card (money_source=card) depends on how long it takes the card’s issuing bank to handle the transaction. In addition, YooMoney may connect to the merchant’s server, and the response time likewise affects the total time for authorizing the payment.

If payment authorization continues for more than 1 minute, the process-payment method returns the results code of the in_progress operation. The application should repeat the process-payment method call with the same parameters once a minute until the final response is received (status should have either the success or refused value).

Response example if payment authorization was not completed

JSON
{
  "status": "in_progress"
}

If no response was received, the payment status is unknown. It is just as likely that the payment was accepted as that it was refused. To determine the payment status, repeat the process-payment call with the same parameters.

If payment is made using a bank card, additional buyer verification may be required using 3‑D Secure technology.

Payment scenario with 3‑D Secure authentication

Step 1. request-payment is called with payment parameters.

Step 2. process-payment is called with money_source=card, csc code, ext_auth_success_uri, and ext_auth_fail_uri.

Request example for payment with a bank card by an application that supports 3‑D Secure

POST /api/process-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 164

request_id=1234567&money-source=card&csc=123&ext_auth_success_uri=http%3A%2F%2Fclient.example.com%2Fsuccess&ext_auth_fail_uri=http%3A%2F%2Fclient.example.com%2Ffail

Step 3. process-payment returns status=ext_auth_required, acs_uri, and acs_params.

Response example when 3‑D Secure authentication is required

JSON
{
  "status": "ext_auth_required",
  "acs_uri": "https://acs.alfabank.ru/acs/PAReq",
  "acs_params": {
    "MD": "723613-7431F11492F4F2D0",
    "PaReq": "eJxVUl1T2zAQ/CsZv8f6tCR7LmLSGiidJjAldMpTR7XVxAN2gmynSX59JeNAebu9O93u7QkuDvXzZG9dW22bWURiHE1sU2zLqlnPoofV1VRFFxpWG2dtfm+L3lkNC9u2Zm0nVTmLVvn9r7v5d/uS/UkYt4b8tjibUiGVxazICMeSSkmtwBmlhYw="
  }
}

Step 4. The application should open the browser and make a POST request to the acs_uri address with acs_params parameters as application/x-www-form-urlencoded (the same as “HTML form submit”)

Step 5. The client is authenticated using the issuing bank’s process, then sent by HTTP 302 Redirect to either ext_auth_success_uri or ext_auth_fail_uri, depending on the result

Step 6. The application should repeat the process-payment call, specifying only a single parameter, request_id.

Request example when repeating the request for payment with a bank card by an application after passing 3‑D Secure authentication

POST /api/process-payment HTTP/1.1
Host: yoomoney.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 18

request_id=1234567

Step 7. process-payment returns status=success or refused.

Data about digital goods

For a successful payment to a merchant of digital goods, the response contains the digital_goods field, which has a list of goods and a list of bonuses.

Data about a digital product or bonus:

Parameter	Type	Description
merchantArticleId	string	Product identifier in the seller’s system. Present only for products.
serial	string	Serial number of the product (the open part of the PIN code, activation code, or login).
secret	string	Secret for the digital product (the closed part of the PIN code, activation code, password, or download link).

Example of digital goods

JSON
"digital_goods": {
  "article": [
    {
      "merchantArticleId": "1234567",
      "serial": "EAV-0087182017",
      "secret": "87actmdbsv"
    },
    {
      "merchantArticleId": "1234567",
      "serial": "2000012",
      "secret": "gjhkgjsuurtrghxchfhjkrwetuertrehtthh"
    },
    {
      "merchantArticleId": "1234567",
      "serial": "2000013",
      "secret": "77788sfs7fd89g89dfg77778dfgdjkert789"
    }
  ],
  "bonus": [
    {
      "serial": "XXXX-XX-XX",
      "secret": "0000-1111-2222-3333-4444"
    }
  ]
}