YooMoney Checkout Widget: quick start — Payment acceptance via the YooMoney API

Quick start for YooMoney Checkout Widget

Using this article, you cam process the first payment via the YooMoney Checkout Widget.

This article describes the easiest integration scenario. You can find more detailed instructions in the Integration section.

Payment process

User goes to the payment page.
You initialize the widget on the payment page and display the payment form.
User selects the payment method, enters the details, and confirms the payment.
YooMoney redirects the user to your page after the payment is complete.
You display the information to the user depending on the payment status.

Done!

Preparation for payment processing

You will need the tools for interacting with YooMoney via API and two pages for payment processing.

Preparation for interaction via API

During the payment process, you will have to interact with YooMoney via API. Prepare the tools for testing requests to API that are convenient for you.

To authenticate requests, you will need ID and secret key of your store in YooMoney.

We recommend making this payment to the YooMoney demo store. The payment process via the demo store is identical to the real one except the money is not transferred anywhere. If you don't have a demo store yet, create and configure it in the Merchant Profile and get its ID and secret key. Learn more about test mode

If you'd like to try out the features of the API but you don't have a YooMoney Merchant Profile, sign up using this link. It's the simplest way to get a demo store. You don't need to enter the information about your company or enter into a contract.

Pages for payment processing

To process a payment, you will need to prepare the payment page and the payment completion page.

The payment page is a page on your website where you will display the payment form and the user will enter their payment details. You will need to embed the widget on this page. To make this payment, create a test page: copy the code below and save as an .HTML format file.

The payment completion page is a page on your website that the user will be redirected to by the widget after the payment in case of success and in case of failure. URL of this page must be specified in the return_url parameter of the script for widget initialization on the payment page. You can use any page, for example, the main page of your website.

Code of the test payment page

HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Прием платежа с помощью виджета ЮKassa</title>

  <!--Connecting the library for initializing the YooMoney Checkout Widget-->
  <script src="https://yookassa.ru/checkout-widget/v1/checkout-widget.js"></script>
 </head>
 <body>
  The payment form will be displayed below. If you haven't created the payment and sent the token for widget initialization yet, you will see an error message.

  <!--Контейнер, в котором будет отображаться платежная форма-->
  <div id="payment-form"></div>

  Bank card details for payment in the &amp;#38;lt;b&amp;#38;gt;demo store;#38;lt;/b&amp;#38;gt;:

   - card number — <b>5555 5555 5555 4477</b>
   - expiration date — <b>01/30</b> (or any other date greater than the current one)
   - CVC — <b>123</b> (or any other three digits)
   - code for 3-D Secure authentication — <b>123</b> (or any other three digits)

  <a href=https://yookassa.ru/developers/payment-acceptance/testing-and-going-live/testing#test-bank-card>Other test bank cards</a>

  <script>
  //Widget initialization. All parameters are required.
  const checkout = new window.YooMoneyCheckoutWidget({
      confirmation_token: 'ct-287e0c37-000f-5000-8000-16961d35b0fd', //Token that must be obtained from YooMoney before the payment process
      return_url: 'https://example.com/', //URL to the payment completion page, it could be any page on your website

      //If necessary, you can customize the widget's colors, see detailed instructions in the documentation
       //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

            //Color of the payment form and its elements
            //background: '#F2F3F5' //Color value in HEX
        //}
      //},
      error_callback: function(error) {
          console.log(error)
      }
  });

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

How to make a test payment

Step 1. Create a payment

To create a payment, send a request to YooMoney containing data for authenticating the request for demo store, idempotence key, amount and description of the payment, as well as the confirmation object with the embedded type (meaning you use the YooMoney Checkout Widget to accept payments). Also specify the capture parameter with the true value, so you'll 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 debit it whenever it will be convenient for you).

When you're making a payment to the demo store, crediting and debiting of money is only simulated.

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"
      }'

YooMoney will return confirmation_token in the payment object. You will need the value of this parameter to initialize the widget.

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": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": true
}

Step 2. Initialize the widget and display the payment form

Open the payment page code, paste the confirmation_token value that you received from YooMoney in the previous step in the script for initializing the widget. Save the changes and open the page in the browser, and the widget's payment form will be displayed.

HTML
//Example of a script with a specified token.
<script>
//Widget initialization. All parameters are required.
const checkout = new window.YooMoneyCheckoutWidget({
    confirmation_token: 'ct-24301ae5-000f-5000-9000-13f5f1c2f8e0', //Token you received after creating the payment
    return_url: 'https://yookassa.ru/', //URL to the payment completion page
    error_callback: function(error) {
        console.log(error)
    }
});

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

Step 3. Enter test details

The procedure depends on which store you're making the payment to, the demo one or the real one.

Payment to a demo store

If you're making the payment to the demo store, the widget will display two payment methods: via YooMoney wallet or from a bank card. You can only use a card for payment.

To make the payment, use the details of the special test bank card, for example:

card number — 5555555555554477
expiration date — 01/30 (or any other date greater than the current one)
CVC — 123 (or any other three digits)
code for 3-D Secure authentication — 123 (or any other three digits)

Payment to a real store

If you're making the payment to the real store, the widget will display all payment methods available to your store.

To make the payment, select the payment method you need and enter the details of the real means of payment.

Step 4. Complete the payment

After confirming the payment, the widget will redirect you to the payment completion page, which is the return_url that you specified in the widget initialization script. When accepting payments from real users, you will need to find out the payment status independently and display the relevant information to the user.

To learn the payment status, send periodic requests for payment information. You can also set up notifications and wait until YooMoney notifies you of status changes.

Example of a successfully completed payment

JSON
{
  "id": "22d6d597-000f-5000-9000-145f6df21d6f",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2018-07-10T14:32:08.545Z",
  "created_at": "2018-07-10T14:25:27.535Z",
  "description": "Order No. 72",
  "income_amount": {
    "value": "1.92",
    "currency": "RUB"
  },
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4477",
      "expiry_month": "01",
      "expiry_year": "2030",
      "card_type": "MasterCard",
      "issuer_country": "US"
    },
    "title": "Bank card *4477"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": true
}

Done! You just completed your first payment made via the widget.

Further steps

If you used the demo store, obtain data for authenticating requests for the real one.
Learn more about standard widget integration scenarios and YooMoney features and select what you need.
Display the widget on your payment page or set up the widget to be displayed in a pop-up window.
Choose how you will interact with the user after the payment.
Set up payment acceptance.
Configure the design of the payment form by selecting the language of the interface copy and customizing the colors of elements.
Set up the processing of widget initialization errors.