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:
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.
Main | Might be useful |
---|---|
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.
<!--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>
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 thefalse
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 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.
If necessary, set up payment refunds.
You can use this scenario if: you sell digital goods or services or if you provide them to the user immediately after the payment.
Main | Might be useful |
---|---|
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.
<!--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>
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 thefalse
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 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.
If necessary, set up payment refunds.
Extension for Physical products and Digital products scenarios. For those who want to make regular charges for subscriptions or implement other recurring payments.
Main | Might be useful |
---|---|
Digital products scenario Saving the payment method for autopayments: | Physical products scenario |
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.
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 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" }'
Obtain the ID of the saved payment method.
Set up regular autopayments via the saved payment method.
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.
Main | Might be useful |
---|---|
Physical products scenario Saving the payment method for autopayments: | Digital products scenario |
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.
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 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" }'
Obtain the ID of the saved payment method.
Set up autopayments for cases when users select one-click payment.
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.
Main | Might be useful |
---|---|
Physical products scenario | Digital products scenario |
- If authentication via 3D-Secure is disabled for your store, contact your YooMoney manager.
- Each user in your system must have a unique ID.
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 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" }'
Specify the user's ID in your system in the request for creating a payment
See also