YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Configuring how payment methods are displayed
By default, the payment form displays all the payment methods available to the store and in the widget. The selection screen design and the order in which the payment methods are displayed is determined by the widget. When a user proceeds to checkout, they select the method and confirm the payment.
If the default ready-made selection screen doesn’t suit you, you can disable it and specify the payment method, for which you'd like to display the payment form to users. This mode is suitable for those who want to implement a custom selection screen or use only one payment method.
 
Using a payment form only for one method
To display the form for payments via a certain method, specify the customization object with the payment_methods array when initializing the widget. The value that you need to specify in the payment_methods array depends on the payment method you'd like to use:
  • Bank card
  • YooMoney
  • Mir Pay
  • SberPay
  • Tinkoff Pay
  • FPS (Faster Payments System)
  • Combinations of payment methods
Bank card
To display the form for payments via bank cards, specify the bank_card value in payment_methods. The minimum width of the container for displaying the payment form is 288 pixels.
Payments via one method: bank card
If a payment via bank card doesn't go through, the widget displays an error message to the user and prompts them to try again. If you’d like to set up a custom interaction with the user after each unsuccessful payment attempt, contact your YooMoney manager.
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Code that must be executed after the payment form is displayed.
        payment_methods: ['bank_card']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
YooMoney
To display the form for payments via YooMoney wallets, linked cards, or in bonus points, specify the yoo_money value in payment_methods. The minimum width of the container for displaying the payment form is 288 pixels.
Payments via one method: YooMoney
If a payment via a YooMoney wallet or linked card doesn't go through, the widget displays an error message to the user and prompts them to try again. If you’d like to set up a custom interaction with the user after each unsuccessful payment attempt, contact your YooMoney manager.
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Selection of payment method for display
        payment_methods: ['yoo_money']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
Mir Pay
To display the button for payments via Mir Pay, specify the mir_pay value in payment_methods. The minimum width of the container for displaying the payment form is 288 pixels. The color scheme of the button can't be changed: it's background can only be white.
Payments via one method on mobile devices: Mir Pay
The button is displayed for payments on mobile devices on Android. If the button can't be displayed, you'll get the no_payment_methods_to_display error.
If you display the Mir Pay button, you need to have a custom scenario of interaction with the user for each payment attempt. If the payment resulted in a failure, find out the reasons behind the cancellation and inform the user. In order for the widget to process unsuccessful attempts on its own, you need to display all the payment methods or the combination of the bank card and Mir Pay methods.
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Selection of payment method for display
        payment_methods: ['mir_pay']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
SberPay
To display the form for payments via SberPay, specify the sberbank value in payment_methods. The minimum width of the container for displaying the payment form is 288 pixels.
There are differences in the payment process for SberPay between PC and mobile. On PC, a QR code is generated, and it should be scanned in the SberBank app on a phone.
Payments via one method on PC: SberPay
On mobile, the widget opens the SberBank app. If the app can't be opened, the Go to the app button is displayed:
Payments via one method on mobile devices: SberPay
If a payment via SberPay doesn't go through, the widget displays an error message to the user and prompts them to try again. If you’d like to set up a custom interaction with the user after each unsuccessful payment attempt, contact your YooMoney manager.
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Selection of payment method for display
        payment_methods: ['sberbank']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
Tinkoff Pay
To display the form for payments via Tinkoff Pay, specify the tinkoff_bank value in payment_methods. The minimum width of the container for displaying the payment form is 288 pixels.
There are differences in the payment process for Tinkoff Pay between PC and mobile. On PC, a QR code is generated, and it should be scanned with a phone:
Payments via one method on PC: Tinkoff Pay
The Go to the app button is displayed for payments on mobile devices:
Payments via one method on mobile devices: Tinkoff Pay
If a payment via Tinkoff Pay doesn't go through, the widget displays an error message to the user and prompts them to try again. If you’d like to set up a custom interaction with the user after each unsuccessful payment attempt, contact your YooMoney manager.
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Selection of payment method for display
        payment_methods: ['tinkoff_bank']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
FPS (Faster Payments System)
To display the form for payments via FPS, specify the sbp value in payment_methods. The minimum width of the container for displaying the payment form is 288 pixels.
There are differences in the payment process for FPS between PC and mobile. On PC, a QR code is generated, and it should be scanned with a phone:
Payments via one method on PC: FPS
The list of banks and payment services is displayed for payments on mobile devices:
Payments via one method on mobile devices: FPS
If a payment via the Faster Payments System doesn't go through, the widget displays an error message to the user and prompts them to try again. If you’d like to set up a custom interaction with the user after each unsuccessful payment attempt, contact your YooMoney manager.
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Selection of payment method for display
        payment_methods: ['sbp']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

//Display of payment form in the container
checkout.render('payment-form');
</script>
Combinations of payment methods
Only one combination of payment methods is available: bank card and Mir Pay. If a payment is made on mobile device on Android, the Mir Pay button will be displayed above the bank card.
To use a combination of payment methods, specify their codes separated by a comma. The minimum width of the container for displaying the payment form is 288 pixels. The color scheme of the button can't be changed: it's background can only be white.
Combination of payment methods on desktop: only bank card is displayed
Combination of payment methods on mobile devices: bank card and Mir Pay
JavaScript
<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://example.com', //URL to the payment completion page

    //Widget customization
    customization: {
        //Selection of payment method for display
        payment_methods: ['bank_card', 'mir_pay']
    },
    error_callback: function(error) {
        //Processing of initialization errors
    }
});

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