Payments from bank cards without authorization

General information

The API is intended for:
  • Payment of goods and services using any bank card without user authorization in Yandex.Money.
  • Saving information about bank cards for repeated payments without entering the complete card data.
  • Usage on users' personal devices and embedding in various mobile apps.
The API allows you to:
  • Pay for goods and services in stores that are connected to Yandex.Money.
  • Deposit funds to users' Yandex.Money accounts.
  • Save information about one or more bank cards and use it for subsequent payments.
To get started:
  1. Register your application and get a client_id (application identifier).
  2. Activate Yandex.Checkout (for businesses or individual entrepeneurs) or create a Wallet in Yandex.Money (for individuals).

Usage scenarios

Registering an instance of the application

Before making the first payment, you need to register a copy of the application in Yandex.Money that is installed on a device and get an identifier for the instance of the application — instance_id. To register an instance, call the instance-id method.

What you should know about the identifier:
  • It is only received once.
  • It is remembered in a secure location on the device (storing it on an SD card is not allowed; you should use KeyChain or SharedPreferences).
  • It is passed as a parameter for all other functions.
  • It is deleted from the device when the application is deleted.

General payment scenario

  1. Payments are processed based on the Payment Pattern with user parameters specified. Each merchant has its own set of these parameters, so the application must show the user a form requesting the information that is needed by a specific store. For example: the payment amount, phone number, contract number, and so on.
  2. The application sends a payment request request-external-payment, which contains the Payment Pattern ID and the parameters entered by the user. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id).
  3. If the user confirmed the payment, the application sends a request to make the payment (process-external-payment) that specifies the payment context ID (request_id).
Note that the application may need a repeat call of the process-external-payment method. This method should be called until the payment process is complete. This may require additional user steps in WebView. Repeated calls are necessary if:
  • The bank card data must be entered on the Yandex.Money page in WebView.
  • The user must go to the issuing bank's page to confirm the transaction over 3-D Secure.
  • Payment processing is not yet complete.
  • The internet connection was lost during the payment process.
Rules for payment processing:
  1. Money is debited from the bank card when the process-external-payment method is called.
  2. If the process-external-payment call is repeated, the method returns the state of the previous payment.
  3. If the internet connection is lost, the server times out, or other network errors occur, the application should repeat the call with the same parameters.

First payment

  1. The application sends a payment request (request-external-payment), which contains the Payment Pattern ID and the user parameters. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id).
  2. The application sends a request to make the payment (process-external-payment) that specifies the payment context ID (request_id). The Yandex.Money server responds with a request to open WebView at the link (status=ext_auth_required, acs_uri, acs_params).
  3. The application opens WebView and goes to the acs_uri address. Next:
    1. The user enters the bank card data on the Yandex.Money page.
    2. If necessary, the user authenticates using 3-D Secure technology on the issuing bank's page.
    3. The user returns to ext_auth_success_uri (if the bank card data was accepted for processing), or ext_auth_fail_uri (if the card data was refused by the payment gateway).
  4. The application repeats process-external-payment calls until it gets the final payment status (success/refused).
  5. The application shows the user the payment result and asks permission to save the bank card data.
  6. If the user agrees to save the card data, the application re-sends the process-external-payment request with the request_token=true parameter. Next:
    1. The Yandex.Money server returns the bank card data and a token for repeated payments.
    2. The application saves the bank card data and the token for repeated payments in a secure location on the device.
Bank card data and token for repeated payments:
  • Are remembered in a secure location on the device (storing it on an SD card is not allowed; KeyChain and SharedPreferences are allowed).
  • Are deleted from the device when the application is deleted.

Payment with saved bank card data

This type of payment may require authentication using 3-D Secure technology, depending on the issuing bank's policy and information about the user's device or a specific transaction.

Payment using saved bank card data without 3-D Secure authentication:
  1. The application sends a payment request (request-external-payment), which contains the Payment Pattern ID and the user parameters. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id).
  2. The application repeats payment requests (process-external-payment), specifying the payment context identifier (request_id), the token for repeated payments and the bank card's CVV2/CVC2 code until it gets the final payment status.
Payment using saved bank card data with 3-D Secure authentication:
  1. The application sends a payment request (request-external-payment), which contains the Payment Pattern ID and the user parameters. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id).
  2. The application sends a payment requests (process-external-payment), specifying the payment context identifier (request_id), the token for repeated payments and the bank card's CVV2/CVC2 code. The Yandex.Money server responds with a request to open WebView at the link (status=ext_auth_required, acs_uri, acs_params).
  3. The application opens WebView and goes to the acs_uri address. Next:
    1. The user authenticates using 3-D Secure technology on the issuing bank's page.
    2. The user returns to ext_auth_success_uri (if the transaction was accepted for processing) or ext_auth_fail_uri (if the transaction was refused).
  4. The application repeats process-external-payment calls until it gets the final payment status (success/refused).

List of methods