The XP loyalty provides manual recovery capabilities for failed redeem option transactions. When webhook delivery to external providers fails, administrators can manually confirm or cancel transactions through dedicated recovery endpoints.
Overview
The XP loyalty manages redeem option transactions, which occur when users exchange loyalty tokens for rewards from external providers. Transactions may fail during webhook delivery due to network issues, provider downtime, or temporary service disruptions. The system provides manual recovery mechanisms for these failed transactions through administrative APIs.
This guide covers the transaction lifecycle, recovery workflows, and operational procedures for handling failed redeem transactions.
Before you begin
Required access — You must have access to the XP loyalty to perform transaction recovery operations. Recovery endpoints are restricted to authenticated admin users.
Transaction state awareness — Only transactions in specific intermediate states can be recovered. Permanently terminal states (success, failure) cannot be modified through recovery endpoints.
Manual intervention — Transaction recovery is a manual, admin-triggered process. The system does not provide automatic scheduled recovery of failed transactions.
Transaction lifecycle
Redeem transactions progress through the following states:
Transaction states
State | Type | Description |
|---|---|---|
pending | Initial | Transaction initiated, awaiting provider webhook response |
postponed | Intermediate | Provider accepted webhook (HTTP 201), awaiting external confirmation |
recoverable-failure | Intermediate | Webhook delivery failed with transient error, eligible for manual recovery |
success | Terminal | Transaction completed successfully, tokens subtracted permanently |
failure | Terminal | Transaction failed permanently, tokens rolled back to user, no recovery possible |
State flow diagram
Transactions in postponed or recoverable-failure states can be resolved through either admin manual intervention or external provider callbacks (for postponed only).
┌─────────┐
│ pending │
└────┬────┘
│
Webhook POST to provider
│
┌────────────────┼────────────────┐
│ │ │
HTTP 200 HTTP 201 Other HTTP
│ │ status codes
│ │ │
▼ ▼ ▼
┌─────────┐ ┌────────────┐ ┌──────────────────┐
│ success │ │ postponed │ │ recoverable- │
└─────────┘ └─────┬──────┘ │ failure │
(terminal) │ └────────┬─────────┘
│ │
┌──────────┴─────────┐ │
│ │ │
External Admin ┌───┴────────┐
callback actions │ │
│ │ │ Admin
│ ┌───────┼────┤ actions
│ │ │ │ │
└────────────┼───────┘ └────────────┤
│ │
┌─────────┴──────────┐ │
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ success │ │ failure │ │ failure │
└─────────┘ └─────────┘ └─────────┘
(terminal) (terminal) (terminal)
How recovery status is determined
The system determines transaction status based on webhook delivery results:
HTTP status code mapping
HTTP Status | Transaction State | Token Action | Explanation |
|---|---|---|---|
200 | success | Burn finalized | Provider confirms immediate completion |
201 | postponed | Burn pending | Provider acknowledges, will confirm asynchronously |
Any other status | recoverable-failure | Burn held for review | Transient failure, manual recovery available |
Network errors | recoverable-failure | Burn held for review | Connection failures, timeouts, DNS errors |
Single webhook attempt
The system performs a single webhook POST attempt to the provider with a 15-second timeout. Any non-200/201 response or network failure immediately transitions the transaction to recoverable-failure state.
Recovery mechanism
Transaction recovery is exclusively manual and requires administrative intervention.
Discovering failed transactions
Administrators can identify failed transactions through the admin panel interface or by querying their own transaction database. Failed transactions can be filtered by status (recoverable-failure, postponed) to identify those requiring manual intervention.
Admin recovery endpoints
Confirm transaction (resolve as success)
Use when the external provider has confirmed redemption completion outside the webhook flow.
External provider callback endpoint
POST /providers/:provider/events/redeem.static.success
Body Object
Parameter | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Provider identifier (path parameter) |
transactionId | string | Yes | Transaction ID to confirm |
secretKey | string | External callback only | Provider authentication key (not required for admins, unique for each redeem option, visible after creation) |
Eligible states
postponed
recoverable-failure
External callback request body example
{
"transactionId": "txn_abc123def456",
"secretKey": "secret_key_here"
}Flow
Admin calls confirm endpoint with transaction ID
System validates transaction is in eligible state
Token subtract is finalized
Transaction status updated to success
TOKENS_TRANSACTION_RESOLVE Kafka event emitted
Result
Transaction moved to success state
User's token subtract is permanently finalized
Redemption recorded as completed
Cancel transaction (resolve as failure)
Use when the external provider cannot fulfill the redemption, or the transaction must be permanently failed.
External provider callback endpoint
POST /providers/:provider/events/redeem.static.failure
Body Object
Parameter | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Provider identifier (path parameter) |
transactionId | string | Yes | Transaction ID to cancel |
secretKey | string | External callback only | Provider authentication key (not required for admins) |
Eligible states
postponed
recoverable-failure
Admin request example
{
"transactionId": "txn_abc123def456"
}External callback request body example
{
"transactionId": "txn_abc123def456",
"secretKey": "provider_secret_key_here"
}Flow
Admin calls cancel endpoint with transaction ID
System validates transaction is in eligible state
Token subtract is rolled back
Transaction status updated to failure
TOKENS_TRANSACTION_RESOLVE Kafka event emitted
Result
Transaction moved to failure state (terminal)
User's tokens are returned to their balance
Redemption recorded as failed
Token rollback
When canceling a transaction, the system automatically returns the subtracted tokens to the user's balance. Ensure this is the intended outcome before confirming cancellation.
Notification system
When a transaction enters recoverable-failure state, the system automatically notifies administrators.
Notification details
Field | Value |
|---|---|
Title | "Redeem Option Webhook failed" |
Content | Includes redeem option name, option type, affected user ID |
Notification flow
Webhook delivery fails (non-200/201 response or network error)
Transaction state updated to recoverable-failure
Notification service processes event and delivers to configured channels
Administrators receive alert with transaction context and recovery action link
Notification timing
Notifications are sent immediately upon entering
recoverable-failurestate, after the single webhook delivery attempt fails.
Provider support
Not all providers support recoverable failure states. Recovery capabilities vary by provider implementation.
Provider compatibility
Provider | Recoverable Failure | Notes |
|---|---|---|
Webhook | Yes | Full support for manual recovery |
Tangible | Yes | Same recovery pattern as webhook provider |
Prizeout | No | Does not support recoverable-failure state |
Provider-specific behavior
Always verify the provider type before attempting recovery. Providers without recoverable-failure support will not expose transactions in intermediate states through the admin recovery endpoints.
Operational workflow
Standard recovery procedure
Detection — Admin receives notification of failed transaction
Investigation — Admin queries failed transactions using admin API
External verification — Admin contacts external provider to verify redemption status
Decision — Based on provider confirmation:
If provider fulfilled redemption: call confirm endpoint
If provider cannot fulfill: call cancel endpoint
Verification — Query transaction again to confirm state transition to terminal state
User communication — If tokens were rolled back (cancel), notify user as appropriate
Monitoring and reporting
Monitor failed transactions
Regularly review transactions in recoverable-failure and postponed states through the admin panel to ensure timely processing. Transactions in postponed state for extended periods may require manual intervention if the external provider fails to send confirmation callbacks.
Reconciliation
Maintain audit logs of all manual recovery actions for accounting reconciliation, especially when handling bulk recovery scenarios.
Frequently asked questions
What happens if I confirm a transaction that was never fulfilled by the provider?
Confirming a transaction finalizes the token subtracts and marks the redemption as complete. The user will not receive their tokens back. Only confirm transactions after verifying with the external provider that they have fulfilled the redemption on their side.
Can I recover a transaction that is already in success or failure state?
No. Both success and failure are terminal states. Once a transaction reaches these states, it cannot be modified through recovery endpoints. The token subtracts (for success) or rollback (for failure) has been permanently finalized.
How long does a transaction stay in recoverable-failure state?
Indefinitely. Transactions remain in recoverable-failure state until an administrator manually confirms or cancels them. There is no automatic expiration or state transition.
What is the difference between postponed and recoverable-failure?postponed indicates the provider acknowledged the webhook (HTTP 201) and will confirm asynchronously. recoverable-failure indicates webhook delivery failed completely. Both states support manual recovery, but postponed transactions may automatically resolve if the provider sends confirmation via their callback mechanism.
Is there a retry mechanism before transactions fail?
The system performs a single webhook POST attempt with a 15-second timeout. Any non-200/201 response or network failure immediately transitions the transaction to recoverable-failure. There is no automatic retry loop at the webhook delivery layer.
Why doesn't the Prizeout provider support recoverable-failure?
Provider-specific implementation differences determine recovery support. Prizeout's integration pattern does not expose intermediate failure states that allow manual recovery. Transactions with Prizeout resolve directly to terminal states.
Can I bulk recover multiple transactions at once?
The current API requires individual transaction recovery through dedicated confirm/cancel endpoints. For bulk recovery scenarios, you must iterate through transactions and call the appropriate endpoint for each transaction ID.
What if a transaction is stuck in postponed state for days?
This typically indicates the external provider (your backend, or another provider) has not sent their asynchronous confirmation callback. Contact the provider to verify redemption status. If confirmed externally, use the confirm endpoint to manually resolve the transaction. If the provider failed to complete the redemption, use the cancel endpoint to roll back tokens.