Order Flow FoxReload: резервация, fulfilment, доставка
Если вы интегрируете FoxReload в масштабе, нужно аккуратно смоделировать состояние заказа на своей стороне: поддержка клиентов, возвраты и сверка — всё зависит от понимания того, что означает каждое состояние и когда происходят переходы. Эта статья проходит по полному order flow FoxReload в том виде, как он реально работает в продакшене.
Пять состояний
Каждый заказ проходит до пяти состояний. Большинство happy-path заказов завершается за 60 секунд.
| Состояние | Значение | Типичная длительность |
|---|---|---|
pending |
Заказ создан, ждёт проверки баланса | <1 с |
reserved |
Сток залочен, FX rate зафиксирован на 15 мин | 0–5 с |
processing |
Fulfilment у поставщика в полёте | 1–60 с |
delivered |
Код/PIN возвращён и подписан | терминальное |
failed |
Резервация или fulfilment не удался | терминальное |
State machine строго однонаправленная — заказ delivered не может вернуться в processing. Возвраты — это отдельный объект (POST /v1/refunds), не меняющий состояние заказа.
1. Pending → reserved
Когда вы вызываете POST /v1/orders с sku, quantity и idempotency_key, FoxReload сначала валидирует ваш баланс и лочит сток у вышестоящего поставщика. FX-курс (для не-USD SKU) фиксируется в этот момент и удерживается 15 минут — достаточно для downstream-ретраев, но не даёт бесплатный re-pricing.
Успешная резервация возвращает HTTP 201 со status: "reserved" и зафиксированным unit_price_usd. Если баланса недостаточно — HTTP 402 insufficient_funds; если SKU нет в наличии — HTTP 409 out_of_stock.
2. Reserved → processing → delivered
Резервация отправляется поставщику в течение ~200 мс. Поставщик возвращает коды либо синхронно (в том же HTTP round-trip, большинство gift card), либо асинхронно (активации eSIM, некоторые региональные PSN-коды — до 60 с).
При успешной доставке FoxReload отправляет вебхук order.delivered:
{
"event": "order.delivered",
"order_id": "ord_8f2c91",
"codes": [
{ "type": "pin", "value": "ENCRYPTED_PAYLOAD", "redeem_url": "..." }
],
"delivered_at": "2026-05-18T10:24:31Z"
}
Значения кодов шифруются at rest с per-order data key — расшифровывайте их на сервере, используя webhook_secret и AES-GCM helper из SDK.
3. Путь failed
Сбои делятся на три категории, каждая со своим кодом failure_reason:
supplier_timeout— upstream не ответил за 60 с. Автоматический возврат на баланс в течение 10 минут.invalid_region— несовпадение региона покупателя (редко; обычно баг в роутинге на вашей стороне).stock_revoked— поставщик отозвал сток между резервацией и fulfilment.
Все failed заказы автоматически возвращают средства на ваш аккаунт. На вашей стороне ничего делать не нужно, кроме обновления UI и уведомления покупателя.
Хотите увидеть полную диаграмму состояний и попробовать sample webhook payload'ы в песочнице? Зарегистрируйтесь на foxreload.com — sandbox-ключи бесплатны и позволяют симулировать каждый переход, включая искусственные сбои, до выхода в live.