В процессе платежа пользователь совершает следующие действия:
- выбирает способ оплаты;
- вводит данные для оплаты выбранным способом;
- при необходимости подтверждает платеж (например, проходит аутентификацию по 3-D Secure или отвечает на смс).
В ЮKassa есть несколько сценариев проведения оплаты. Сценарии различаются в зависимости от того, где пользователь выбирает способ оплаты и вводит платежные данные. В некоторых случаях пользователю нужно дополнительно подтвердить, что он согласен на оплату выбранным способом. Для этого вам будет необходимо реализовать определенный сценарий подтверждения.
Каждый платеж можно проводить в две стадии. Обычно, если пользователь внес оплату, ЮKassa сразу списывает деньги и перечисляет их на ваш расчетный счет. В двухстадийных платежах вы можете регулировать, в какой момент списать деньги и завершить платеж.
Платеж
— основная сущность API ЮKassa для приема платежей.
Чтобы создать платеж, вам нужно передать в запросе :
- данные для аутентификации;
- ключ идемпотентности (подойдет любое случайное значение);
- сумму платежа;
- данные для оплаты (зависят от выбранного сценария проведения платежа).
ЮKassa умеет принимать платежи в две стадии, но для простоты вы можете провести обычный платеж (параметр
capture
со значением true
). Это значит, что сразу после оплаты платеж успешно завершится и перейдет в статус succeeded
.Также вы можете передать дополнительные данные, например номер заказа в вашей системе. ЮKassa вернет их без изменений. Данные необходимо передавать в объекте
metadata
в виде набора пар «ключ-значение».Пример запроса на создание платежа
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "100.00", "currency": "RUB" }, "capture": true, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "description": "Заказ №37", "metadata": { "order_id": "37" } }'
В ответ на запрос придет созданный объект Платежа .
Пример созданного объекта платежа
{ "id": "2419a771-000f-5000-9000-1edaf29243f2", "status": "pending", "paid": false, "amount": { "value": "100.00", "currency": "RUB" }, "confirmation": { "type": "redirect", "confirmation_url": "https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=2419a771-000f-5000-9000-1edaf29243f2" }, "created_at": "2019-03-12T11:10:41.802Z", "description": "Заказ №37", "metadata": { "order_id": "37" }, "recipient": { "account_id": "100500", "gateway_id": "100700" }, "refundable": false, "test": false }
Для большинства способов оплаты после создания платежа вам нужно получить согласие от пользователя, что он готов заплатить. Для этого пользователю нужно дополнительно что-то сделать, например пройти 3-D Secure при оплате банковской картой, подтвердить оплату в платежном сервисе партнера или оплатить счет в интернет-банке.
Если от пользователя нужно получить подтверждение, созданный платеж сначала перейдет в статус
pending
. В следующие статусы (succeeded
или waiting_for_capture
) платеж перейдет, только если пользователь согласится внести оплату.Если подтверждение не требуется, платеж сразу перейдет в статус
succeeded
или waiting_for_capture
(если вы проводите платеж в две стадии).Если пользователь передумает платить или что-то пойдет не так (например, на счете не окажется нужной суммы), платеж отменится и перейдет в статус
canceled
.ЮKassa поддерживает несколько сценариев подтверждения: Redirect, External, QR-код, Embedded и Mobile application.
Сценарий подтверждения Redirect: пользователю необходимо что-то сделать на странице ЮKassa или ее партнера (например, ввести данные банковской карты или пройти аутентификацию по 3-D Secure). Вам нужно перенаправить пользователя на
confirmation_url
, полученный в платеже . При успешной оплате (и если что-то пойдет не так) ЮKassa вернет пользователя на return_url
, который вы отправите в запросе на создание платежа .Сценарий подтверждения External: для подтверждения платежа пользователю необходимо совершить действия во внешней системе (например, ответить на смс). От вас требуется только сообщить пользователю о дальнейших шагах.
Сценарий подтверждения QR-код: для подтверждения платежа пользователю необходимо просканировать QR-код. От вас требуется сгенерировать QR-код, используя любой доступный инструмент, и отобразить его на странице оплаты.
Сценарий подтверждения Embedded: действия, необходимые для подтверждения платежа, будут зависеть от способа оплаты, который пользователь выберет в виджете ЮKassa. Подтверждение от пользователя получит ЮKassa — вам необходимо только встроить виджет к себе на страницу.
Сценарий подтверждения Mobile application: для подтверждения платежа пользователю необходимо совершить действия в мобильном приложении (например, в приложении интернет-банка). Вам нужно перенаправить пользователя на
confirmation_url
, полученный в платеже . При успешной оплате (и если что-то пойдет не так) ЮKassa вернет пользователя на return_url
, который вы отправите в запросе на создание платежа . Подтвердить платеж по этому сценарию можно только на мобильном устройстве (из мобильного приложения или с мобильной версии сайта).Один способ оплаты может поддерживать несколько сценариев подтверждения. Особенности подтверждения платежа при оплате разными способами описаны в разделе Способы оплаты.
Вы можете проводить платежи в две стадии:
- Холдирование (предавторизация): пользователь вносит оплату, и деньги замораживаются — например, на его банковской карте или в электронном кошельке (зависит от способа, которым он платит).
- Списание: замороженные деньги списываются по вашему запросу.
Чтобы создать двухстадийный платеж, передайте в запросе на создание платежа параметр
capture
со значением false
.Пример запроса на создание двухстадийного платежа
curl https://api.yookassa.ru/v3/payments \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "100.00", "currency": "RUB" }, "capture": false, "confirmation": { "type": "redirect", "return_url": "https://www.example.com/return_url" }, "description": "Заказ №37", "metadata": { "order_id": "37" } }'
Как только деньги будут авторизованы, платеж перейдет в статус
waiting_for_capture
. Этот статус означает, что вам нужно принять решение: списать оплату или отменить платеж. Если вы не сделали это за определенное время, платеж перейдет в статус canceled
, а деньги автоматически вернутся пользователю.В зависимости от способа оплаты у вас есть 6 часов или 7 дней, чтобы списать деньги. Точное время передается в параметре
expires_at
. Если вы ничего не сделаете с платежом за этот срок, ЮKassa отменит платеж, указав причину expired_on_capture
. Подробнее о причинах отмены платежаЧтобы принять оплату, используйте метод capture . По умолчанию списывается вся сумма платежа. Чтобы списать только часть, передайте в запросе объект
amount
с нужной суммой. Если сумма списания меньше суммы платежа, остаток автоматически вернется пользователю.Пример запроса на списание всей суммы платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json'
Пример запроса на частичное списание
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "value": "2.00", "currency": "RUB" } }'
Если вы хотите отказаться от оплаты, то отмените платеж с помощью метода cancel . Платеж перейдет в статус
canceled
, и деньги вернутся пользователю. В этом случае ЮKassa не будет удерживать комиссию за проведение платежа.Вы можете отменить только платежи в статусе
waiting_for_capture
. Если платеж перешел в статус succeeded
, вы можете создать возврат.Пример запроса на отмену платежа
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \ -X POST \ -u <Идентификатор магазина>:<Секретный ключ> \ -H 'Idempotence-Key: <Ключ идемпотентности>' \ -H 'Content-Type: application/json' \ -d '{ }'
Жизненный цикл платежа зависит от настроек вашего магазина и параметров, которые вы передадите в запросе на создание платежа . Каждому этапу жизненного цикла соответствует статус платежа .
pending
— платеж создан и ожидает действий от пользователя. Если вы используете решение ЮKassa для работы по 54-ФЗ и сценарий Сначала чек, потом платеж, то платеж может находиться в статусе
pending
до тех пор, пока онлайн-касса не сообщит об успешной или неуспешной регистрации чека. Из статуса pending
платеж может перейти в succeeded
, waiting_for_capture
(при двухстадийной оплате) или canceled
(если что-то пошло не так).waiting_for_capture
— платеж оплачен, деньги авторизованы и ожидают списания. Из этого статуса платеж может перейти в
succeeded
(если вы списали оплату) или canceled
(если вы отменили платеж или что-то пошло не так).succeeded
— платеж успешно завершен, деньги будут перечислены на ваш расчетный счет в соответствии с вашим договором с ЮKassa. Это финальный и неизменяемый статус.
canceled
— платеж отменен. Вы увидите этот статус, если вы отменили платеж самостоятельно, истекло время на принятие платежа или платеж был отклонен ЮKassa или платежным провайдером. Это финальный и неизменяемый статус.
В зависимости от вашего процесса часть статусов может быть пропущена, но их последовательность не меняется.
Чтобы узнать статус платежа, периодически отправляйте запросы, чтобы получить информацию о платеже , или подождите, когда придет уведомление от ЮKassa.
Отправка чеков в налоговуюНеуспешные платежиВходящие уведомленияТестирование платежей