Выплаты продавцу
Для проведения выплаты вам нужно сначала получить от продавца данные карты, а затем отправить ЮKassa запрос на создание выплаты.
 
Особенности
Выплаты возможны на карты российских банков.
Есть лимиты на выплаты продавцу:
  • количество выплат по одной сделке — 1;
  • количество выплат за сутки — не более 20 на одну банковскую карту;
  • размер разовой выплаты — от 100 до 150 000 рублей (включительно);
  • сумма выплат за месяц — не более 1 500 000 рублей на одну банковскую карту.
 
Сценарий взаимодействия
Чтобы сделать выплату на банковскую карту:
  1. Получите данные банковской карты с помощью специального виджета ЮKassa.
  2. Проведите выплату с полученными данными.
Если в процессе выплата не пройдет, ЮKassa сообщит причину отмены выплаты.
 
Получение данных банковской карты
Чтобы провести выплату, вам нужно получить данные банковской карты продавца. Получение и хранение номера карты подпадает под действие стандарта PCI DSS, поэтому ЮKassa хранит эти данные на своей стороне.
Чтобы получить данные карты для выплаты, разместите у себя на сайте специальный виджет и отобразите продавцу форму для ввода данных. Для этого:
Шаг 1. Подключите библиотеку. Скрипт доступен по адресу:
https://static.yoomoney.ru/payouts-data-widget-front/widget.js
Шаг 2. На страницу сбора данных банковской карты добавьте HTML-элемент, в котором хотите разместить форму. Задайте для этого элемента атрибут
id
.
Шаг 3. Для инициализации виджета создайте новый экземпляр класса
PayoutsData
, передайте в него
successCallback
, который будет принимать параметры карты, и 
errorCallback
, который будет принимать код ошибки.
Шаг 4. Чтобы отобразить форму ввода номера карты, вызовите метод
render
. Передайте в него значение атрибута
id
, в котором нужно разместить форму, и при необходимости код, который нужно выполнить после отображения формы.
HTML
<!--Подключение библиотеки-->
<script src="https://static.yoomoney.ru/payouts-data-widget-front/widget.js"></script>

<!--HTML-элемент, в котором будет отображаться форма ввода номера карты-->
<div id="payout-form"></div>

<script>
//Инициализация виджета. Все параметры обязательные.
const payoutsData = new window.PayoutsData({
  successCallback(data) {
    //Обработка ответа с токеном карты
  },
  errorCallback(error) {
    //Обработка ошибок инициализации
  }
});

//Отображение платежной формы в контейнере
payoutsData.render('payout-form')
//После отображения платежной формы метод render возвращает Promise (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения платежной формы.
  });
</script>
Когда пользователь введет данные, библиотека вызовет
successCallback
. В результате вы получите следующие данные:
ПараметрТипОписание
synonimstring
Синоним банковской карты — идентификатор карты в системе ЮKassa, который нужно использовать для проведения выплат.
Пример:
uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106
panmaskstring
Маска карты для отображения данных пользователю.
Пример:
555555******4477
bankNamestring
Наименование эмитента, выпустившего банковскую карту.
Пример:
YOOMONEY NBCO LLC
typestring
Наименование платежной системы.
Пример:
MasterCard
Вы можете хранить эти данные на своей стороне без опасения утечки: их публикация не приводит к финансовым или имиджевым потерям.
Синоним банковской карты можно использовать несколько раз и для разных выплат. Для одной и той же карты можно сделать несколько синонимов.
Если при получении данных возникла ошибка, инициализируйте виджет заново и попросите продавца ввести данные еще раз.
 
Проведение выплаты
Шаг 1. Создайте выплату: отправьте ЮKassa запрос с данными для аутентификации запроса, ключом идемпотентности и данными для выплаты на банковскую карту:
  • в объекте
    amount
    передайте сумму, которую нужно выплатить продавцу;
  • в объекте
    deal
    передайте идентификатор сделки;
  • в параметре
    description
    передайте описание выплаты;
  • в параметре
    payout_token
    передайте полученный синоним банковской карты.
