Skip to main content
A redemption progresses through a series of states that describe its lifecycle, from creation through to a final outcome.
  • draft: draft: the redemption has been recorded but has not yet reached a final outcome.
  • confirmed: the redemption completed successfully and the requested amount was redeemed from the provider’s stored value. The merchant is owed money. redeemed_amount represents the amount redeemed.
  • failed: the redemption could not be completed. The provider rejected the redemption (voucher already used, expired, invalid PIN, insufficient balance, etc.) or an error may have occurred. No money has moved. Additional information may be available in last_error.
  • reserved: value has been reserved and is awaiting confirmation.
Today, all supported providers complete redemption immediately.

As a result, redemptions transition directly from draft to confirmed or failed.

See [Providers](/documentation/collect/redemptions/providers) for addtional details.

​
How a redemption works

The lifecycle is consistent across stored value types. The examples below use voucher redemption, which is the stored value type supported today.

The client makes a single API request. Moment manages the interaction with the underlying provider, including redemption processing, error handling, and recovery where supported.

Immediate Redemption For all currently supported providers, redemption is completed in a single request. Reserved Redemption Some providers may support reserving value before final confirmation.

​
Voucher Redemption Outcomes

Voucher redemption may result in one of three outcomes.
  1. Full Redemption. The requested amount is redeemed successfully and no value remains.
  2. Partial Redemption. The requested amount is redeemed successfully and value remains after redemption. The remaining value may be returned as a replacement (change) voucher or delivered through another provider-specific mechanism. See Providers for more details.
  3. Failed Redemption. The redemption is rejected and no value is redeemed. Common causes include invalid credentials, insufficient available value, expired vouchers, or previously redeemed vouchers.

​
Guarantees

  • Duplicate Redemption Protection. Repeated requests using the same Idempotency-Key return the original outcome without creating an additional redemption. Requests using the same key with different request bodies are rejected.
  • Remaining Value Preservation. Where a provider returns remaining value after a partial redemption, that value is captured on the redemption and returned in the API response where supported.
  • Recovery from Ambiguous Provider Responses. When a provider response times out, the service resolves the redemption to a final confirmed or failed state (never an indeterminate “maybe”), using provider-specific recovery endpoints where available.
  • Full Audit History. Every redemption attempt, provider reference, state transition, and error is recorded on the redemption and remains available for auditing and troubleshooting.
  • Consistent Events. Webhook events remain consistent with the redemption state, allowing downstream systems to process redemption outcomes reliably.