---
title: "Redeem Transaction Recovery"
slug: "redeem-transaction-recovery"
updated: 2026-06-30T21:33:59Z
published: 2026-06-30T21:33:59Z
canonical: "docs.xtremepush.com/redeem-transaction-recovery"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Redeem Transaction Recovery

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).

```plaintext
┌─────────┐
│ 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 |

> [!NOTE]
> **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**

```json
{
  "transactionId": "txn_abc123def456",
  "secretKey": "secret_key_here"
}
```

**Flow**

1. Admin calls confirm endpoint with transaction ID
2. System validates transaction is in eligible state
3. Token subtract is finalized
4. Transaction status updated to success
5. 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**

```json
{
  "transactionId": "txn_abc123def456"
}
```

**External callback request body example**

```json
{
  "transactionId": "txn_abc123def456",
  "secretKey": "provider_secret_key_here"
}
```

**Flow**

1. Admin calls cancel endpoint with transaction ID
2. System validates transaction is in eligible state
3. Token subtract is rolled back
4. Transaction status updated to failure
5. 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

> [!WARNING]
> **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

1. Webhook delivery fails (non-200/201 response or network error)
2. Transaction state updated to recoverable-failure
3. Notification service processes event and delivers to configured channels
4. Administrators receive alert with transaction context and recovery action link

> [!NOTE]
> **Notification timing**
> 
> Notifications are sent immediately upon entering `recoverable-failure` state, 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 |

> [!WARNING]
> **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

1. **Detection** — Admin receives notification of failed transaction
2. **Investigation** — Admin queries failed transactions using admin API
3. **External verification** — Admin contacts external provider to verify redemption status
4. **Decision** — Based on provider confirmation:
  - If provider fulfilled redemption: call confirm endpoint
  - If provider cannot fulfill: call cancel endpoint
5. **Verification** — Query transaction again to confirm state transition to terminal state
6. **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.