process-payment method

Description

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

Input parameters

Parameter Type Description
request_id string Payment request ID assigned by Yandex.Money, 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.

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 string 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 authorization_reject
Tip.

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

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.
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 Yandex.Money. 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 Yandex.Money user.
payee string Account number of the user receiving the payment. Present when funds were successfully transferred to the account of another Yandex.Money user.
credit_amount amount The amount credited to the payee's account. Present when funds were successfully transferred to the account of another Yandex.Money 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.
hold_for_pickup_link string A link to the deferred transfer when sending it via Yandex.Mail. The field is present if the value is known.
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.

Operation processing result codes:

Code Description
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.
Tip.

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

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.
  • Yandex.Money 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 Yandex.Money 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 “Yandex.Money” 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.
Important.

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, Yandex.Money 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).

CAUTION. 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.
Tip.
Conditions for processing a payment using a linked bank card:
  • The user's Yandex.Money 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.

3-D Secure authentication of payment using a linked bank card

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:

  • request-payment is called with payment parameters
  • process-payment is called with money-source=card, csc code, ext_auth_success_uri, and ext_auth_fail_uri
  • process-payment returns status=ext_auth_required, acs_uri, and acs_params
  • 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")
  • 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
  • the application should repeat the process-payment call, specifying only a single parameter, request_id
  • 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:


"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"
    }
  ]
}
    

Examples

Request example for payment from a user's account:

POST /api/process-payment HTTP/1.1
Host: money.yandex.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: money.yandex.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123 
Content-Type: application/x-www-form-urlencoded
Content-Length: 44 

request_id=1234567&money_source=card&csc=123

Response example if payment authorization was not completed:

{ 
"status": "in_progress" 
} 

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

POST /api/process-payment HTTP/1.1
Host: money.yandex.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

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: money.yandex.ru
Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
Content-Type: application/x-www-form-urlencoded
Content-Length: 18

request_id=1234567

Response example for successful authorization of the payment:

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

Response example for refusal:

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

Response example if payment authorization was not completed:

{"status": "in_progress"}

Response example when 3-D Secure authentication is required.

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