Выставление счетов: прием платежей — Прием платежей по API ЮKassa

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

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

В этой статье описано, как выставить счет по API и принять платеж.

Общий сценарий выставления счета

Сценарий выставления счета

Пользователь подтверждает детали заказа.
Вы создаете счет — отправляете ЮKassa POST-запрос с данными платежа, корзины заказа и сроком действия счета.
ЮKassa возвращает вам созданный объект счета в статусе pending со ссылкой на счет (параметр url в объекте счета).
Вы отправляете полученную ссылку пользователю любым удобным способом
Пользователь переходит по ссылке на страницу счета. Там он видит корзину заказа, срок действия счета и кнопку К оплате с суммой платежа.
Пользователь переходит к оплате.
ЮKassa создает платеж по выставленному счету.
ЮKassa на платежной форме отображает способы оплаты, доступные для этого платежа.
Пользователь выбирает способ оплаты, вводит данные и подтверждает платеж.
Вы можете получить информацию об оплате выставленного счета двумя способами:
- Через платеж: если у вас настроены уведомления, ЮKassa присылает уведомление о переходе платежа в статус succeeded (для платежей в одну стадию) или в статус waiting_for_capture (для платежей в две стадии). Так вы получите объект платежа в актуальном статусе.
- Через счет: вы отправляете ЮKassa GET-запрос на получение информации о счете . Так вы получите объект счета в актуальном статусе.
При необходимости, вы сообщаете пользователю результат оплаты счета.

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

Шаг 1. Создайте счет . Передайте в запросе следующие данные:

объект payment_data с данными платежа и, при необходимости, данными для чека;
в объекте payment_data передайте параметр capture со значением true, если хотите провести платеж в одну стадию, и со значением false, если вам нужны платежи в две стадии;
массив cart с корзиной заказа, которую пользователь увидит на странице счета;
объект delivery_method_data, который указывает на способ отправки ссылки пользователю. В него входит параметр type, единственное возможное значение — self (самостоятельная отправка ссылки на счет);
параметр expires_at с датой и временем, до которого счет может быть оплачен.

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

cURL
PHP
Python
  curl https://api.yookassa.ru/v3/invoices \
    -X POST \
    -u <Shop ID>:<Secret Key> \
    -H 'Idempotence-Key: <Idempotence Key>' \
    -H 'Content-Type: application/json' \
    -d '{
          "payment_data": {
            "amount": {
              "value": "10.00",
              "currency": "RUB"
            },
            "capture": true,
            "description": "Order No. 37",
            "metadata": {
              "order_id": "37"
            }
          },
          "cart": [
            {
              "description": "Product number 12345",
              "price": {
                "value": "9.00",
                "currency": "RUB"
              },
              "discount_price": {
                "value": "7.00",
                "currency": "RUB"
              },
              "quantity": 1.000
            },
            {
              "description": "Product number 67890",
              "price": {
                "value": "1.00",
                "currency": "RUB"
              },
              "quantity": 3.000
            }
          ],
          "delivery_method_data": {
            "type": "self"
          },
          "locale": "ru_RU",
          "expires_at": "2024-10-18T10:51:18.139Z",
          "description": "Invoice for order No. 37",
          "metadata": {
            "order_id": "37"
          }
       }'

В ответ на запрос ЮKassa вернет созданный объект счета .

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

JSON
{
  "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "status": "pending",
  "cart": [
    {
      "description": "Product number 12345",
      "price": {
        "value": "9.00",
        "currency": "RUB"
      },
      "discount_price": {
        "value": "7.00",
        "currency": "RUB"
      },
      "quantity": 1.000
    },
    {
      "description": "Товар арт. 67890",
      "price": {
        "value": "1.00",
        "currency": "RUB"
      },
      "quantity": 3.000
    }
  ],
  "delivery_method": {
    "type": "self",
    "url": "https://yookassa.ru/my/i/Zqncq0lhxSqo/a"
  },
  "created_at": "2024-10-01T11:37:15.137Z",
  "expires_at": "2024-10-18T10:51:18.139Z",
  "description": "Invoice for order No. 37",
  "metadata": {
    "order_id": "37"
  }
}

Шаг 2. Отправьте пользователю ссылку на счет любым удобным способом: она вернется в параметре delivery_method.url в объекте счета . При переходе по этой ссылке пользователь попадет на страницу счета.

Шаг 3. Дождитесь успешного платежа по счету. Вы можете узнать о платеже и его статусе двумя способами:

Подождите, когда придет уведомление от ЮKassa по платежу. В объекте платежа , помимо прочих данных, будет объект invoice_details с идентификатором счета — так вы сможете сопоставить платеж с конкретным счетом.
Периодически отправляйте GET-запросы для получения информации о счете — в ответ на запрос ЮKassa вернет объект счета . Если пользователь подтвердил оплату, то в объект счета будет включен объект payment_details с идентификатором и статусом платежа. При необходимости отправьте GET-запрос с идентификатором платежа, чтобы получить расширенную информацию о нём .

Пример объекта счета в статусе succeeded с объектом payment_details

JSON
{
  "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "status": "succeeded",
  "cart": [
    {
      "description": "Product number 12345",
      "price": {
        "value": "9.00",
        "currency": "RUB"
      },
      "discount_price": {
        "value": "7.00",
        "currency": "RUB"
      },
      "quantity": 1.000
    },
    {
      "description": "Товар арт. 67890",
      "price": {
        "value": "1.00",
        "currency": "RUB"
      },
      "quantity": 3.000
    }
  ],
  "payment_details": {
    "id": "22e18a2f-000f-5000-a000-1db6312b7767",
    "status": "succeeded"
  },
  "created_at": "2024-10-01T11:37:15.137Z",
  "description": "Invoice for order No. 37",
  "metadata": {
    "order_id": "37"
  }
}

