YooMoney Checkout Widget: typical usage scenarios — Payment acceptance via the YooMoney API

Typical usage scenarios for the YooMoney Checkout Widget

This article includes several common integration scenarios via the YooMoney Checkout Widget.

Main scenarios:

Physical products for goods and services delivered after your confirmation
Digital products for goods and services provided immediately after payment

Extensions of the main scenarios:

Subscription for autopayments
One-click purchase
Purchase via saved bank card

Physical products

You can use this scenario if:

you sell physical goods with delivery and you want to charge users only after checking that the ordered products are in stock;
you provide services and you want to charge users only after checking the order or discussing it with the customer.

Useful articles

Main	Might be useful
Basics of working with the API Two-stage payments Widget integration Errors during widget initialization	Displaying widget in a pop-up window Configuring widget's color scheme Configuring text language Notifications Refunds One-click purchases Saving users' bank card details

Short memo

Preparation

Step 1. Prepare for integration: get the data for request authentication, enable the required payment methods, and get your website ready.

Step 2. Prepare the payment page: place the widget, set up the display of payment form, and if necessary, the widget's color scheme.

HTML
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

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

<script>
//Widget initialization. All parameters are required except for the customization object.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page

    //Widget configuration (if necessary)
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            //Accent color: Pay button, selected radio buttons, checkboxes, and text boxes
            control_primary: '#00BF96' //Color value in HEX
        }
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>

Accepting the payment

Step 1. Set up the procedure for creating a payment and receiving a token for widget initialization, specify these additional parameters in the request for creating a payment:

capture parameter with the false value to process the payment in two stages;
confirmation.locale parameter if you want to configure the language of the payment form's interface.

Example of a request for creating a payment

cURL
PHP
Python
curl https://api.yookassa.ru/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",
          "locale": "en_US"
        },
        "capture": false,
        "description": "Order No. 72"
      }'

Step 2. Set up widget initialization and the processing of errors.

Step 3. Set up the procedure of payment completion and the display of information to the user depending on the payment status.

Step 4. Set up the debiting and the cancellation of payment after the successful confirmation of payment by the user.

After the payment

If necessary, set up payment refunds.

Digital goods

You can use this scenario if: you sell digital goods or services or if you provide them to the user immediately after the payment.

Useful articles

Main	Might be useful
Basics of working with the API Widget integration Errors during widget initialization	Displaying widget in a pop-up window Configuring widget's color scheme Configuring copy language Notifications Refunds One-click purchases Saving users' bank card details

Short memo

Preparation

Step 1. Prepare for integration: get the data for request authentication, enable the required payment methods, and get your website ready.

Step 2. Prepare the payment page: place the widget, set up the display of payment form, and if necessary, the widget's color scheme.

HTML
<!--Library implementation-->
<script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>

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

<script>
//Widget initialization. All parameters are required except for the customization object.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'confirmation-token', //Token that must be obtained from YooMoney before the payment process
    return_url: 'https://merchant.site', //URL to the payment completion page

    //Widget configuration (if necessary)
    customization: {
        //Color scheme customization, minimum one parameter, color values in HEX
        colors: {
            //Accent color: Pay button, selected radio buttons, checkboxes, and text boxes
            control_primary: '#00BF96' //Color value in HEX
        }
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>

Accepting the payment

Step 1. Set up the procedure for creating a payment and receiving a token for widget initialization, specify these additional parameters in the request for creating a payment:

capture parameter with the false value to process the payment in two stages;
confirmation.locale parameter if you want to configure the language of the payment form's interface.

Example of a request for creating a payment

cURL
PHP
Python
curl https://api.yookassa.ru/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",
          "locale": "en_US"
        },
        "capture": false,
        "description": "Order No. 72"
      }'

Step 2. Set up widget initialization and the processing of errors.

Step 3. Set up the procedure of payment completion and the display of information to the user depending on the payment status.

After the payment

If necessary, set up payment refunds.

Subscription for autopayments

Extension for Physical products and Digital products scenarios. For those who want to make regular charges for subscriptions or implement other recurring payments.

Useful articles

Main	Might be useful
Digital products scenario Saving the payment method for autopayments: General information Unconditional saving of payment method Obtaining the ID of the saved payment method Processing an autopayment	Physical products scenario Payment without saving the payment method

Short memo

Preparation

Additional preparation for autopayments:

Tell your YooMoney manager that you're going to use autopayments.
Implement the procedure for user's consent to enable autopayments.

Accepting the first payment

When creating a payment, specify the save_payment_method parameter with the true value in the request to process a payment with saving the payment method. Other parameters depend on your scenario..

Example of a request for creating a payment

cURL
PHP
Python
curl https://api.yookassa.ru/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",
          "locale": "ru_RU"
        },
        "capture": true,
        "save_payment_method": true,
        "description": "Order No. 72"
      }'

After the first payment

Obtain the ID of the saved payment method.

Accepting further payments

Set up regular autopayments via the saved payment method.

One-click purchases

Extension for Physical products and Digital products scenarios.

You can use this scenario if:

you want to give users the option to pay for purchases immediately in one click;
you're going to implement the form for choosing the payment method independently.

If you want to use a ready-made form for choosing the payment method ad save only the bank card, use purchase via saved bank card.

Useful articles

Main	Might be useful
Physical products scenario Saving the payment method for autopayments: General information Conditional saving of payment method Obtaining the ID of the saved payment method Processing an autopayment	Digital products scenario Payment without saving the payment method Purchase via saved bank card

Short memo

Preparation

Additional preparation for autopayments:

Tell your YooMoney manager that you're going to use autopayments.
Implement the procedure for user's consent to enable autopayments.

Accepting the first payment

When creating a payment, do not specify the save_payment_method parameter in the request. Other parameters depend on your scenario.

Example of a request for creating a payment

cURL
PHP
Python
curl https://api.yookassa.ru/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",
          "locale": "ru_RU"
        },
        "capture": true,
        "description": "Order No. 72"
      }'

After the first payment

Obtain the ID of the saved payment method.

Accepting further payments

Set up autopayments for cases when users select one-click payment.

Purchase via saved bank card

Extension for Physical products and Digital products scenarios.

You can use this scenario if:

you want to save the user's bank card and display it during recurring payments;
you're going to use a ready-made form for choosing the payment method.

If you want to implement the form for choosing the payment method and save the YooMoney wallet or bank card independently, use one-click purchase.

Useful articles

Main	Might be useful
Physical products scenario Saving the user's bank card details	Digital products scenario Subscription to autopayments One-click purchases

Short memo

Preparation

If authentication via 3D-Secure is disabled for your store, contact your YooMoney manager.
Each user in your system must have a unique ID.

Accepting the first payment

Specify merchant_customer_id with the user's ID in your system in the request for creating a payment. Specify other parameters depending on your scenario.

Example of a request for creating a payment

cURL
PHP
Python
curl https://api.yookassa.ru/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",
        "merchant_customer_id": "79999999999"
      }'

Accepting further payments

Specify the user's ID in your system in the request for creating a payment