Общая платёжная форма

Для общей формы используется тот же endpoint, что и для обычного платежа. Единственное отличие - полеpayment_method необходимо полностью исключить из JSON. Покупатель выберет способ оплаты на странице по адресу payment_url.

Как работает flow

1. Ваш backend создаёт платёж без payment_method
2. Cashera возвращает checkout-сессию, её UUID и payment_url
3. Вы перенаправляете покупателя на URL из ответа
4. Покупатель выбирает один из доступных способов оплаты
5. Checkout-сессия становится обычной транзакцией с теми же uuid и external_id
6. Дальше действуют стандартные статусы и вебхуки транзакции

Перед подключением

• У мерчанта должен быть включён хотя бы один одноразовый метод для общей формы
• Должен быть настроен HTTPS callback_url - в запросе или в настройках мерчанта
• API-запрос выполняется только с backend-сервера с заголовком X-Api-Key
• Суммы передаются целыми числами в минорных единицах

Параметры запроса

Создание формы

curl -X POST https://api.cashera.cash/api/v1/integration/transactions \
  -H "X-Api-Key: $CASHERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "RUB",
    "external_id": "order-2026-000123",
    "description": "Оплата заказа №000123",
    "metadata": { "order_id": "000123" },
    "callback_url": "https://merchant.example/webhooks/cashera",
    "success_url": "https://merchant.example/payment/success",
    "fail_url": "https://merchant.example/payment/fail"
  }'

Ответ до выбора метода

API отвечает 201 Created. Финансовые поля имеют значение null, пока способ оплаты не выбран и транзакция не создана.

{
  "uuid": "0195f0c1-e0a2-7221-9330-7d597e7141f7",
  "type": "deposit",
  "amount": 15000,
  "gross_amount": null,
  "net_amount": null,
  "fee_amount": null,
  "currency": "RUB",
  "settlement_currency": null,
  "settlement_amount": null,
  "payment_method": null,
  "status": "pending",
  "external_id": "order-2026-000123",
  "description": "Оплата заказа №000123",
  "metadata": { "order_id": "000123" },
  "payment_url": "https://pay.cashera.cash/0195f0c1-e0a2-7221-9330-7d597e7141f7",
  "expires_at": "2026-08-28T15:35:00+00:00",
  "created_at": "2026-08-28T15:00:00+00:00",
  "updated_at": "2026-08-28T15:00:00+00:00",
  "selection_required": true,
  "available_payment_methods": [
    { "code": "sbp", "title": "СБП" },
    { "code": "card", "title": "Банковская карта" }
  ]
}

Перенаправление покупателя

Используйте payment_url из ответа без изменения домена или пути. URL может учитывать индивидуальный checkout-домен вашего мерчанта.

header('Location: ' . $checkout['payment_url']);
exit;

Статус общей формы

До и после выбора метода используйте те же status endpoint'ы:

• GET /integration/transactions/{uuid}
• GET /integration/transactions/by-external-id/{externalId}

До выбора метода ответ содержит payment_method: null и selection_required: true. После выбора возвращается обычная транзакция с тем же UUID и заполненным payment_method.

Идемпотентность

• Точный повтор возвращает ту же checkout-сессию и тот же UUID
• После выбора метода точный повтор возвращает уже созданную транзакцию
• Изменение суммы, валюты, описания, metadata или URL при том же external_id вернёт 409
• Нельзя при повторе добавлять payment_method или переключаться с прямого платежа на общую форму

При timeout повторите исходный JSON без изменений или получите состояние по external_id. Подробнее - идемпотентность.

Ошибки

{
  "message": "No payment methods are available on checkout."
}