Для проведения Безопасной сделки нужно создать в Ю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 }