Making payouts to bank cards using the card synonym

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:

Obtain bank card details.
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 1. Initialize the widget and display the form on the data collection page.

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
}