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

# Transaction Statuses

> This section goes over the various statuses Meld transactions can have and what they mean.

# Transaction Statuses

This page is for developers wiring up webhook handlers and dashboard logic across any of Meld's crypto products. It lists every status a Meld transaction can have, what each one means, and which are temporary vs final. Statuses are identical across White-Label API, Meld Checkout, and Virtual Account.

<Tip>
  Use TERMINAL statuses to decide when to stop polling, release funds, or surface a final UI state to the user. Use TEMPORARY statuses to display progress.
</Tip>

## Common Transaction Flow

The typical successful transaction follows this progression:

**`PENDING`→`SETTLING` →`SETTLED`**

* **PENDING**: User has started payment process
* **SETTLING**: User submitted payment, funds being processed
* **SETTLED**: Payment completed successfully, crypto delivered to user
* **FAILED**: Transaction unsuccessful at any stage

## Status Types

**TEMPORARY**: Status will continue to change as transaction progresses\
**TERMINAL**: Final status - no further changes will occur

## Current Transaction Statuses

### Active Processing States

| Status            | Description                                                      | Type      | User Action                  |
| ----------------- | ---------------------------------------------------------------- | --------- | ---------------------------- |
| `PENDING CREATED` | Transaction created in Meld system, awaiting provider processing | TEMPORARY | Wait for processing          |
| `PENDING`         | Submitted to provider for review and verification                | TEMPORARY | Wait for approval            |
| `SETTLING`        | Provider approved transaction, crypto transfer in progress       | TEMPORARY | Wait for completion          |
| `TWO_FA_REQUIRED` | Payment info provided, awaiting 2FA verification                 | TEMPORARY | Complete 2FA verification    |
| `TWO_FA_PROVIDED` | 2FA submitted, provider validating with card issuer              | TEMPORARY | Wait for validation          |
| `ERROR`           | Technical error during processing - transaction may retry        | TEMPORARY | Monitor for retry or failure |

### Final States

| Status      | Description                                                           | Type     | Next Steps                           |
| ----------- | --------------------------------------------------------------------- | -------- | ------------------------------------ |
| `SETTLED`   | Transaction completed successfully, crypto delivered                  | TERMINAL | Transaction complete                 |
| `FAILED`    | Transaction declined by payment systems                               | TERMINAL | User can retry with different method |
| `DECLINED`  | Declined by provider or bank (insufficient funds, invalid card, etc.) | TERMINAL | User should check payment method     |
| `CANCELLED` | Cancelled by user during payment process                              | TERMINAL | User can start new transaction       |
| `REFUNDED`  | Crypto not delivered, full refund issued to customer                  | TERMINAL | Refund processed                     |

## Legacy Statuses

These statuses may appear in older transactions:

| Status                  | Modern Equivalent | Type      |
| ----------------------- | ----------------- | --------- |
| `ACCEPTED`              | `PENDING`         | TEMPORARY |
| `AUTHORIZED`            | `PENDING`         | TEMPORARY |
| `PARTIALLY_SETTLED`     | `PENDING`         | TEMPORARY |
| `AUTHORIZATION_EXPIRED` | `FAILED`          | TERMINAL  |

## Implementation Notes

**Webhook Handling**: Monitor for status changes via webhooks to update your UI in real-time

**Error Handling**: For TERMINAL failure states (`FAILED`, `DECLINED`, `CANCELLED`), allow users to start a new transaction

**User Communication**: Keep users informed during TEMPORARY states, especially longer processes like `SETTLING`

<br />