Old versions of the API
Help
Sign up for YooMoney
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:
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
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
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
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
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
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
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
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
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
Short memo
Preparation
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
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
See also
Integration scenarios