/integration/subscriptions/{uuid}/charge-nowПодписка должна иметь действующую привязку и статус active или past_due. Мерчант включён, баланс не заморожен. Подписка, ожидающая подтверждения или отменённая, для нового списания не подходит. Провайдер проверяет доступность операции при запросе.
Запрос
| Поле | Тип | Описание |
|---|---|---|
uuidобязательное | uuid | UUID подписки Cashera в пути запроса. Это не UUID отдельного платежа |
X-Api-Keyобязательное | header | API-ключ владельца подписки |
Idempotency-Keyобязательное | header | Непустой ключ до 200 символов, без управляющих символов. Один новый ключ означает одну новую попытку списания |
Тело запроса не передавайте. Нельзя задать сумму, валюту или дату в этом запросе: списание использует текущие подтверждённые условия. Для смены цены сначала успешно выполните update. Создание платежа с новым external_id здесь не используется.
curl -X POST 'https://api.cashera.cash/api/v1/integration/subscriptions/31dc7faa-c380-4ec7-a258-3202a2211e76/charge-now' \-H "X-Api-Key: $CASHERA_API_KEY" \-H 'Accept: application/json' \-H 'Idempotency-Key: subscription-pro-10428-extra-001'
Ответ без обёртки data, формат описан в объекте транзакции. Суммы приведены в копейках; в примере комиссию 5% оплачивает мерчант. UUID в ответе относится к отдельному платежу, UUID в URL относится к подписке. Сохраните их раздельно. Технический external_id платежа не нужно вычислять или передавать самостоятельно.
Как узнать, что деньги списаны
- Сохраните UUID транзакции из ответа
202 - Дождитесь вебхука transaction.status_updated с этим UUID и статусом
paid - Проверьте подлинность вебхука, связь с подпиской, сумму и валюту
- При недоставке события запросите GET /integration/transactions/{uuid} по UUID платежа или историю списаний
Повтор того же запроса с тем же ключом возвращает тот же платёж с его текущим локальным состоянием. Даже если HTTP-код повторного ответа равен 202, проверяйте поле status: платёж уже мог перейти в финальное состояние. Ни наличие подписки, ни active, ни HTTP 202 не заменяют подтверждённую оплату конкретной транзакции.
Основное расписание сохраняется
charge-now не меняет next_charge_at, interval и interval_count. Если следующее плановое списание назначено на завтра, оно остаётся назначенным на завтра. Не вызывайте этот метод автоматически рядом с плановым списанием без учёта уже оплаченных периодов в вашей системе: это отдельная попытка, а не перенос оплаты.
Защита от повторного списания
- Одна бизнес-операция в вашей системе соответствует одному сохранённому ключу
- При двойном клике, повторе webhook или перезапуске вашего worker используйте тот же ключ
- После тайм-аута,
409или5xxне генерируйте новый ключ - Не запускайте вторую операцию, пока результат первой не установлен
- Новый ключ создавайте только для новой осознанной попытки, когда предыдущий результат известен
Cashera сохраняет операцию и восстанавливает её в фоне. Пока идентификатор платежа не получен, повтор использует исходный ключ; после получения проверяется тот же платёж. Успешное зачисление не повторяется от повторной job или webhook. Эти гарантии не объединяют два запроса с разными ключами в одно списание.
Ошибки
422: ключ отсутствует или некорректен; 404: проверьте UUID и API-ключ; 409: конфликт ключа, статуса или незавершённая операция;400: операция отклонена провайдером;429: уменьшите частоту запросов; 5xx: результат мог остаться неопределённым. Если до 400 уже был тайм-аут, этот отказ не доказывает, что первая попытка не прошла. Следуйте инструкции по восстановлению.