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

# Status reference

> Every status, how it transitions, and what your integration should do.

Every object in Zapyd 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
* Red: failed
* Amber: refunds, holds and reviews, which need attention but aren't failures

***

## 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={"theme":{"light":"css-variables","dark":"css-variables"}}
graph LR
    A[UNVERIFIED] --> B[PROCESSING]
    B --> C[VERIFIED]
    B --> D[FAILED]
    style C fill:#E6F3ED,stroke:#99CDB6,color:#018248
    style D fill:#FEF3F2,stroke:#FECDCA,color:#B42318
```

**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 (`KYC_FAILED`), contact Zapyd support with the customer ID. See [KYC sharing](/guides/customers/kyc-sharing#5-fix-a-failure) for the update endpoint per reason

***

## Bank status

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

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"}}
graph LR
    A[PROCESSING] --> B[VERIFIED]
    A --> C[FAILED]
    style B fill:#E6F3ED,stroke:#99CDB6,color:#018248
    style C fill:#FEF3F2,stroke:#FECDCA,color:#B42318
```

**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={"theme":{"light":"css-variables","dark":"css-variables"}}
graph LR
    A[UNLINKED] --> B[LINKED]
    A --> C[EXPIRED]
    style B fill:#E6F3ED,stroke:#99CDB6,color:#018248
    style C fill:#FEF3F2,stroke:#FECDCA,color:#B42318
```

**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={"theme":{"light":"css-variables","dark":"css-variables"}}
graph LR
    A[PROCESSING] --> B[SUCCESS]
    A --> C[FAILED]
    A --> F[REFUND_INITIATED]
    F --> D[REFUNDED]
    A --> E[ON_HOLD]
    style B fill:#E6F3ED,stroke:#99CDB6,color:#018248
    style C fill:#FEF3F2,stroke:#FECDCA,color:#B42318
    style D fill:#FFFAEB,stroke:#FEDF89,color:#B54708
    style E fill:#FFFAEB,stroke:#FEDF89,color:#B54708
    style F fill:#FFFAEB,stroke:#FEDF89,color:#B54708
```

**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 Zapyd 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 |
| `IN_REVIEW` | Held for compliance review, or waiting on a request for information (RFI) from the customer |
| `PENDING` | Widget orders only: waiting for the customer's crypto transfer |

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"}}
graph LR
    A[PROCESSING] --> B[SUCCESS]
    A --> C[FAILED]
    A --> D[REFUNDED]
    A --> E[IN_REVIEW]
    E --> B
    E --> C
    style B fill:#E6F3ED,stroke:#99CDB6,color:#018248
    style C fill:#FEF3F2,stroke:#FECDCA,color:#B42318
    style D fill:#FFFAEB,stroke:#FEDF89,color:#B54708
    style E fill:#FFFAEB,stroke:#FEDF89,color:#B54708
```

**What to do:**

* `SUCCESS`: confirm delivery to the user. Use `metadata.utr` from the webhook as the transfer reference
* `FAILED`: `failure_reason` is always the generic `Payout failed`. Notify the user. Contact Zapyd support with the payout ID for details
* `REFUNDED`: notify the user. The transaction did not complete; see `metadata.refund_reason`
* `IN_REVIEW`: if the webhook carries `metadata.rfi_link`, send the customer there to answer the request for information. Otherwise wait; the payout moves to `SUCCESS` or `FAILED`

***

## EDD status

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

| Status | Description |
| - | - |
| `PROCESSING` | EDD submitted, review not started |
| `DOCS_REQ` | The reviewer needs more documents |
| `IN_REVIEW` | Under manual review |
| `VERIFIED` | EDD passed. The customer has higher limits |
| `FAILED` | EDD failed. Standard limits remain in place |

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"}}
graph LR
    A[PROCESSING] --> B[VERIFIED]
    A --> C[FAILED]
    A --> D[DOCS_REQ]
    A --> E[IN_REVIEW]
    E --> B
    E --> C
    style B fill:#E6F3ED,stroke:#99CDB6,color:#018248
    style C fill:#FEF3F2,stroke:#FECDCA,color:#B42318
    style D fill:#FFFAEB,stroke:#FEDF89,color:#B54708
```

**What to do:**

* `DOCS_REQ`: tell the customer that more documents are needed
* `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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.