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