Multipurpose token for payments and payouts

Only for bank cards

Using YooMoney, you can get a special bank card token that can be used for processing payments and making payouts.

How it works

A multipurpose token is a saved payment method that is used for autopayments or payouts.

To obtain a multipurpose token, you need to save the payment method by linking the user's bank card to your store. Во время привязки вы получите идентификатор способа оплаты, это и есть универсальный токен.

To make a payout, you need to send the saved payment method ID in the request for creating a payout, and, to process a payment, you need to send the ID in the request for creating a payment. Payments made using the saved payment method ID will be direct as in the user will not have to confirm the debiting of money.

Есть два вида сохранения способа оплаты:

Привязка во время платежа: вы сохраняете способ оплаты во время оплаты товара или услуги. При необходимости платеж можно создать на минимальную сумму, а затем отменить, чтобы деньги вернулись пользователю.
Привязка на нулевую сумму: вы создаете привязку, при которой ЮKassa проверяет банковскую карту, но деньги у пользователя не списываются.

For payments with saved payment methods, you can use any integration scenario if bank card payments are available. We recommend using only those integration options where no other payment methods except for cards are available. You can find the recommended integration options in the Preparing for integration section of this article.

General scenario for creating and using a token

Save the payment method first, then use it for payouts and payments.

Saving the payment method

Это сценарий для привязки карты с проведением платежа на минимальную сумму. If you want to link a card when paying for a product or service, you do not need to cancel the payment.
As an example, we use payment by bank card on the ready-made YooMoney page. The procedure may slightly vary depending on your selected integration scenario.

General scenario for saving the payment method

You inform the user that you will save their bank card details and use them for payments and payouts.
The user consents to the terms.
You create a payment by sending a POST request to YooMoney indicating that you need to save the payment method.
YooMoney returns the created payment object with the pending status as well as the link to the payment page.
You redirect the user to the payment page.
The user enters bank card details.
YooMoney sends the data to the acquirer.
If necessary, the acquirer asks the user for authentication via 3-D Secure.
The user completes the verification process.
The acquirer provides YooMoney with the results of the payment.
YooMoney informs the user of the results of the payment.
The user returns to your website.
You request payment information by sending a GET request with the payment ID to YooMoney.
YooMoney returns the created payment object in its current status, which is either waiting_for_capture (money is authorized, awaiting debiting) or canceled (payment canceled).
If the object status is waiting_for_capture, you check that the payment method has been saved and save the payment method ID.
You cancel the payment by sending a POST request with the payment ID to YooMoney.
YooMoney returns the payment object with the canceled status.
You display the results of saving the payment method to the user.

Payout scenario

General scenario for making payouts using saved payment method ID

You create a payout by sending a POST request to YooMoney with the ID of the saved payment method.
YooMoney sends an order to the acquirer to transfer money to the payout recipient.
The acquirer processes the request and reports on the results of the transaction.
YooMoney returns the payout object with the final status, which is either succeeded (payout successful) or canceled (payout canceled).

If, in response to a request, YooMoney returns the payout object with the pending status, it means the acquirer is still processing the payout order. To find out the final status of the payout, wait for the YooMoney notification or request payout information using the GET method with increasing reasonable intervals (for example, you can use the Fibonacci sequence).

Payment made using a saved payment method

General scenario for processing payments using saved payment method ID

You create a payment by sending a POST request to YooMoney with the ID of the saved payment method.
YooMoney sends an order to the acquirer to debit money from the user's bank card.
The acquirer processes the request and reports on the results of the transaction.
YooMoney returns the payout object with the final status, which is either succeeded (payment successful) or canceled (payment canceled).

If you process payments in two stages, the status of the returned payment will be either waiting_for_capture (money is authorized and ready for debiting) or canceled (payment canceled). If the payment status is waiting_for_capture, you need to debit the money or cancel the payment to complete the process.

Preparing for integration

To enable the feature, inform your YooMoney manager that you want to accept payments and make payouts using a multipurpose token. If necessary, the manager will create a store or a gateway for you (if you did not have those).

Interaction format

The interaction format for payments and payouts is the same, the only difference is in the data for request authentication: payment acceptance requires the login and the secret key of the store, payouts require the login and the secret key of the gateway.

Preparing for payment method saving and payment acceptance

To accept payments, you need to:

