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

Проведение сделок

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

Особенности

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

Вознаграждение после успешного платежа: вы получаете свое вознаграждение сразу после успешного платежа. При возврате платежа вы можете вернуть покупателю только ту сумму, которая предназначалась продавцу.
Вознаграждение при закрытии сделки: вы получаете свое вознаграждение после успешной выплаты при закрытии сделки. При возврате платежа вы можете вернуть покупателю всю сумму платежа, включая ваше вознаграждение.

У сделки есть срок жизни. Это промежуток времени (например, 90 дней), в течение которого нужно принять оплату от покупателя и сделать выплату продавцу. Если к концу этого срока вы не сделаете выплату или возврат, ЮKassa автоматически закроет сделку и вернет оплату покупателю. Минимальная длительность сделки — 1 день, максимальная — 180 дней. Срок жизни устанавливается при подключении Безопасной сделки и распространяется на все сделки вашей интернет-площадки в ЮKassa.

Сделка закрывается автоматически при выполнении определенных условий.

Заключение сделки

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

safe_deal

— Безопасная сделка) и моментом, когда ЮKassa нужно будет перечислить вознаграждение вашей платформе: после успешной оплаты (

payment_succeeded

) или при закрытии сделки (

deal_closed

В параметре

description

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

Также вы можете передать дополнительные данные, например номер заказа в вашей системе. ЮKassa вернет их без изменений. Данные необходимо передавать в объекте

metadata

в виде набора пар «ключ-значение» (строки в формате UTF-8).

Пример запроса на создание сделки

cURL
curl https://api.yookassa.ru/v3/deals \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "safe_deal",
        "fee_moment": "payment_succeeded",
        "metadata": {
          "order_id": "37"
        },
        "description":"SAFE_DEAL 123554642-2432FF344R"
      }'

В ответ на запрос ЮKassa вернет созданный объект сделки .

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

JSON
{
   "type": "safe_deal",
   "fee_moment": "payment_succeeded",
   "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
   "balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "payout_balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "status": "opened",
   "created_at": "2021-06-18T07:28:39.390497Z",
   "expires_at": "2021-09-16T07:28:39.390513Z",
   "metadata": {
      "order_id": "37"
   },
   "description":"SAFE_DEAL 123554642-2432FF344R",
   "test": false
}

Шаг 2. Сохраните идентификатор сделки (значение параметра

в созданном объекте). Он понадобится вам при проведении операций в составе сделки и получения статуса сделки.

Получение информации о сделке

Если вы хотите узнать баланс, статус, срок жизни сделки или другую информацию о ней, отправьте ЮKassa запрос на получение информации о сделке и передайте в нём идентификатор сделки.

Пример запроса на создание сделки

cURL
curl https://api.yookassa.ru/v3/deals/{deal_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

В ответ на запрос ЮKassa вернет объект сделки в актуальном состоянии.

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

JSON
{
   "type": "safe_deal",
   "fee_moment": "payment_succeeded",
   "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
   "balance": {
      "value": "800.00",
      "currency": "RUB"
   },
   "payout_balance": {
      "value": "800.00",
      "currency": "RUB"
   },
   "status": "opened",
   "created_at": "2021-06-18T07:28:39.390497Z",
   "expires_at": "2021-09-16T07:28:39.390513Z",
   "metadata": {
      "order_id": "37"
   },
   "description":"SAFE_DEAL 123554642-2432FF344R",
   "test": false
}

Получение списка сделок

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

Вы можете отфильтровать сделки по времени создания, по сроку автоматического закрытия сделки, по статусу и по тексту в описании сделки (параметр

description

объекта сделки ).

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

Пример запроса на получение списка сделок

cURL
curl https://api.yookassa.ru/v3/deals?limit=10&status=opened&full_text_search=123554642 \
  -X GET
  -u <Идентификатор магазина>:<Секретный ключ>

В ответ на запрос вернется список сделок . В списке будет информация о сделках, созданных за последние 3 года. Список будет отсортирован по времени создания сделок в порядке убывания.

Пример списка сделок

JSON
{
   "type":"list",
   "items":[
      {
         "type":"safe_deal",
         "fee_moment":"deal_closed",
         "id":"dl-285e5ee7-0022-5000-8000-01536a44b147",
         "balance":{
            "value":"-45.00",
            "currency":"RUB"
         },
         "payout_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"
         },
         "description":"SAFE_DEAL 123554642-2432FF344R",
         "test":false
      },
      {
         "type":"safe_deal",
         "fee_moment":"payment_succeeded",
         "id":"dl-d68d2fe4-2abb-47e5-8112-32e27f87fb52",
         "balance":{
            "value":"0.00",
            "currency":"RUB"
         },
         "payout_balance":{
            "value":"0.00",
            "currency":"RUB"
         },
         "status":"opened",
         "created_at":"2021-07-29T07:28:39.390497Z",
         "expires_at":"2021-10-29T07:28:39.390513Z",
         "metadata":{
            "order_id":"37"
         },
         "description":"SAFE_DEAL 123554642-6722FF343W",
         "test":false
      }
   ],
   "next_cursor":"dl-28559370-0022-5000-8000-0b65d8e0e06d"
}

Закрытие сделки

Сделку закрывает ЮKassa. Основания для закрытия сделки:

вы приняли оплату от покупателя и успешно выплатили ее продавцу (на балансе сделки не осталось денег);
вы приняли оплату от покупателя, но вернули ее обратно (на балансе сделки не осталось денег);
закончился срок жизни сделки, указанный в параметре
expires_at
(если на балансе сделки остались деньги, ЮKassa вернет их покупателю).

Пример закрытой сделки

JSON
{
   "type": "safe_deal",
   "fee_moment": "payment_succeeded",
   "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
   "balance": {
      "value": "0.00",
      "currency": "RUB"
   },
   "payout_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"
   },
   "description":"SAFE_DEAL 123554642-2432FF344R",
   "test": false
}

Есть вопросы или замечания по документации?

Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить. Для этого оставьте свои контакты и выберите время.

Да, хочу обсудить

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

Входящие уведомления Основы работы с API Прием оплаты от покупателя Выплаты продавцу Тестирование

Особенности

Заключение сделки

Получение информации о сделке

Получение списка сделок

Закрытие сделки