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

# Status reference

> All status values, state transitions, and what to do when each terminal state fires.

Every object in DollarPe has a lifecycle. This page covers all possible statuses, how they transition, and what your integration should do when each one fires.

## Color coding

All flow diagrams use the same color convention:

* Green: success / completed
* Red: failed / error
* Orange: reversed / refunded
* Yellow: on hold / cancelled

***

## Customer status

| Status       | Description                                      |
| ------------ | ------------------------------------------------ |
| `UNVERIFIED` | Initial state after customer creation            |
| `PROCESSING` | KYC submitted, automated checks running          |
| `VERIFIED`   | KYC passed. Customer can link banks and transact |
| `FAILED`     | KYC failed or account suspended                  |

```mermaid theme={null}
graph LR
    A[UNVERIFIED] --> B[PROCESSING]
    B --> C[VERIFIED]
    B --> D[FAILED]
    style C fill:#4CAF50,color:#fff
    style D fill:#FF5252,color:#fff
```

**What to do:**

* `VERIFIED`: unlock transaction flows for this customer
* `FAILED`: check `failure_reason` in the `CUSTOMER` webhook. If recoverable (e.g., `DOCUMENT_VERIFICATION_FAILED`), prompt the user to retry. If terminal (e.g., `KYC_FAILED`), contact DollarPe support with the customer ID

***

## Bank status

| Status       | Description                                            |
| ------------ | ------------------------------------------------------ |
| `PROCESSING` | Bank account or UPI ID submitted, verification running |
| `VERIFIED`   | Bank account or UPI ID verified and ready to use       |
| `FAILED`     | Verification failed                                    |

```mermaid theme={null}
graph LR
    A[PROCESSING] --> B[VERIFIED]
    A --> C[FAILED]
    style B fill:#4CAF50,color:#fff
    style C fill:#FF5252,color:#fff
```

**What to do:**

* `VERIFIED`: the bank account is ready for payout orders
* `FAILED`: check `failure_reason` in the `BANK` webhook. Common reasons: `ACCOUNT_TYPE_NRE`, `NAME_MISMATCH`, `PENNY_DROP_FAILED`. Prompt the user to add a different account or correct the details

***

## Quotation status

| Status     | Description                                 |
| ---------- | ------------------------------------------- |
| `UNLINKED` | Quotation created, not yet tied to an order |
| `LINKED`   | Quotation locked to an order and in use     |
| `EXPIRED`  | Quotation validity period elapsed           |

```mermaid theme={null}
graph LR
    A[UNLINKED] --> B[LINKED]
    A --> C[EXPIRED]
    style B fill:#4CAF50,color:#fff
    style C fill:#FF5252,color:#fff
```

**What to do:**

* `EXPIRED`: fetch a new quotation and present the updated rate to the user before retrying

***

## Payin status

| Status             | Description                                    |
| ------------------ | ---------------------------------------------- |
| `PROCESSING`       | Payin submitted, awaiting payment confirmation |
| `SUCCESS`          | Payment received and crypto released           |
| `FAILED`           | Payin failed                                   |
| `REFUND_INITIATED` | Refund process started                         |
| `REFUNDED`         | Fiat returned to the user's source account     |
| `ON_HOLD`          | Payment flagged and held for review            |

```mermaid theme={null}
graph LR
    A[PROCESSING] --> B[SUCCESS]
    A --> C[FAILED]
    A --> F[REFUND_INITIATED]
    F --> D[REFUNDED]
    A --> E[ON_HOLD]
    style B fill:#4CAF50,color:#fff
    style C fill:#FF5252,color:#fff
    style D fill:#FFA726,color:#fff
    style E fill:#FFD600,color:#000
    style F fill:#FFA726,color:#fff
```

**What to do:**

* `SUCCESS`: release crypto to the user. Record the `id` from the webhook as your reconciliation reference
* `FAILED`: check `failure_reason` in the `PAYIN` webhook (e.g., `INCORRECT_UTR`, `PAYMENT_NOT_RECEIVED`). Notify the user. Do not release crypto
* `REFUND_INITIATED`: wait for `REFUNDED` before updating the user
* `REFUNDED`: notify the user that their fiat has been returned. Do not release crypto
* `ON_HOLD`: do not release crypto. Contact DollarPe support with the payin ID

***

## Payout status

| Status       | Description                                  |
| ------------ | -------------------------------------------- |
| `PROCESSING` | Payout submitted, funds transfer in progress |
| `SUCCESS`    | Funds delivered to the beneficiary           |
| `FAILED`     | Payout failed                                |
| `REFUNDED`   | Payout amount returned to source             |
| `CANCELLED`  | Payout cancelled before processing completed |

```mermaid theme={null}
graph LR
    A[PROCESSING] --> B[SUCCESS]
    A --> C[FAILED]
    A --> D[REFUNDED]
    A --> E[CANCELLED]
    style B fill:#4CAF50,color:#fff
    style C fill:#FF5252,color:#fff
    style D fill:#FFA726,color:#fff
    style E fill:#FFD600,color:#000
```

**What to do:**

* `SUCCESS`: confirm delivery to the user. Use `metadata.utr` from the webhook as the transfer reference
* `FAILED`: check `failure_reason` in the `PAYOUT` webhook. Notify the user. Contact DollarPe support for reconciliation
* `REFUNDED` / `CANCELLED`: notify the user. The transaction did not complete

***

## EDD status

Enhanced Due Diligence applies to customers whose transaction volume triggers additional verification requirements.

| Status     | Description                                    |
| ---------- | ---------------------------------------------- |
| `VERIFIED` | EDD passed. Customer has enhanced payin limits |
| `FAILED`   | EDD failed. Standard limits remain in place    |

```mermaid theme={null}
graph LR
    A[PROCESSING] --> B[VERIFIED]
    A --> C[FAILED]
    style B fill:#4CAF50,color:#fff
    style C fill:#FF5252,color:#fff
```

**What to do:**

* `VERIFIED`: update the customer's displayed limits in your UI
* `FAILED`: inform the user their limits remain unchanged. They can resubmit EDD documents if the failure reason is correctable