Old versions of the API
Help
Sign up for YooMoney
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
  1. User goes to the payment page.
  2. You initialize the widget on the payment page and display the payment form.
  3. User selects the payment method, enters the details, and confirms the payment.
  4. YooMoney redirects the user to your page after the payment is complete.
  5. 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>Payment acceptance via the YooMoney widget</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
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"
      }'
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
See also
Basics of using the API