Проведение сделок
Для проведения Безопасной сделки нужно создать в Ю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. Сохраните идентификатор сделки (значение параметра
id
в созданном объекте). Он понадобится вам при проведении операций в составе сделки и получения статуса сделки.
 
Получение информации о сделке
Если вы хотите узнать баланс, статус, срок жизни сделки или другую информацию о ней, отправьте Ю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Прием оплаты от покупателяВыплаты продавцуТестирование