Проведение сделок
Для проведения Безопасной сделки нужно создать в ЮKassa сделку, в рамках которой вы будете проводить все операции.
 
Особенности
В ЮKassa есть два сценария проведения сделок, которые зависят от момента перечисления вам вознаграждения:
  • Вознаграждение после успешного платежа: вы получаете свое вознаграждение сразу после успешного платежа. При возврате платежа вы можете вернуть покупателю только ту сумму, которая предназначалась продавцу.
  • Вознаграждение при закрытии сделки: вы получаете свое вознаграждение после успешной выплаты при закрытии сделки. При возврате платежа вы можете вернуть покупателю всю сумму платежа, включая ваше вознаграждение.
У сделки есть срок жизни. Это промежуток времени (например, 90 дней), в течение которого нужно принять оплату от покупателя и сделать выплату продавцу. Если к концу этого срока вы не сделаете выплату или возврат, ЮKassa автоматически закроет сделку и вернет оплату покупателю. Минимальная длительность сделки — 1 день, максимальная — 180 дней. Срок жизни устанавливается при подключении Безопасной сделки и распространяется на все сделки вашей интернет-площадки в ЮKassa.
Сделка закрывается автоматически при выполнении определенных условий.
 
Заключение сделки
Шаг 1. Создайте сделку: отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности (подойдет любое случайное значение), типом сделки (
safe_deal
 — Безопасная сделка) и моментом, когда ЮKassa нужно будет перечислить вознаграждение вашей платформе: после успешной оплаты (
payment_succeeded
) или при закрытии сделки (
deal_closed
).
Также вы можете передать дополнительные данные, например номер заказа в вашей системе. Ю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"
        }
      }'
В ответ на запрос ЮKassa вернет созданный объект сделки .
Пример созданного объекта сделки
JSON
{
    "type": "safe_deal",
    "fee_moment": "payment_succeeded",
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "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"
    },
    "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"
    },
    "status": "opened",
    "created_at": "2021-06-18T07:28:39.390497Z",
    "expires_at": "2021-09-16T07:28:39.390513Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}
 
Закрытие сделки
Сделку закрывает Ю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"
    },
    "status": "closed",
  "created_at": "2021-06-18T07:28:39.390497Z",
    "expires_at": "2021-09-16T07:28:39.390513Z",
    "metadata": {
        "order_id": "37"
    },
    "test": false
}
 
Что почитать еще
Основы работы с APIПрием оплаты от покупателяВозврат оплаты покупателюВыплаты продавцуТестирование