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

# Transaction Statuses

> Detailed guide to transaction statuses, transitions, and handling each state

# Transaction Statuses

This guide explains each transaction status in detail, including when they occur, how to handle them, and what actions are available.

## Status Overview

Card transactions can be in one of four states:

| Status       | Description                             | When It Occurs                         | Can Be Changed To                       |
| ------------ | --------------------------------------- | -------------------------------------- | --------------------------------------- |
| **pending**  | Transaction authorized but not captured | Immediately after authorization        | `posted`, `declined`, or `void`         |
| **posted**   | Transaction captured and finalized      | After capture (typically automatic)    | `refunded` (via new refund transaction) |
| **declined** | Authorization failed                    | Authorization rejected                 | None (final state)                      |
| **void**     | Authorization reversed                  | Authorization cancelled before capture | None (final state)                      |

## Status Transitions

### Normal Flow

```mermaid theme={null}
flowchart LR
    A[Authorization] --> B[pending]
    B --> C[Capture]
    C --> D[posted]
    D --> E[Refund]
    E --> F[refund transaction]

    X[Direct capture<br/>offline / ATM /<br/>stand-in auth] --> D

    style B fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style D fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style F fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style X fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
```

**Typical Flow:**

1. **Authorization** → Transaction status: `pending`
2. **Capture** (automatic) → Transaction status: `posted`
3. **Refund** (if needed) → New transaction with `intent: "refund"`

**Direct-capture Flow** (no `pending` step):

Some transactions reach `posted` without a prior authorization. The issuer first sees them at clearing time. This applies to:

* **Offline transactions** — terminals that capture offline and submit later
* **ATM withdrawals** — captured directly when the network sends the clearing record
* **Stand-in authorizations** — approved by the card network and surfaced to the issuer only at clearing

For these transactions, the resulting record has `status: "posted"` and the `type` field set to the underlying transaction kind (e.g. `PURCHASE`, `ATM`). The reason for direct capture is not exposed in the webhook payload.

### Failure Scenarios

```mermaid theme={null}
flowchart TD
    Start([Transaction event]) --> M{Message type?}
    M -->|Authorization| A[Authorization Request]
    M -->|No auth| X[Direct capture<br/>offline / ATM /<br/>stand-in auth]
    X --> F[posted]
    A --> B{Approved?}
    B -->|Yes| C[pending]
    B -->|No| D[declined]
    C --> E{Captured?}
    E -->|Yes| F
    E -->|No| G{Reversed?}
    G -->|Yes| H[void]
    G -->|No| C

    style C fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style D fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
    style F fill:#c8e6c9,stroke:#388e3c,stroke-width:2px,color:#000
    style H fill:#e1bee7,stroke:#7b1fa2,stroke-width:2px,color:#000
    style X fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
```

## Pending Transactions

**Status:** `pending`

Pending transactions represent authorized but not yet captured transactions.

### Characteristics

* **Funds Status**: Funds are held but not transferred
* **Reversibility**: Can be reversed (voided) before capture
* **Capture Timing**: Automatically captured after authorization (typically within seconds)
* **postedAt Field**: `null` until captured
* **Amount**: May change while pending (e.g., tip adjustments)

### When It Occurs

* Immediately after successful authorization
* Before capture completes
* During tip adjustment period (for certain transaction types)

### Use Cases

* Monitor pending authorizations
* Detect potential fraud before capture
* Reverse unauthorized transactions
* Track authorization holds

### Example Response

```json theme={null}
{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "pending",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "postedAt": null,
  "authorization": {
    "id": "auth_abc123",
    "amount": 50.00
  }
}
```

### Actions Available

* **Monitor**: Query transactions with `status=pending`
* **Void**: Reverse the authorization (if needed)
* **Wait**: Allow automatic capture to proceed

## Posted Transactions

**Status:** `posted`

Posted transactions are finalized and funds have been settled.

### Characteristics

* **Funds Status**: Funds have been transferred
* **Reversibility**: Cannot be reversed (only refunded)
* **Finality**: Transaction details are final
* **postedAt Field**: Contains capture timestamp
* **Amount**: Final and cannot change

### When It Occurs

* After successful capture
* Typically automatic after authorization
* When funds are settled

### Use Cases

* Generate statements
* Calculate balances
* Process refunds
* Accounting reconciliation
* Compliance reporting

### Example Response

```json theme={null}
{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "posted",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "postedAt": "2025-01-15T10:30:05Z",
  "authorization": {
    "id": "auth_abc123",
    "amount": 50.00
  }
}
```

### Actions Available

* **Refund**: Create a refund transaction
* **Report**: Include in statements and reports
* **Monitor**: Track for disputes or issues

