YooMoney Checkout Widget: Saving the user's bank cards — Payment acceptance via the YooMoney API

Saving the user’s bank cards

The YooMoney payment widget can save the details of bank cards used for payment in your store. The user won’t have to re-enter the details for recurring payments: they will be able to select the card they paid with earlier. To make a payment, the use only needs to confirm the payment by completing authentication via 3-D Secure or entering the CVV2 (CVC2, CID) code.

If you want to implement your own payment method selection screen and save payment details for one-click payments, use autopayments with conditional saving for payment methods.

Selecting a saved card when making a payment

Specifics

The widget saves bank card details for successful payments and displays them for recurring payments. The user can select one of five frequently used cards or enter a new one. Unnecessary cards can be deleted.

The widget saves arbitrary bank cards only, so the cards that are linked to the YooMoney wallet cannot be saved.

You need to specify merchant_customer_id (user identifier in your system) in the request for creating a payment. If you don’t do this, you won’t be able to save the card.

Make sure that the merchant_customer_id corresponds to the user who wants to make a purchase. For example, use two-factor authentication. If you send an incorrect identifier in the request, the user might choose someone else’s bank cards for payment.

If you have several stores connected to YooMoney, the user can pay with a saved card in all of them. This requires the user ID to be the same in all of your stores.

During a payment, the widget can remember the card details and save the card for autopayments. More about saving the card details and using it for autopayments

Saving cards in the widget is not suitable for regular unconditional payments. If you want to make autopayments, specify the save_payment_method parameter in the request and use payment_method_id for subsequent payments. Learn more about saving payment method for autopayments

If 3-D Secure authentication is disabled in your store, you won’t be able to save the bank card. Contact your manager to enable the option to save the card.

Interaction scenario

Step 1. First payment to the store: the user enters bank card details and agrees to save them. After the user confirms the debit of money, the YooMoney payment widget will remember the user’s bank card details.

Step 2. Subsequent payments to the store: the user selects the card saved in the widget for recurring payments.

First payment to the store

User proceeds to checkout.
You send a payment creation request to YooMoney and additionally specify the user ID in your system.
YooMoney returns the created payment object with a token for initializing the widget.
You initialize the widget and display the form on the payment page.
User chooses to pay with a bank card, enters the data, and allows the widget to save their payment data.
If necessary, the widget displays a pop-up window for 3-D Secure authentication.
User confirms the payment.
If the payment is processed, the widget redirects the user to the payment completion page on your side.
You display the required information depending on the status of the payment.

Saving a bank card in the store

Subsequent payments to the store

User proceeds to checkout.
You send a payment creation request to YooMoney and additionally specify the user ID in your system.
YooMoney returns the created payment object with a token for initializing the widget.
You initialize the widget and display the form on the payment page.
The widget displays user’s saved bank cards
User selects the card saved in your store.
The widget displays a pop-up window for 3‑D Secure authentication or asks for a CVV2 (CVC2, CID) code.
User confirms the payment.
If the payment is processed, the widget redirects the user to the payment completion page on your side.
You display the required information depending on the status of the payment.

Selecting a saved card for subsequent payments

Payment with saving the bank card in a store

Create a payment and specify the merchant_customer_id with the user’s identifier in your system, for example, the login of their account in your store.

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

YooMoney will respond with the merchant_customer_id without any changes and confirmation_token, the token for initializing the widget. Proceed with the payment in the usual manner. Далее проводите платеж как обычно.

Saving a bank card and using it for autopayments

The widget can simultaneously save a bank card and start using it for autopayments. In the request for creating a payment, specify the user ID in your system and the save_payment_method parameter with the value true for unconditional saving. For conditional saving, specify only the user ID: there is no need to specify save_payment_method. More about saving a payment method for autopayments

Saving a bank card and using it for autopayments

Payment with saving a bank card and using it for autopayments

Create a payment and specify save_payment_method and merchant_customer_id with the user’s identifier in your system.

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,
        "save_payment_method": true,
        "description": "Order No. 72",
        "merchant_customer_id": "+79999999999"
      }'

YooMoney will respond with the merchant_customer_id without any changes and confirmation_token, the token for initializing the widget.

If the payment was successful, save the payment_method.id payment method ID. Use it as the identifier of the saved payment method for subsequent payments.