Пример запроса на создание выплаты
cURL
curl https://api.yookassa.ru/v3/payouts \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "800.00",
          "currency": "RUB"
        },
        "payout_token": "<Синоним банковской карты>",
        "description": "Выплата по заказу №37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект выплаты .
Пример созданного объекта выплаты
JSON
{
  "id": "po-285ec15d-0003-5000-a000-08d1bec7dade",
  "amount": {
    "value": "800.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card",
    "card": {
      "first6": "220220",
      "last4": "2537",
      "card_type": "MIR",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
  },
  "description": "Выплата по заказу №37",
  "created_at": "2021-06-21T14:28:45.132Z",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
  },
  "metadata": {
    "order_id": "37"
  },
  "test": false
}
Шаг 2. Дождитесь, когда банк получателя согласует выплату и ЮKassa изменит статус объекта выплаты на 
succeeded
. Для этого периодически отправляйте ЮKassa запросы на получение информации о выплате .
Пример объекта выплаты в статусе succeeded
JSON
{
    "id": "po-28559c4f-0003-5000-9000-0baf38b7a7fd",
    "amount": {
        "value": "800.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "bank_card",
    "card": {
      "first6": "220220",
      "last4": "2537",
      "card_type": "MIR",
      "issuer_country": "RU",
      "issuer_name": "Sberbank Of Russia"
    }
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": false
}
После успешной выплаты ЮKassa закроет сделку.
Пример объекта сделки после выплаты
JSON
{
    "type": "safe_deal",
    "fee_moment": "payment_succeeded",
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "balance": {
        "value": "0.00",
        "currency": "RUB"
    },
    "status": "closed",
    "created_at": "2021-06-18T07:28:39.390497Z",
    "expires_at": "2021-09-16T07:28:39.390513Z",
    "metadata": {
        "order_id": "37"
    },
    "test": true
}
 
Неуспешные выплаты
В процессе выплаты что-то может пойти не так. Например, может быть превышен лимит выплаты, ЮKassa может заподозрить попытку мошенничества. В этом случае выплата будет отменена и перейдет в статус
canceled
.
Чтобы вы могли лучше понимать, что произошло и что с этим делать, ЮKassa пришлет в объекте выплаты  комментарий к отмене выплаты (
cancellation_details
). В нём будут указаны инициатор и причина отмены выплаты. Вы можете использовать эти данные для анализа и решения проблем, вывода сообщений пользователю и любых других целей.
Пример объекта выплаты в статусе canceled
JSON
{
    "id": "po-285c0ab7-0003-5000-9000-0e1166498fda",
    "amount": {
        "value": "400.00",
        "currency": "RUB"
    },
    "status": "canceled",
    "payout_destination": {
        "type": "bank_card",
        "card": {
            "first6": "444444",
            "last4": "4448",
            "card_type": "Visa",
            "issuer_country": "PL",
            "issuer_name": "Krakowski Bank Spoldzielczy"
        }
    },
    "description": "Выплата по заказу №37",
    "created_at": "2021-06-16T13:04:55.633Z",
    "deal": {
        "id": "dl-28559370-0022-5000-8000-0b65d8e0e06d"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": true,
    "cancellation_details": {
        "party": "yoo_money",
        "reason": "general_decline"
    }
}
 
Инициаторы отмены выплаты
Инициатор отмены возвращается в параметре
party
объекта
cancellation_details
.
ЗначениеОписание
merchantПлатформа (вы)
yoo_moneyЮKassa
payment_network«Внешние» участники процесса выплаты — все остальные участники выплаты, кроме ЮKassa и вас (например, эмитент банковской карты)
 
Причины отмены выплаты
Причина отмены возвращается в параметре
reason
объекта
cancellation_details
.
ЗначениеОписание
fraud_suspectedВыплата заблокирована из-за подозрения в мошенничестве
general_declineПричина не детализирована. Пользователю следует обратиться к инициатору отмены выплаты за уточнением подробностей
one_time_limit_exceededПревышен лимит на разовое зачисление. Подробнее о лимитах
periodic_limit_exceededПревышен лимит выплат за период времени (сутки, месяц). Подробнее о лимитах
rejected_by_payeeЭмитент отклонил выплату по неизвестным причинам
 
Что почитать еще
Основы работы с APIТестированиеРеестры вознаграждений