## Declined Transactions

**Status:** `declined`

Declined transactions failed authorization.

### Characteristics

* **Funds Status**: No funds held or transferred
* **Finality**: Cannot be changed or retried
* **Reason**: Declined for specific reason (see below)
* **postedAt Field**: `null`

### Common Reasons

| Reason                      | Description                                |
| --------------------------- | ------------------------------------------ |
| **Insufficient Balance**    | Card account doesn't have enough funds     |
| **Card Suspended**          | Card is temporarily blocked                |
| **Card Cancelled**          | Card has been permanently cancelled        |
| **Spending Limit Exceeded** | Transaction exceeds card or account limits |
| **Card Expired**            | Card expiration date has passed            |
| **Invalid PIN/CVV**         | Incorrect authentication credentials       |
| **Fraud Detection**         | Transaction flagged by fraud system        |
| **Restricted Merchant**     | Merchant or category is blocked            |

### When It Occurs

* During authorization request
* Before any funds are held
* Immediately after authorization attempt

### Use Cases

* Monitor decline rates
* Identify card issues
* Alert cardholders
* Fraud detection
* Improve authorization rates

### Example Response

```json theme={null}
{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "declined",
  "amount":  Reason": "insufficient_balance",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "postedAt": null
}
```

### Actions Available

* **Monitor**: Track decline rates and reasons
* **Alert**: Notify cardholder of issue
* **Investigate**: Review card account status
* **Resolve**: Fix underlying issue (fund account, unsuspend card, etc.)

## Void Transactions

**Status:** `void`

Void transactions are authorizations that were reversed before capture.

### Characteristics

* **Funds Status**: Funds were released back to card account
* **Transfer**: No funds were transferred
* **Refundability**: Cannot be refunded (nothing was captured)
* **Timing**: Must occur before capture

### When It Occurs

* Authorization reversed before capture
* Manual void by issuer
* System-initiated reversal
* Authorization timeout/expiry

### Use Cases

* Reverse mistaken authorizations
* Cancel pending transactions
* Release held funds
* Handle authorization errors

### Example Response

```json theme={null}
{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "void",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "voidedAt": "2025-01-15T10:30:02Z",
  "postedAt": null
}
```

### Actions Available

* **Monitor**: Track voided transactions
* **Verify**: Confirm funds were released
* **Report**: Include in reconciliation

## Status Comparison

| Aspect                | pending    | posted           | declined | void          |
| --------------------- | ---------- | ---------------- | -------- | ------------- |
| **Funds Held**        | Yes        | No (transferred) | No       | No (released) |
| **Funds Transferred** | No         | Yes              | No       | No            |
| **Can Reverse**       | Yes (void) | No               | N/A      | N/A           |
| **Can Refund**        | No         | Yes              | No       | No            |
| **postedAt**          | `null`     | Timestamp        | `null`   | `null`        |
| **Final**             | No         | Yes              | Yes      | Yes           |

## Best Practices

### 1. Monitor Status Transitions

Set up alerts for unexpected status transitions:

**Concept:**

* Query transactions with `status=pending` and a time threshold
* Alert if transactions remain pending longer than expected
* Investigate long-pending transactions for potential issues

**Endpoint:** `GET /v1/cardaccounts/transactions`

**Query Parameters:**

* `status`: `pending`
* `dateRangeFrom`: Threshold time (e.g., 1 hour ago)

**Example:**

```bash theme={null}
curl "https://access.utgl.io/v1/cardaccounts/transactions?cardAccountId=YOUR_ID&status=pending&dateRangeFrom=2025-01-15T09:30:00Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Monitoring Strategy:**

* Set up scheduled queries for pending transactions
* Alert when transactions exceed expected pending duration
* Review transaction details for investigation

### 2. Handle Each Status Appropriately

* **pending**: Monitor for fraud, allow capture to proceed
* **posted**: Include in statements, process refunds if needed
* **declined**: Investigate reason, alert cardholder
* **void**: Verify funds released, update records

### 3. Track Status Changes

Use webhooks to receive real-time status updates:

* `cardaccount.transaction.created` - New transaction record appears
* `cardaccount.transaction.updated` - Status changes on an existing transaction (e.g. pending → posted, pending → void)
* `cardaccount.transaction.declined` - Transaction declined

## Next Steps

* [Transaction Lifecycle](/issuing/guides/transaction-lifecycle) - Overview of transaction flow
* [Webhooks Guide](/issuing/guides/webhooks-1) - Set up status change notifications
* [API Reference](/issuing/api-reference/openapi) - Explore transaction endpoints