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

Заголовок Idempotency-Key обязателен для запросов, создающих операции с деньгами: создание платежа и возврат. Значение выбираете вы — например, идентификатор заказа в вашей системе.

Правила

• Повтор с тем же ключом и тем же телом вернёт сохранённый ответ. Операция не выполнится второй раз.
• Тот же ключ с другим телом — ошибка 409. Это защита от случайного переиспользования: иначе платёж на другую сумму тихо вернул бы результат старого.
• Параллельный запрос с тем же ключом — тоже 409: первый ещё выполняется.
• Если операция не удалась, ключ освобождается — можно повторить с ним же.

curl -X POST https://api.assalam.uz/subscribe/v1/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1024" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000000, "card": "cmsr…"}'

{
  "id": "cmsr1a2b",
  "amount": 5000000,
  "status": "REQUIRES_PAYMENT"
}

{
  "message": "Idempotency-Key уже использован с другим телом запроса",
  "error": "Conflict",
  "statusCode": 409
}

Как выбирать ключ

Ключ должен быть привязан к намерению, а не к попытке. Хорошо: order-1024, policy-5567-payment. Плохо: случайная строка на каждый вызов — тогда повтор после обрыва создаст второй платёж.

Минимальная длина — 8 символов.

Дальше по теме