Безопасная сделка: выплаты продавцу — Прием платежей по API ЮKassa

Выплаты продавцу

Для проведения выплаты вам нужно сначала получить от продавца данные, куда ему перевести вознаграждение, а затем отправить ЮKassa запрос на создание выплаты.

Особенности

Выплаты возможны на банковские карты российских банков и кошельки ЮMoney с любым статусом, кроме анонимного.

Для всех видов выплат есть ограничения на выплаты продавцу. Если лимиты превышены, выплаты не пройдут.

Вид выплаты	Разовый лимит	Лимит за период
Банковская карта Ограничения действуют на одну банковскую карту получателя выплаты	Минимум — 1 рубль Максимум — 150 000 рублей	Максимальное количество выплат за сутки — 20 Максимальная сумма выплат за месяц — 1 500 000 рублей
Кошелек ЮMoney Лимиты зависят от статуса кошелька	Минимум — 1 рубль Максимум зависит от текущего баланса кошелька. После выплаты баланс кошелька не может превышать определенную сумму: Именной кошелек — 60 000 рублей Идентифицированный кошелек — 500 000 рублей	Максимальная сумма выплат за месяц — 600 000 рублей

Сценарий взаимодействия

Чтобы сделать выплату:

Получите от продавца данные о том, куда перевести его вознаграждение.
Проведите выплату с полученными данными.

Конкретный порядок действий зависит от вида выплаты:

Выплаты на банковскую карту
Выплаты на кошелек ЮMoney

Если в процессе выплата не пройдет, ЮKassa сообщит причину отмены выплаты.

Выплаты на банковскую карту

Чтобы провести выплату, вам нужно получить данные банковской карты продавца. Получение и хранение номера банковской карты подпадает под действие стандарта PCI DSS, поэтому ЮKassa хранит эти данные на своей стороне. Чтобы получить данные карты продавца, используйте специальный виджет ЮKassa.

Если у вас есть сертификат на соответствие требованиям PCI DSS, вы можете собрать данные самостоятельно и при проведении выплаты передать ЮKassa номер банковской карты.

Выберите, как вы хотите получить данные банковской карты продавца:

С помощью виджета ЮKassa для сбора данных
Самостоятельно

Выплаты с получением данных с помощью виджета ЮKassa

Чтобы сделать выплату на банковскую карту:

Получите данные банковской карты с помощью специального виджета Ю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>


<div id="payout-form"></div>

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

//Отображение платежной формы в контейнере
payoutsData.render('payout-form')
//После отображения платежной формы метод render возвращает Promise (можно не использовать).
  .then(() => {
    //Код, который нужно выполнить после отображения платежной формы.
  });
</script>

Когда пользователь введет данные, библиотека вызовет successCallback. В результате вы получите следующие данные:

Параметр	Тип	Описание
synonim	string	Синоним банковской карты — идентификатор карты в системе ЮKassa, который нужно использовать для проведения выплат. Пример: `uAFUv0jwtUA_8mMIFeRqzAYw.SC.001.202106`
panmask	string	Маска карты для отображения данных пользователю. Пример: `555555******4477`
bankName	string	Наименование эмитента, выпустившего банковскую карту. Пример: `YOOMONEY NBCO LLC`
type	string	Наименование платежной системы. Пример: `MasterCard`

Вы можете хранить эти данные на своей стороне без опасения утечки: их публикация не приводит к финансовым или имиджевым потерям.

Синоним банковской карты можно использовать несколько раз и для разных выплат. Для одной и той же карты можно сделать несколько синонимов.

Если при получении данных возникла ошибка, инициализируйте виджет заново и попросите продавца ввести данные еще раз.

Проведение выплаты на банковскую карту

Шаг 1. Создайте выплату: отправьте ЮKassa запрос с данными для аутентификации запроса, ключом идемпотентности и данными для выплаты на банковскую карту:

в объекте amount передайте сумму, которую нужно выплатить продавцу;
в объекте deal передайте идентификатор сделки;
в параметре description передайте описание выплаты;
в параметре payout_token передайте полученный синоним банковской карты.

Пример запроса на создание выплаты

cURL
PHP
Python
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 закроет сделку.

Выплаты с самостоятельным получением данных карты

Чтобы передавать в запросе на создание выплаты номер банковской карты, вам нужно получить сертификат на соответствие требованиям PCI DSS.

Чтобы сделать выплату на банковскую карту:

Получите данные банковской карты.
Проведите выплату с полученными данными.

Получение данных банковской карты

Для проведения выплаты вам понадобится номер банковской карты. Получите его любым удобным вам способом.

Выплаты можно делать только на карты российских банков.

Проведение выплаты на банковскую карту

в объекте amount передайте сумму, которую нужно выплатить продавцу;
в объекте deal передайте идентификатор сделки;
в параметре description передайте описание выплаты;
в объекте payout_destination_data передайте код вида выплаты bank_card и номер банковской карты, на которую нужно перевести вознаграждение продавца.

