Для проведения Безопасной сделки нужно создать в ЮKassa сделку, в рамках которой вы будете проводить все операции.
В ЮKassa есть два сценария проведения сделок, которые зависят от момента перечисления вам вознаграждения:
- Вознаграждение после успешного платежа: вы получаете свое вознаграждение сразу после успешного платежа. При возврате платежа вы можете вернуть покупателю только ту сумму, которая предназначалась продавцу.
- Вознаграждение при закрытии сделки: вы получаете свое вознаграждение после успешной выплаты при закрытии сделки. При возврате платежа вы можете вернуть покупателю всю сумму платежа, включая ваше вознаграждение.
У сделки есть срок жизни. Это промежуток времени (например, 90 дней), в течение которого нужно принять оплату от покупателя и сделать выплату продавцу. Если к концу этого срока вы не сделаете выплату или возврат, ЮKassa автоматически закроет сделку и вернет оплату покупателю. Минимальная длительность сделки — 1 день, максимальная — 180 дней. Срок жизни устанавливается при подключении Безопасной сделки и распространяется на все сделки вашей интернет-площадки в ЮKassa.
Сделка закрывается автоматически при выполнении определенных условий.
Шаг 1. Создайте сделку: отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности (подойдет любое случайное значение), типом сделки (
safe_deal
— Безопасная сделка) и моментом, когда ЮKassa нужно будет перечислить вознаграждение вашей платформе: после успешной оплаты (payment_succeeded
) или при закрытии сделки (deal_closed
).В параметре
description
вы можете передать уникальную информацию о сделке. Например, идентификатор сделки на стороне вашей площадки, идентификатор покупателя или продавца. В запросе на получение списка сделок вы можете использовать этот параметр для фильтрации нужных вам сделок.Также вы можете передать дополнительные данные, например номер заказа в вашей системе. ЮKassa вернет их без изменений. Данные необходимо передавать в объекте
metadata
в виде набора пар «ключ-значение» (строки в формате UTF-8).Пример запроса на создание сделки
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 вернет созданный объект сделки .
Пример созданного объекта сделки
{ "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 https://api.yookassa.ru/v3/deals/dl-285e5ee7-0022-5000-8000-01516a44b147 \ -X GET \ -u <Идентификатор магазина>:<Секретный ключ>
В ответ на запрос ЮKassa вернет объект сделки в актуальном состоянии.
Пример объекта сделки с пополненным балансом
{ "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 https://api.yookassa.ru/v3/deals?limit=10&status=opened&full_text_search=123554642 \ -X GET -u <Идентификатор магазина>:<Секретный ключ>
В ответ на запрос вернется список сделок . В списке будет информация о сделках, созданных за последние 3 года. Список будет отсортирован по времени создания сделок в порядке убывания.
Пример списка сделок
{ "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 вернет их покупателю).
Пример закрытой сделки
{ "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 }
Есть вопросы или замечания по документации?
Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить.
Для этого оставьте свои контакты и выберите время.
Да, хочу обсудить