Old versions of the API
Help
Sign up for YooMoney
Making payouts to cards using a bank card synonym
This article describes how to make payouts to bank cards using a card synonym that received from the data collection widget.
To make a payout to a bank card:
  1. Obtain bank card details.
  2. Make a payout using details received.
If you need to display the payout recipient information in payout report extracts (e.g., for submission to government agencies), save the recipient's data in YooMoney before making a payout. Then set the saved data ID in the request for creating a payout. More about sending the recipient's data for the purpose of making extracts from reports
Obtaining bank card details
In order to make a payout, you need to get a bank card synonym using the widget. If you already have a synonym for the card you need, you can use this one. If you don't, get a synonym using the widget:
Step 2. When a user enters the card number, process the result.
Making a payout using the widget
Create a payout : send YooMoney a request with data for authentication, idempotence key, and information for a payout to a bank card:
  • set the amount to be paid to the user in the amount object; the amount must not exceed the limits;
  • enter the description of the payout in the description parameter;
  • set the received bank card synonym (a value of the payout_token parameter received from the widget) in the payout_token parameter;
  • if you make payouts with recipient's data specified for the extract from a report, specify the personal data ID in the personal_data array.
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"
        },
        "payout_token": "<Bank card synonym>",
        "description": "Payout for order No. 37",
        "metadata": {
          "order_id": "37"
        }
      }'
YooMoney will return a created payout object  in response to the request.
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 a request for payout information
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payouts/{payout_id} \
    -X GET \
    -u <Gateway ID>:<Secret Key> \
Example of the 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
}
See also
Payouts to the self-employed