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.

To obtain a multipurpose token, you need to save the payment method by linking the user's bank card to your store. To do this, you need to process a successful payment. The ID of the saved payment method will be the ID of the successful payment. This ID is the multipurpose token.

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.

There are two methods of saving the payment method: make a payment for the minimum amount and then cancel it so that the money is returned to the user, or save the payment method during the payment for a product or service.

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

This is a scenario for linking a card after making a payment with the minimum amount. 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.

To save a payment method, specify the save_payment_method parameter with the true value in the request for creating a payment.

There are two options for saving a payment method:

Saving only: you make a minimum amount payment (to make sure the card is valid) and then cancel it.
Saving after the payment: you accept payment for a product or service and save the card details in the process.

Saving only

Step 1. Inform the user that they need to link their bank card to your service. Explain in detail what this means and how it works:

How you will use the details of this card: how often you will debit money and make payouts, and in what amounts.
What should be done to save the payment method: let the user know that they need to make a minimum amount payment. They will have to use the bank card that they want to link to your service. The money will be returned to their account afterwards.
How to stop using the card for payments and payouts.

Obtain user's consent to link their card for payouts and direct payments.

Step 2. When the user proceeds to linking a bank card, start making a payment with payment method saving in accordance with the selected integration scenario. In the request for creating a payment, specify the save_payment_method parameter with the true value to save the payment method, and the capture parameter with the false value to process the payment in two stages.

Example of payment via bank card with payment method saving

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": "1.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "capture": false,
        "save_payment_method": true,
        "description": "Payment for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'

Step 3. If the payment was returned with the pending status and the confirmation_url parameter, redirect the user to confirmation_url to confirm the payment.

Example of payment with the pending status

JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "pending",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Payment for order No. 37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": false
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.com/return_url",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2a217a2d-000f-5000-9000-1bd6f124af9c"
  },
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  }
}

Step 4. Wait for the user to confirm the payment, and its status will change to waiting_for_capture. To find out the payment status, wait for notification from YooMoney, or send periodic inquiries for payment information .

Step 5. Make sure that the payment was made from a bank card and the payment method is saved: the payment_method.type parameter in the payment object has the bank_card value, and the value of the payment_method.saved parameter is true.

Example of payment with the waiting_for_capture status

JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "waiting_for_capture",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Payment for order No. 37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": true,
    "title": "Bank card *4444",
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "12",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU"
    }
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "expires_at": "2022-06-02T11:37:55.385Z",
  "test": false,
  "paid": true,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  }
}

Step 6. Save the payment method ID (payment_method.id). It will serve as the multipurpose token. Use it when making payouts and direct payments.

Step 7. Cancel the payment .

Example of a request for canceling a payment

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{

      }'

Example of payment with the canceled status

JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "canceled",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Payment for order No. 37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": true,
    "title": "Bank card *4444",
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "12",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU"
    }
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  },
  "cancellation_details": {
    "party": "merchant",
    "reason": "canceled_by_merchant"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  }
}

Step 8. Inform the user about the results of saving the bank card data.

Saving after the payment

Step 1. Inform the user that you will save their bank card details during payment. Explain in detail what this means and how it works:

How you will use the details of this card: how often you will debit money and make payouts, and in what amounts.
How to stop using the card for payments and payouts.

Obtain user's consent to link their card for payouts and direct payments.

Step 2. When the user proceeds to paying for a product or service, start making a payment with payment method saving in accordance with the selected integration scenario. In the request for creating a payment, specify the save_payment_method parameter with the true value.

Example of payment via bank card with payment method saving

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": "1.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://example.com/return_url"
        },
        "capture": false,
        "save_payment_method": true,
        "description": "Payment for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'

Step 3. If the payment was returned with the pending status and the confirmation_url parameter, redirect the user to confirmation_url to confirm the payment.

Example of payment with the pending status

JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "pending",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Payment for order No. 37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": false
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.com/return_url",
    "confirmation_url": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=2a217a2d-000f-5000-9000-1bd6f124af9c"
  },
  "test": false,
  "paid": false,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  }
}

Step 4. Wait for the user to confirm the payment, and its status will change to either succeeded or waiting_for_capture (if the payment was made in two stages). To find out the payment status, wait for notification from YooMoney, or send periodic inquiries for payment information .

Example of payment with the waiting_for_capture status

JSON
{
  "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
  "status": "waiting_for_capture",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "description": "Payment for order No. 37",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "payment_method": {
    "type": "bank_card",
    "id": "2a217a2d-000f-5000-9000-1bd6f124af9c",
    "saved": true,
    "title": "Bank card *4444",
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_year": "2030",
      "expiry_month": "12",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU"
    }
  },
  "created_at": "2022-05-26T11:37:17.497Z",
  "expires_at": "2022-06-02T11:37:55.385Z",
  "test": false,
  "paid": true,
  "refundable": false,
  "metadata": {
    "order_id": "37"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  }
}

Step 6. Save the payment method ID (payment_method.id). It will serve as the multipurpose token. Use it when making payouts and direct payments.

Step 7. If the payment is made in two stages, capture or cancel the payment.

Step 8. Inform the user about the results of the payment.

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.