Если вы принимаете платежи в одну стадию, то это финальный шаг — платеж и счет в статусе succeeded, значит счет оплачен.

Шаг 4. Если вы принимаете платежи в две стадии, то после подтверждения пользователем платеж перейдет в статус waiting_for_capture. Этот статус означает, что вам нужно принять решение: списать оплату или отменить платеж.

Отправьте соответствующий запрос с идентификатором платежа. Подробнее о том, как получить идентификатор платежа

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
    -X POST \
    -u <Shop ID>:<Secret Key> \
    -H 'Idempotence-Key: <Idempotence Key>' \
    -H 'Content-Type: application/json' \
    -d '{
          "amount": {
            "value": "2.00",
            "currency": "RUB"
          }
        }'

При успешном подтверждении платеж перейдет в статус succeeded. Счет также останется в статусе succeeded и будет считаться оплаченным.

При отмене платеж перейдет в статус canceled. Счет также отменится, перейдет в статус canceled. Оплатить счет уже не получится, для приема платежа нужно будет создать новый счет.

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

Готово!

Идентификатор платежа: как получить и зачем он нужен

Когда на странице счета пользователь перейдет к оплате, ЮKassa автоматически создаст объект платежа и перенаправит пользователя на платежную форму. У каждого объекта платежа есть идентификатор. Например, 22e18a2f-000f-5000-a000-1db6312b7767.

Он потребуется вам для следующих действий:

отмена или списание оплаты по платежу в две стадии;
возврат платежа;
сохранение способа оплаты для автоплатежей;
отправка чеков с использованием решений ЮKassa для работы по 54-ФЗ;
получение информации о платеже .

Как получить идентификатор платежа

В объекте платежа

Если дожидаетесь уведомления от ЮKassa по платежу, то идентификатор получите в значении параметра object.id в объекте платежа . Кроме того, в объекте платежа вернется идентификатор счета в параметре invoice_details.id — так вы сможете сопоставить платеж и счет.

Пример тела уведомления payment.waiting_for_capture

JSON
{
  "type": "notification",
  "event": "payment.waiting_for_capture",
  "object": {
    "id": "22e18a2f-000f-5000-a000-1db6312b7767",
    "status": "succeeded",
    "paid": true,
    "amount": {
      "value": "10.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000",
      "three_d_secure": {
        "applied": true
      }
    },
    "captured_at": "2024-10-02T12:46:18.139Z",
    "created_at": "2024-10-02T12:45:15.137Z",
    "description": "Order No. 37",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22e18a2f-000f-5000-a000-1db6312b7767",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2022",
        "card_type": "Mir",
        "card_product": {
          "code": "MCP",
          "name": "MIR Privilege"
        },
        "issuer_country": "RU",
        "issuer_name": "Sberbank"
      },
      "title": "Bank card *4444"
    },
    "refundable": true,
    "refunded_amount": {
      "value": "0.00",
      "currency": "RUB"
    },
    "recipient": {
      "account_id": "100500",
      "gateway_id": "100700"
    },
    "test": false,
    "invoice_details": {
      "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54"
    }
  }
}

В объекте счета

Если отправляете GET-запросы, чтобы получить информацию о счете , то идентификатор вернется в значении параметра payment_details.id в объекте счета , но только при условии, что пользователь уже подтвердил платеж. С идентификатором платежа вы сможете отправить ещё один GET-запрос, чтобы получить объект платежа с расширенной информацией о нём (способ оплаты, дата и время оплаты и т.д.).

Если платежа не было или пользователь его еще не подтвердил, то объект счета вернется без объекта payment_details.

Пример объекта счета в статусе succeeded

JSON
{
  "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "status": "succeeded",
  "cart": [
    {
      "description": "Product number 12345",
      "price": {
        "value": "9.00",
        "currency": "RUB"
      },
      "discount_price": {
        "value": "7.00",
        "currency": "RUB"
      },
      "quantity": 1.000
    },
    {
      "description": "Товар арт. 67890",
      "price": {
        "value": "1.00",
        "currency": "RUB"
      },
      "quantity": 3.000
    }
  ],
  "payment_details": {
    "id": "22e18a2f-000f-5000-a000-1db6312b7767",
    "status": "waiting_for_capture"
  },
  "created_at": "2024-10-01T11:37:15.137Z",
  "description": "Invoice for order No. 37",
  "metadata": {
    "order_id": "37"
  }
}

Информирование об оплате счета

Вы можете узнавать об оплаченных счетах несколькими способами: в личном кабинете, по электронной почте, по API или с помощью уведомлений по платежу от ЮKassa.

В личном кабинете

В личном кабинете вы можете найти информацию о статусе в разделе Счета клиентам. Если вы принимаете платежи в две стадии, в личном кабинете счет будет в статусе Оплачен, даже если вы ещё не приняли решение об отмене или списании оплаты по платежу.

По электронной почте

По электронной почте вы можете получить письмо об оплате счета. Для этого включите уведомления о счетах в личном кабинете.

По API

По API вы можете периодически отправлять запросы, чтобы получить объект счета . В нём содержится статус счета, срок действия, корзина заказа и другие данные. Этот способ подойдет только для счетов, выставленных по API. Если вы выставили счет в личном кабинете или через Telegram-бота, то получить информацию о нём по API не получится.

Уведомления по платежу от ЮKassa

Вы можете дожидаться уведомления по платежу от ЮKassa. В теле уведомления вы получите объект платежа , в котором, помимо прочих данных, содержится объект invoice_details с идентификатором выставленного счета. С его помощью вы можете сопоставить платеж с конкретным счетом. Если объект платежа в статусе succeedeed, то счет оплачен.