Get store ID and secret key.
Approve the use of autopayments with the YooMoney manager.
Set up notifications.
Выбрать вид сохранения способа оплаты:
- Привязка во время платежа (с последующей отменой платежа при необходимости)
- Привязка на нулевую сумму
Select an integration scenario. We recommend using the integration scenarios that include only bank cards:
- Payment via bank card on a ready-made YooMoney page
- YooMoney widget as a separate form for payment via bank card (available only after approval by the manager)
- Checkout.js (requires approval by the manager)
- Payment via bank card in your payment form (requires PCI DSS compliance certificate)
Implement payment method saving.
Implement autopayments (payments made using a saved payment method).

Preparing for payouts

You need to get the gateway ID and secret key and implement payouts using the saved payment method. You don't need to get approval on anything else.

Saving a payment method

To authenticate a request, you need to use your YooMoney store's ID and secret key for payment acceptance.

Шаг 1. Сообщите пользователю, что ему нужно привязать к вашему сервису свою банковскую карту. Подробно расскажите, что это значит и как это работает:

Как вы будете использовать данные этой карты: с какой регулярностью вы будете списывать деньги и делать выплаты, на какую сумму.
Как можно отказаться от использования карты для платежей и выплат.

Шаг 2. Получите от пользователя согласие на привязку его карты для проведения выплат и безакцептных платежей.

Шаг 3. Сохраните способ оплаты подходящим вам способом:

Привязка во время платежа — вы принимаете оплату за товар или услугу и в процессе сохраняете данные карты. Платеж можно принять на минимальную сумму (чтобы убедиться, что карта действительна), а затем отменить.
Привязка на нулевую сумму — вы создаете привязку, в процессе которой ЮKassa проверяет, что с картой всё в порядке, и сохраняет ее данные.

Шаг 4. Если вы используете привязку во время платежа, проверьте, что оплата была банковской картой и способ оплаты сохранен.

Шаг 5. Сохраните полученный идентификатор способа оплаты. Рекомендуется сохранять его в связке с идентификатором пользователя в вашей системе. Это нужно, чтобы в дальнейшем вы могли соотнести пользователя и его платежные данные.

Making a payout

To authenticate a request, you need to use your YooMoney gateway's ID and secret key for payouts.

Create a payout by sending a request to YooMoney with the authentication data, idempotency key, and data for payout to a bank card using the saved payment method:

in the amount object, specify the amount to be paid to the user; the amount must fall within limits;
in the description parameter, specify the payout description;
in the payment_method_id parameter, specify the saved payment method ID.

Example of a request for creating a payout

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Gateway ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "5.00",
          "currency": "RUB"
        },
        "payment_method_id": "<Saved payment method's ID>",
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'

In response to the request, YooMoney will return the created payout object .

Example of a created payout object

JSON
{
  "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
  "amount": {
    "value": "5.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "555555",
      "last4": "4477",
      "card_type": "Mir",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
  },
  "description": "Payout for order No. 37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "metadata": {
    "order_id": "37"
  },
  "test": false
}

If you received a payout with the pending status, wait until the status changes to succeeded or canceled. Wait for the YooMoney notification or request payout information with an increasing reasonable interval.

Example of request for payment information

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Gateway ID>:<Secret Key> \

Example of a payout object with the succeeded status

JSON
{
    "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
    "amount": {
        "value": "5.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "bank_card",
        "card": {
          "first6": "555555",
          "last4": "4477",
          "card_type": "Mir",
          "issuer_country": "RU",
          "issuer_name": "Sberbank Of Russia"
        }
    },
    "description": "Payout for order No. 37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}

Processing a payment

To authenticate a request, you need to use your YooMoney store's ID and secret key for payment acceptance.

Create a payment by sending a request to YooMoney with authentication data, idempotency key, and data for making a payment using the saved payment method:

in the amount object, specify the amount to be debited from the user's card;
in the description parameter, specify the payment description;
in the payment_method_id parameter, specify the saved payment method ID;
in the capture parameter, specify the true value if you want to make a payment in one stage and debit the money immediately, and the false value if you want to make a payment in two stages and debit the money later.

Example of a request for creating a payment

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"
        },
        "capture": true,
        "payment_method_id": "<Saved payment method's ID>",
        "description": "Order No. 37"
      }'

In response to the request, YooMoney will return the created payment object . Upon a successful payment, the payment_method object will display information about the payment data of the saved method that you used when processng the payment.

Example of a payment with the succeeded status

JSON
{
  "id": "255350c9-000f-5000-a000-1f211b3ea0a7",
  "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-18T17:20:50.825Z",
  "created_at": "2018-07-18T17:18:39.345Z",
  "description": "Order No. 72",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22e18a2f-000f-5000-a000-1db6312b7767",
    "saved": true,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "test": false
}

If you are process payments in two stages, capture or cancel the payment.