Пример запроса на создание выплаты

cURL
PHP
Python
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_destination_data":
        {
            "type": "bank_card",
            "card": {
              "number": "5555555555554477"
          }
        },
        "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": "555555",
      "last4": "4477",
      "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
}

Пример объекта выплаты в статусе succeeded

JSON
{
    "id": "po-28559c4f-0003-5000-9000-0baf38b7a7fd",
    "amount": {
        "value": "800.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": "Выплата по заказу №37",
    "created_at": "2021-06-21T14:28:45.132Z",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": false
}

Если выплата успешна, ЮKassa закроет сделку.

Выплаты на кошелек ЮMoney

Чтобы сделать выплату на кошелек ЮMoney:

Получите данные кошелька ЮMoney.
Проведите выплату с полученными данными.

Получение данных кошелька ЮMoney

Для проведения выплаты вам понадобится номер кошелька ЮMoney. Получите его любым удобным вам способом.

Чтобы получить выплату, владельцу кошелька нужно пройти полную или упрощенную идентификацию в ЮMoney (статус кошелька — именной или идентифицированный).

Максимальный размер выплаты зависит от лимита на баланс: после выплаты остаток в кошельке не должен превышать определенную сумму, размер которой зависит от статуса кошелька. Если выплата не проходит из-за лимита на баланс, получателю следует изменить статус кошелька или потратить сумму, на которую превышается остаток.

Проведение выплаты на кошелек ЮMoney

Создайте выплату

: отправьте ЮKassa запрос с данными для аутентификации запроса, ключом идемпотентности и данными для выплаты на кошелек ЮMoney:

в объекте amount передайте сумму, которую нужно выплатить продавцу;
в объекте deal передайте идентификатор сделки;
в параметре description передайте описание выплаты;
в объекте payout_destination_data передайте код вида выплаты yoo_money и номер кошелька, на который нужно перевести вознаграждение продавца.

Пример запроса на создание выплаты

cURL
PHP
Python
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_destination_data": {
          "type": "yoo_money",
          "account_number": "4100116075156746"
        },
        "description": "Выплата по заказу № 37",
        "metadata": {
          "order_id": "37"
        },
        "deal": {
          "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
        }
      }'

В ответ на запрос ЮKassa вернет созданный объект выплаты . Он будет уже в финальном статусе — succeeded или canceled.

Пример созданного объекта выплаты

JSON
{
    "id": "po-28836e72-0003-5000-9000-08892e762c41",
    "amount": {
        "value": "800.00",
        "currency": "RUB"
    },
    "status": "succeeded",
    "payout_destination": {
        "type": "yoo_money",
        "account_number": "4100116075156746"
    },
    "description": "Выплата по заказу № 37",
    "created_at": "21.06.2021T14:28:45.132Z",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147"
    },
    "metadata": {
        "order_id": "37"
    },
    "test": "false"
}

Если выплата успешна, ЮKassa закроет сделку.

Неуспешные выплаты

В процессе выплаты что-то может пойти не так. Например, может быть превышен лимит выплаты, Ю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": false,
    "cancellation_details": {
        "party": "yoo_money",
        "reason": "general_decline"
    }
}

Инициаторы отмены выплаты

Инициатор отмены возвращается в параметре party объекта cancellation_details.

Значение	Описание
yoo_money	ЮKassa
payout_network	«Внешние» участники процесса выплаты — все остальные участники выплаты, кроме ЮKassa и вас (например, эмитент банковской карты)

Причины отмены выплаты

Причина отмены возвращается в параметре reason объекта cancellation_details.

Значение	Описание
fraud_suspected	Выплата заблокирована из-за подозрения в мошенничестве. Следует обратиться к инициатору отмены выплаты за уточнением подробностей или выбрать другой способ получения выплаты или другое платежное средство (например, другую банковскую карту).
general_decline	Причина не детализирована. Пользователю следует обратиться к инициатору отмены выплаты за уточнением подробностей.
identification_required	Кошелек ЮMoney не идентифицирован. Пополнение анонимного кошелька запрещено. Пользователю необходимо идентифицировать кошелек.
one_time_limit_exceeded	Превышен лимит на разовое зачисление. Можно уменьшить размер выплаты, разбить сумму и сделать несколько выплат, выбрать другой способ получения выплат или другое платежное средство (например, другую банковскую карту).
periodic_limit_exceeded	Превышен лимит выплат за период времени (сутки, месяц). Следует выбрать другой способ получения выплаты или другое платежное средство (например, другую банковскую карту).Превышен лимит выплат за период времени (сутки, месяц).
rejected_by_payee	Эмитент отклонил выплату по неизвестным причинам. Пользователю следует обратиться к эмитенту за уточнением подробностей или выбрать другой способ получения выплаты или другое платежное средство (например, другую банковскую карту).

Что почитать еще

Входящие уведомления Основы работы с API Тестирование Безопасной сделки Реестры вознаграждений