> ## 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 Lifecycle

> Overview of card transaction lifecycle, flow, and types

# Transaction Lifecycle

This guide provides an overview of how card transactions work in the Issuing API, including the transaction flow, lifecycle states, and transaction types.

## Overview

Card transactions are created automatically when cardholders use their cards for purchases, ATM withdrawals, or other card-based transactions. As an issuer, you can monitor these transactions, view their status, and perform operations like refunds.

## Transaction Lifecycle

Card transactions follow a standard authorization-capture flow with support for reversals and refunds:

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending: Cardholder Uses Card<br/>(Authorization)
    Pending --> Posted: Transaction Captured<br/>(Funds Settled)
    Pending --> Declined: Authorization Failed<br/>(Insufficient Funds, etc.)
    Pending --> Void: Authorization Reversed<br/>(Before Capture)
    
    Posted --> Refunded: Refund Issued
    Posted --> [*]: Transaction Complete
    Declined --> [*]: Transaction Complete
    Void --> [*]: Transaction Complete
    Refunded --> [*]: Transaction Complete
    
    note right of Pending
        Authorization holds funds
        but doesn't transfer them yet.
        Can be reversed or captured.
    end note
    
    note right of Posted
        Funds are settled and
        transaction is final.
        Can only be refunded.
    end note
```

## Transaction Flow

The following sequence diagram shows how a card transaction flows through the system:

```mermaid theme={null}
sequenceDiagram
    participant Cardholder
    participant Merchant
    participant Network as Payment Network
    participant API as Issuing API
    participant CardAccount as Card Account
    
    Cardholder->>Merchant: Swipe/Tap/Insert Card
    Merchant->>Network: Authorization Request<br/>(Amount, Card Details)
    Network->>API: Forward Authorization Request
    
    Note over API: Check Card Status<br/>Check Balance<br/>Verify Limits
    
    alt Authorization Approved
        API->>CardAccount: Hold Funds (Authorization)
        API->>Network: Authorization Approved
        Network->>Merchant: Authorization Approved
        Merchant->>Cardholder: Transaction Approved
        
        Note over API: Transaction Status: pending
        
        Note over API,CardAccount: Capture (typically automatic)
        API->>CardAccount: Debit Funds
        API->>API: Update Status: posted
        
        API->>Network: Capture Confirmation
        Network->>Merchant: Funds Settled
    else Authorization Declined
        API->>Network: Authorization Declined<br/>(Reason: Insufficient Funds, etc.)
        Network->>Merchant: Transaction Declined
        Merchant->>Cardholder: Transaction Declined
        
        Note over API: Transaction Status: declined
    end
```

## Transaction Statuses Overview

Card transactions can be in one of four states:

| Status       | Description                             | Next Actions              |
| ------------ | --------------------------------------- | ------------------------- |
| **pending**  | Transaction authorized but not captured | Can be captured or voided |
| **posted**   | Transaction captured and finalized      | Can be refunded           |
| **declined** | Authorization failed                    | No further action         |
| **void**     | Authorization reversed                  | No further action         |

<Note>
  For detailed information about each status, see [Transaction Statuses](/issuing/guides/transaction-statuses).
</Note>

## Transaction Types

Card transactions can have different intents:

| Intent       | Description                  | Example                               |
| ------------ | ---------------------------- | ------------------------------------- |
| **charge**   | Card purchase or payment     | Cardholder buys goods at merchant     |
| **refund**   | Refund of a previous charge  | Merchant refunds a purchase           |
| **topup**    | Adding funds to card account | Cardholder adds money to prepaid card |
| **withdraw** | ATM withdrawal               | Cardholder withdraws cash             |
| **fee**      | Service fee                  | Monthly card fee, ATM fee             |
| **cashback** | Cashback reward              | Rewards program cashback              |
| **interest** | Interest payment             | Interest earned on balance            |

## Key Concepts

### Authorization vs Capture

* **Authorization**: Holds funds but doesn't transfer them. Transaction status is `pending`.
* **Capture**: Transfers funds and finalizes the transaction. Transaction status becomes `posted`.

### Reversal vs Refund

* **Reversal (Void)**: Cancels a `pending` authorization before capture. Funds are released immediately.
* **Refund**: Returns funds from a `posted` transaction. Creates a new refund transaction.

## Next Steps

* [Transaction Statuses](/issuing/guides/transaction-statuses) - Detailed guide to transaction statuses
* [Webhooks Guide](/issuing/guides/webhooks-1) - Set up real-time transaction notifications
* [API Reference](/issuing/api-reference/openapi) - Explore transaction endpoints