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

pending ──▶ authorized ──▶ succeeded ──▶ partially_refunded ──▶ refunded
   │  (холд, capture_mode=manual)   │ (capture)
   ├──▶ succeeded (карта auto / СБП)  └──▶ canceled (cancel холда)
   ├──▶ canceled  (отказ банка, reason_code + message в поле decline;
   │               отмена магазином до оплаты, cancel_reason = merchant_canceled)
   ├──▶ expired   (истёк expires_at, по умолчанию — «Срок оплаты» из настроек магазина)
   └──▶ on_hold   (заказ заблокирован правилами ПЦ — ждём решения Оператора)

Терминальные статусы: succeeded, canceled, expired, refunded, partially_refunded. Итог платежа узнавайте по вебхуку или запросом GET /payments/{id}, а не по возврату плательщика на return_url.

Платежи

POST /payments — создать платёж

curl -X POST https://platezhka.online/api/v1/payments \\
  -H "Authorization: Bearer sk_test_XXXX" -H "Idempotency-Key: order-1001" -H "Content-Type: application/json" \\
  -d '{"amount": 100000, "order_id": "1001", "description": "Заказ 1001", "return_url": "https://shop.example/orders/1001",
       "customer": {"id": "user-42", "email": "buyer@example.com"}, "items": [{"text": "Товар", "price": 100000, "quantity": 1}]}'

Ответ 201 — объект платежа (все поля). Передайте id виджету на странице оформления заказа или перенаправьте покупателя на payment_url:

{
  "id": "pay_3kZ1x9QmT0aBcDeFgHiJkL",
  "object": "payment",
  "shop_id": "723612",
  "mode": "live",
  "test": false,
  "status": "pending",
  "amount": 100000,
  "currency": "RUB",
  "captured_amount": 0,
  "refunded_amount": 0,
  "order_id": "1001",
  "description": "Заказ 1001",
  "capture_mode": "auto",
  "method": null,
  "confirmation": {
    "type": "hosted"
  },
  "payment_url": "https://platezhka.online/pay/pay_3kZ1x9QmT0aBcDeFgHiJkL",
  "return_url": "https://shop.example/orders/1001",
  "customer": {
    "id": "user-42",
    "email": "buyer@example.com"
  },
  "items": [
    {
      "itemId": 1,
      "text": "Товар",
      "price": 100000,
      "quantity": 1
    }
  ],
  "metadata": {},
  "source": "api",
  "receipt_status": null,
  "paygine_order_id": 3504676,
  "expires_at": "2026-09-22T13:00:00+03:00",
  "created_at": "2026-09-22T12:00:00+03:00"
}

Номер заказа и покупатель

order_id — номер заказа в вашей системе. Он возвращается в платеже и во всех вебхуках платежа, по нему работает поиск в кабинете и фильтр GET /payments?order_id=. Уникальность не требуется: на один заказ можно создать несколько платежей (например, после истечения срока первого). От повторного создания при обрыве связи защищает заголовок Idempotency-Key. Для произвольных данных остаётся metadata.

customer.id — идентификатор покупателя у вас; фильтр GET /payments?customer_id=.

Виджет, ссылка на оплату и возврат в магазин

• Основной способ — виджет на вашей странице: QR СБП первым экраном, карта — на форме ПЦ внутри виджета. Виджету нужен только id платежа.
• payment_url — тот же виджет на нашей странице: для писем, мессенджеров и сайтов без JavaScript. method задаёт, что показать первым: sbp — QR (по умолчанию), card — сразу форму карты.
• confirmation: {"type": "redirect"} с method: "card": payment_url ведёт прямо на форму ввода карты ПЦ, минуя виджет.
• Email и телефон для чека берём из customer; в виджете их не спрашиваем.
• После оплаты покупатель автоматически возвращается на return_url через 10 секунд (в виджете — если не передан redirect: false); к адресу добавляется payment_id=<id>. По этому параметру запросите GET /payments/{id}: сам возврат не подтверждает оплату.

GET /payments/{id} — получить платёж

GET /payments — список

Курсорная пагинация: starting_after — id последнего полученного платежа. Ответ: {object: "list", data: [...], has_more: true}.

POST /payments/{id}/capture — списать холд

Только для status = authorized. Тело {"amount": 80000} — необязательно, для частичного списания (не больше суммы холда). Внимание: при частичном списании чек на изменённую сумму требует согласования с Оператором ПЦ; платёж помечается предупреждением.

POST /payments/{id}/cancel — отменить платёж

Для authorized — отмена холда, всегда на полную сумму: деньги разблокируются на карте.

Для pending — закрытие неоплаченного платежа, например при отмене заказа: страница оплаты перестаёт работать, платёж переходит в canceled с cancel_reason = merchant_canceled, приходит событие payment.canceled. Если покупатель в этот момент уже вводил карту и успел оплатить, платёж перейдёт в succeeded (или authorized) с соответствующим событием — верните деньги запросом POST /refunds или отмените холд.