Процесс платежа
В процессе платежа пользователь совершает следующие действия:
  1. выбирает способ оплаты;
  2. вводит данные для оплаты выбранным способом;
  3. при необходимости подтверждает платеж (например, проходит аутентификацию по 3-D Secure или отвечает на смс).
В Яндекс.Кассе есть несколько сценариев проведения оплаты. Сценарии различаются в зависимости от того, где пользователь выбирает способ оплаты и вводит платежные данные. В некоторых случаях пользователю нужно дополнительно подтвердить, что он согласен на оплату выбранным способом. Для этого вам будет необходимо реализовать определенный сценарий подтверждения.
Каждый платеж можно проводить в две стадии. Обычно, если пользователь внес оплату, Яндекс.Касса сразу списывает деньги и перечисляет их на ваш расчетный счет. В двухстадийных платежах вы можете регулировать, в какой момент списать деньги и завершить платеж.
Создание платежа
Платеж 
— основная сущность API Яндекс.Кассы для приема платежей.
Чтобы создать платеж, вам нужно передать в запросе :
Яндекс.Касса умеет принимать платежи в две стадии, но для простоты вы можете провести обычный платеж (параметр
capture
со значением
true
). Это значит, что сразу после оплаты платеж успешно завершится и перейдет в статус
succeeded
.
Также вы можете передать дополнительные данные, например, номер заказа в вашей системе. Яндекс.Касса вернет их без изменений. Данные необходимо передавать в объекте
metadata
в виде набора пар «ключ-значение».
Пример запроса на создание платежа
cURL
PHP
Python
curl https://payment.yandex.net/api/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.merchant-website.com/return_url"
        },
        "description": "Заказ №1",
        "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://money.yandex.ru/api-pages/v2/payment-confirm/epl?orderId=2419a771-000f-5000-9000-1edaf29243f2"
  },
  "created_at": "2019-03-12T11:10:41.802Z",
  "description": "Заказ №1",
  "metadata": {
    "order_id": "37"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "test": false
}
Подтверждение платежа пользователем
Для большинства способов оплаты после создания платежа вам нужно получить согласие от пользователя, что он готов заплатить. Для этого пользователю нужно дополнительно что-то сделать, например, пройти 3-D Secure при оплате банковской картой, подтвердить оплату в платежном сервисе партнера или оплатить счет в интернет-банке.
Если от пользователя нужно получить подтверждение, созданный платеж  сначала перейдет в статус
pending
. В следующие статусы (
succeeded
или
waiting_for_capture
) платеж перейдет, только если пользователь согласится внести оплату.
Если подтверждение не требуется (например, при оплате через Apple Pay), платеж сразу перейдет в статус
succeeded
или
waiting_for_capture
(если вы проводите платеж в две стадии).
Если пользователь передумает платить или что-то пойдет не так (например, на счете не окажется нужной суммы), платеж отменится и перейдет в статус
canceled
.
Сценарии подтверждения
В Яндекс.Кассе поддерживаются два сценария подтверждения: Redirect и External.
Сценарий подтверждения Redirect: пользователю необходимо что-то сделать на странице Яндекс.Кассы или ее партнера (например, ввести данные банковской карты или пройти аутентификацию по 3-D Secure). Вам нужно перенаправить пользователя на
confirmation_url
, полученный в платеже . При успешной оплате (и если что-то пойдет не так) Яндекс.Касса вернет пользователя на
return_url
, который вы отправите в запросе на создание платежа .
Сценарий подтверждения External: для продолжения пользователю необходимо совершить действия во внешней системе (например, ответить на смс). От вас требуется только сообщить пользователю о дальнейших шагах.
Один способ оплаты может поддерживать несколько сценариев подтверждения. Особенности подтверждения платежа при оплате разными способами описаны в разделе Способы оплаты.
Двухстадийные платежи
Вы можете проводить платежи в две стадии:
  1. Холдирование (предавторизация): пользователь вносит оплату, и деньги замораживаются — например, на его банковской карте или в электронном кошельке (зависит от способа, которым он платит).
  2. Списание: замороженные деньги списываются по вашему запросу.
Чтобы создать двухстадийный платеж, передайте в запросе на создание платежа  параметр
capture
со значением
false
.
Пример запроса на создание двухстадийного платежа
cURL
PHP
Python
curl https://payment.yandex.net/api/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.merchant-website.com/return_url"
        },
        "description": "Заказ №1",
        "metadata": {
          "order_id": "37"
        }
      }'
Холдирование
Как только деньги будут авторизованы, платеж перейдет в статус
waiting_for_capture
. Этот статус означает, что вам нужно принять решение: списать оплату или отменить платеж. Если вы не сделали это за определенное время, платеж перейдет в статус
canceled
, а деньги автоматически вернутся пользователю.
В зависимости от способа оплаты у вас есть 6 часов или 7 дней, чтобы списать деньги. Точное время передается в параметре
expires_at
.
Списание оплаты
Чтобы принять оплату, используйте метод capture . По умолчанию списывается вся сумма платежа. Чтобы списать только часть, передайте в запросе объект
amount
с нужной суммой. Если сумма списания меньше суммы платежа, остаток автоматически вернется пользователю.
Частичное списание доступно только при оплате банковской картой и из кошелька в Яндекс.Деньгах. Для остальных способов оплаты можно списать только всю сумму целиком.
Пример запроса на списание всей суммы платежа
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json'
Пример запроса на частичное списание
cURL
PHP
Python
curl https://payment.yandex.net/api/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
, и деньги вернутся пользователю. В этом случае Яндекс.Касса не будет удерживать комиссию за проведение платежа.
Вы можете отменить только платежи в статусе
waiting_for_capture
. Если платеж перешел в статус
succeeded
, вы можете создать возврат .
Пример запроса на отмену платежа
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments/{payment_id}/cancel \
    -X POST \
    -u <Идентификатор магазина>:<Секретный ключ> \
    -H 'Idempotence-Key: <Ключ идемпотентности>' \
    -H 'Content-Type: application/json' \
    -d '{

        }'
Жизненный цикл платежа
Жизненный цикл платежа зависит от настроек вашего магазина и параметров, которые вы передадите в запросе на создание платежа . Каждому этапу жизненного цикла соответствует статус платежа .
Статусы платежа
pending
— платеж создан и ожидает действий от пользователя. Из этого статуса платеж может перейти в
succeeded
,
waiting_for_capture
(при двухстадийной оплате) или
canceled
(если что-то пошло не так).
waiting_for_capture
— платеж оплачен, деньги авторизованы и ожидают списания. Из этого статуса платеж может перейти в
succeeded
(если вы списали оплату) или
canceled
(если вы отменили платеж или что-то пошло не так).
succeeded
— платеж успешно завершен, деньги будут перечислены на ваш расчетный счет в соответствии с вашим договором с Яндекс.Кассой. Это финальный и неизменяемый статус.
canceled
— платеж отменен. Вы увидите этот статус, если вы отменили платеж самостоятельно, истекло время на принятие платежа или платеж был отклонен Яндекс.Кассой или платежным провайдером. Это финальный и неизменяемый статус.
В зависимости от вашего процесса часть статусов может быть пропущена, но их последовательность не меняется.
Что почитать еще
Оплата по 54-ФЗНеуспешные платежиВходящие уведомленияТестирование