Процесс платежа

В процессе платежа пользователь совершает следующие действия:

выбирает способ оплаты;
вводит данные для оплаты выбранным способом;
при необходимости подтверждает платеж (например, проходит аутентификацию по 3-D Secure или отвечает на смс).

В ЮKassa есть несколько сценариев проведения оплаты. Сценарии различаются в зависимости от того, где пользователь выбирает способ оплаты и вводит платежные данные. В некоторых случаях пользователю нужно дополнительно подтвердить, что он согласен на оплату выбранным способом. Для этого вам будет необходимо реализовать определенный сценарий подтверждения.

Каждый платеж можно проводить в две стадии. Обычно, если пользователь внес оплату, ЮKassa сразу списывает деньги и перечисляет их на ваш расчетный счет. В двухстадийных платежах вы можете регулировать, в какой момент списать деньги и завершить платеж.

Создание платежа

Платеж — основная сущность API ЮKassa для приема платежей.

Чтобы создать платеж, вам нужно передать в запросе:

данные для аутентификации;
ключ идемпотентности (подойдет любое случайное значение);
сумму платежа;
данные для оплаты (зависят от выбранного сценария проведения платежа).

ЮKassa умеет принимать платежи в две стадии, но для простоты вы можете провести обычный платеж (параметр capture со значением true). Это значит, что сразу после оплаты платеж успешно завершится и перейдет в статус succeeded.

Также вы можете передать дополнительные данные, например номер заказа в вашей системе. ЮKassa вернет их без изменений. Данные необходимо передавать в объекте metadata в виде набора пар «ключ-значение».

Пример запроса на создание платежа

cURL

PHP

Python

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"
        }
      }'

В ответ на запрос придет созданный объект платежа.

Пример созданного объекта платежа

JSON

{
  "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 отменит платеж, указав причину expired_on_confirmation. Подробнее о причинах отмены платежа

Сценарии подтверждения

Ю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

PHP

Python

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, а деньги автоматически вернутся пользователю.

В зависимости от способа оплаты у вас есть от 2 часов до 7 дней, чтобы списать деньги. Точное время передается в параметре expires_at. Если вы ничего не сделаете с платежом за этот срок, ЮKassa отменит платеж, указав причину expired_on_capture. Подробнее о причинах отмены платежа

Списание оплаты

Когда платеж перешел в статус waiting_for_capture, вы можете подтвердить платеж — списать оплату полностью или частично.

Полное списание

Доступно для всех способов оплаты, которые поддерживают холдирование. Подробнее о способах оплаты и их возможностях

Чтобы списать всю сумму, отправьте ЮKassa запрос на подтверждение платежа с пустым телом запроса.

Пример запроса на списание всей суммы платежа

cURL

PHP

Python

curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json'

Частичное списание

Доступно для этих способов оплаты: банковская карта, кошелек ЮMoney, SberPay, Mir Pay, T‑Pay, «Покупки в кредит» от СберБанка, платежи через сервис «Плати частями».

Если вы проводите автоплатежи, при сохранении способа оплаты во время платежа можно списать часть суммы для всех способов оплаты, при повторном платеже (рекурренте) — для всех, кроме кошелька ЮMoney.

Чтобы списать только часть суммы, отправьте ЮKassa запрос на подтверждение платежа и передайте в нём в объект amount с нужной суммой. Если сумма списания меньше суммы платежа, остаток автоматически вернется пользователю.

Пример запроса на частичное списание

cURL

PHP

Python

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"
          }
        }'

Отмена платежа

Если вы хотите отказаться от оплаты, отправьте ЮKassa запрос на отмену платежа. Платеж перейдет в статус canceled, и деньги вернутся пользователю В этом случае ЮKassa не будет удерживать комиссию за проведение платежа.

Вы можете отменить только платежи в статусе waiting_for_capture. Если платеж перешел в статус succeeded, вы можете создать возврат.

Пример запроса на отмену платежа

cURL

PHP

Python

curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{

      }'

Жизненный цикл платежа

Жизненный цикл платежа зависит от настроек вашего магазина и параметров, которые вы передадите в запросе на создание платежа. Каждому этапу жизненного цикла соответствует статус платежа.

Статусы платежа

pending — платеж создан и ожидает действий от пользователя. В некоторых случаях платеж может оставаться в этом статусе даже после подтверждения платежа пользователем:

Если вы используете стороннюю онлайн-кассу для работы по 54-ФЗ и сценарий Сначала чек, потом платеж, то платеж может находиться в статусе pending до тех пор, пока онлайн-касса не сообщит об успешной или неуспешной регистрации чека.
Если вы проводите платеж способом «Покупки в кредит» от СберБанка и применяется охлаждение кредита или рассрочки, то платеж будет находиться в статусе pending, пока не закончится период охлаждения (срок указывается в параметре suspended_until) или пока пользователь не откажется от кредита или рассрочки в приложении СберБанка.

Из статуса pending платеж может перейти в succeeded, waiting_for_capture (при двухстадийной оплате) или canceled (если что-то пошло не так).

waiting_for_capture — платеж оплачен, деньги авторизованы и ожидают списания. Из этого статуса платеж может перейти в succeeded (если вы списали оплату) или canceled (если вы отменили платеж или что-то пошло не так).

succeeded — платеж успешно завершен, деньги будут перечислены на ваш расчетный счет в соответствии с вашим договором с ЮKassa. Это финальный и неизменяемый статус.

canceled — платеж отменен. Вы увидите этот статус, если вы отменили платеж самостоятельно, истекло время на принятие платежа или платеж был отклонен ЮKassa или платежным провайдером. Это финальный и неизменяемый статус.

В зависимости от вашего процесса часть статусов может быть пропущена, но их последовательность не меняется.

Чтобы узнать статус платежа, периодически отправляйте запросы, чтобы получить информацию о платеже, или подождите, когда придет уведомление от ЮKassa.

Что почитать еще

Отправка чеков в налоговую

Неуспешные платежи

Входящие уведомления

Тестирование платежей