Yandex.Checkout Widget
Using the Yandex.Checkout widget, you can embed a ready-made payment form on your website. The user can pay via several payment methods, such as Yandex.Money wallet and bank cards linked to it, arbitrary bank card, Apple Pay, Google Pay, and Sberbank Online. The widget allows users to save bank cards and Yandex.Money wallets for recurring payments in your store.
Yandex.Checkout widget’s payment form
The payment form automatically adjusts to the size of the user’s device, checks the entered data and alerts the user if something is entered incorrectly.
To process a payment via the widget, just create a payment using the Yandex.Checkout API, initialize the widget, and display the form on the payment page.
Integration:
  1. Read about the payment processing scenario in the widget.
  2. Set up payment methods.
  3. Prepare the payment page.
  4. Implement payment processing.
  5. Implement recurring payments if necessary.
  6. Set up the processing of widget initialization errors.
 Payment processing scenario
  1. User proceeds to payment.
  2. You send a request for creating a payment to Yandex.Checkout.
  3. Yandex.Checkout returns the created payment object with a token for initializing the widget.
  4. You initialize the widget and display the form on the payment page.
  5. User selects a payment method, enters their details.
  6. Widget redirects the user to the payment confirmation page (for example, for 3-D Secure authentication) if required.
  7. User confirms the payment.
  8. The widget redirects the user to the payment completion page on your side.
  9. You display the relevant information depending on the payment status.
Done!
 Payment method configuration
The widget supports the following payment methods:
  • Yandex.Money wallet and bank cards linked to it,
  • arbitrary bank cards,
  • Apple Pay,
  • Google Pay,
  • Sberbank Online.
Only authorized users can pay with the Yandex.Money wallet and bank cards linked to it.
 General configuration
By default, the only payment methods are Yandex.Money wallets and linked cards. Contact the Yandex.Checkout manager to find out other payment methods available to you.
If you want the widget to support payments via Google Pay and Apple Pay, your website must use HTTPS and a valid TLS/SSL certificate (minimum version is TLS v1.2). To enable Apple Pay, you’ll need perform additional configuration.
 Apple Pay configuration
Step 1. Provide your Yandex.Checkout manager with the URL of the website where you’re going to embed the widget.
Step 2. Download the merchant.ru.yandex.kassa file and upload it to your website at:
https://<your website URL>/.well-known/apple-developer-merchantid-domain-association
This is the only acceptable path to the file, including the period and hyphens. A period in the URL indicates a hidden folder.
Step 3. To ensure that payment using Apple Pay is always available via the widget, renew the TLS/SSL certificate no later than 8 days before its expiration date.
 Payment page
To accept payments, prepare a payment page by connecting the library and embedding the widget.
Step 1. Enable the script from CDN. The library will be available in the global scope under
YandexCheckout
.
Step 2. Add the HTML element that will be used as a container of the payment form. Set the
id
attribute for this element.
Step 3. To initialize the widget, create a new
YandexCheckout
class instance with
confirmation_token
that you need to obtain from Yandex.Checkout before payment,
return_url
for sending the user after the payment, and
error_callback
as the error handler function that will be called with the error code.
confirmation_token
must be obtained from Yandex.Checkout for every payment.
Step 4. To display the payment form, call the
render
method. Use the value of container’s
id
attribute as the argument.
HTML
<!--Library implementation-->
<script src="https://kassa.yandex.ru/checkout-ui/v2.js"></script>

<!--HTML element in which the payment form will be displayed-->
<div id="payment-form"></div>

<script>
//Widget initialization. All parameters are required.
const checkout = new window.YandexCheckout({
    confirmation_token: 'confirmation-token', //Token that must be obtained from Yandex.Checkout before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page
    error_callback(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
 Payment process
To process a payment:
  1. Create a payment in Yandex.Checkout
  2. Initialize the widget
  3. Complete the payment
If you want to test the widget, create a payment for your demo store and pay with one of the test cards. More about payment testing
 Step 1. Create a payment
To create a payment, send a request to Yandex.Checkout, include the data for request authentication, the idempotency key, the
amount
object containing the payment amount, the
confirmation
object with the
embedded
type, and if necessary the
description
parameter with a description of the transaction that will be displayed to the user during the payment process. Also include the
capture
parameter with the
true
value. This means you will receive the money immediately after the payment (if the value is 
false
, the required amount will be held on the user’s account, and you’ll be able to capture it whenever convenient).
You can set any other parameters in the request, except for
payment_method_data
,
payment_method_id
,
payment_token
,
airline
.
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "embedded"
        },
        "capture": true,
        "description": "Order No. 72"
      }'
 Step 2. Initialize the widget
Yandex.Checkout will return
confirmation_token
in the payment object .
JSON
{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-24301ae5-000f-5000-9000-13f5f1c2f8e0"
  },
  "created_at": "2018-07-10T14:25:27.535Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Use this token for
YandexCheckout
class instantiation and widget initialization.
The token is for single-use only. If not used, the token will expire after 1 hour. If the user does not pay within an hour, the widget will not be initialized, and you will need to request the token again. If the user pays and returns to the form, it will be displayed with an error.
To request the token again, create another payment and initialize the widget using the new token.
 Step 3. Complete the payment
When the user enters the payment details and confirms the payment, Yandex.Checkout will redirect them to 
return_url
which you specify during widget initialization. You will need to check the payment results (success or failure) independently and display the necessary information to the user.
You can check the payment status in a notification sent by Yandex.Checkout, or you can send periodic requests for payment information .
 Saving payment methods for recurring payments
Using the Yandex.Checkout widget, you can save payment methods and use them for recurring payments, for example, as a monthly charge for a subscription.
Recurring payments are only enabled by default in the demo store. If you want to enable them in your real store, contact the Yandex.Checkout manager.
If you’re allowed to use autopayments, you can process payments:
 Payment with the payment method saved
By saving the payment method, you can save a bank card or Yandex.Money wallet in your store. Using the widget, you can process payments and save the payment method unconditionally or conditionally.
Payment method is saved unconditionally when the method is saved by default and the user can’t affect this. The process is as follows:
  1. On your website, you place the warning for the user alerting them that you will save their payment details and explaining how you will use it (for example, the frequency and amounts of your future debits) and how the user can disable recurring charges in your store. On your side, you receive the user’s consent to make autopayments.
  2. The widget displays only two payment methods to the user: with an arbitrary bank card or from a Yandex.Money wallet (if the user is logged in to their Yandex account). After the user selects the payment method, the widget will inform them that the payment method will be in to your store. Upon successful payment, the bank card or wallet details will be automatically saved in Yandex.Checkout.
Example of usage: subscription for regular payments.
Payment with the payment method saved unconditionally
Payment method is saved conditionally when the method is saved by the user’s request. The process is as follows:
  1. On your website, you let the user know that they can save their payment details and explain how you will use it and how the user can disable the option.
  2. The widget displays all available payment methods to the user. If the user selects payment with an arbitrary bank card or Yandex.Money wallet, the widget will offer them to save payment details in your store. If the user agrees and the payment is processed successfully, the payment method information will be saved in Yandex.Checkout, and you will be able to use the saved payment method’s ID for recurring payments. If the user refuses, the information will not be saved in the store after the payment.
Example of usage: saving a means of payment in the store to speed up the payment process for subsequent payments.
Payment with the payment method saved conditionally
 Payment with the payment method saved unconditionally
Step 1. Create a payment and specify
save_payment_method
parameter with the
true
value.
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "embedded"
        },
        "capture": true,
        "save_payment_method": true,
        "description": "Order No. 72"
      }'
Step 2. Yandex.Checkout will respond with
confirmation_token
, the token for initializing the widget.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Step 4. Process the payment in the usual manner.
If the payment is processed successfully, you will receive the saved payment method’s ID.
 Payment with the payment method saved conditionally
Step 1. Create a payment (no need to include
save_payment_method
).
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "embedded"
        },
        "capture": true,
        "description": "Order No. 72"
      }'
Step 2. Yandex.Checkout will respond with
confirmation_token
, the token for initializing the widget.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-2557c659-000f-5000-9000-12714806d854"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Step 4. Process the payment in the usual manner.
If the payment is processed successfully, you will receive the saved payment method’s ID.
 Getting the saved payment method’s ID
Step 1. Wait until the user confirms the payment, and its status changes to 
succeeded
(or 
waiting_for_capture
if it’s a two-stage payment). You can check the payment status in a notification sent by Yandex.Checkout, or you can send periodic requests for payment information .
Step 2. Make sure the payment method is saved: the
payment_method.saved
value in the payment object has changed to 
true
.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "captured_at": "2018-07-18T17:20:50.825Z",
  "created_at": "2018-07-18T17:18:39.345Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "25564507-000f-5000-9000-19878c91d156",
    "saved": true,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "test": false
}
Step 3. Save the
payment_method.id
. You’ll need to use it as the identifier of the saved payment method for subsequent payments.
Done!
Now you can make recurring payments. You’ll need to implement payments with a saved payment method independently.
 Payments without saving the payment method
You can process payments without saving the payment method. The user can pay via any available payment methods. The method won’t be saved.
To process a payment without saving the payment method:
Step 1. Create a payment and specify the
save_payment_method
parameter with the
false
value.
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "embedded"
        },
        "capture": true,
        "save_payment_method": false,
        "description": "Order No. 72"
      }'
Step 2. Yandex.Checkout will respond with
confirmation_token
, the token for initializing the widget.
JSON
{
  "id": "25564507-000f-5000-9000-19878c91d156",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "embedded",
    "confirmation_token": "ct-25564507-000f-5000-9000-19878c91d156"
  },
  "created_at": "2019-11-07T14:59:19.351Z",
  "description": "Order No. 72",
  "metadata": {},
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}
Step 4. Process the payment in the usual manner.
 Widget initialization errors
If the widget initialization failed, Yandex.Checkout will send an error code to the callback function.
Error codeValue
token_required
Token not sent. Send
confirmation_token
during widget initialization.
invalid_token
Invalid token. Create a payment to obtain a token.
token_expired
Token has expired. Create a payment to obtain a new token.
return_url_required
Return URL not specified. Specify
return_url
during widget initialization.
internal_service_error
Error during payment creation. Repeat widget initialization.
 See also
Quick startPayment processNotificationsRecurring payments