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

# Crypto Payout

> Spend your MID's VND balance to send a stablecoin to a recipient wallet.

The Crypto Payout endpoint lets a partner spend the VND balance accumulated on their merchant (MID) account to send a stablecoin (e.g. USDT, USDC) to any recipient wallet.

Orders are created in a pending state awaiting Holdstation Pay operator approval — **no VND is debited at create time**. Once approved, Holdstation Pay debits the VND from your MID balance and broadcasts the on-chain stablecoin transfer to the recipient.

<Note>
  The target `token_address` must reference a stablecoin (token with `token_type=STABLECOIN`). Use the [List Tokens](/api-reference/tokens/list-tokens) endpoint to discover supported stablecoins per chain.
</Note>

## Workflow

1. **Check VND balance** — confirm the MID has enough VND via [Get MID Balance](/api-reference/mid/get-balance).
2. **Pick the destination** — choose the target chain and stablecoin contract.
3. **Create the payout order** — call [Create Crypto Payout](/api-reference/mid/crypto-payout) with the spend amount (in VND or token), the recipient wallet address, and a `callback` URL. Use a unique `idempotency_key` for every distinct payout to avoid duplicates.
4. **Wait for operator approval** — the order starts in a pending state. Holdstation Pay operators review and approve.
5. **Receive status webhooks** — the configured `callback` receives [Orders Webhook](/guides/webhooks/orders-webhook) events as the order moves through approval, on-chain submission, confirmation, or failure.

```mermaid theme={null}
sequenceDiagram
    actor P as Partner
    participant H as Holdstation Pay
    participant O as Operator
    participant B as Blockchain
    actor R as Recipient

    P->>+H: POST /partners/orders/crypto-payout
    Note over P, H: amount + currency + token_address + recipient + callback
    H-->>-P: Returns {order} (state = Created, awaiting approval)
    O->>H: Approve order
    H-->>H: Debit MID VND balance
    H->>+B: Broadcast stablecoin transfer
    B-->>R: Receive stablecoin
    B-->>-H: Confirm on-chain transfer
    H-->>P: (via callback) Order Completed
```

## Processing States

Crypto payout orders move through a dedicated processing-state set. State updates are delivered to your configured `callback` as [Orders Webhook](/guides/webhooks/orders-webhook) events.

| Processing State     | Value | Description                                            |
| -------------------- | ----- | ------------------------------------------------------ |
| Waiting For Approval | 40    | Created; awaiting Holdstation operator to settle       |
| Crypto Pending       | 41    | Token send submitted on-chain; awaiting confirmation   |
| Crypto Confirmed     | 42    | Token transfer confirmed on-chain                      |
| Crypto Failed        | 43    | Token transfer failed; VND refunded, re-settle allowed |
| Crypto Queued        | 44    | VND debited; crypto send queued for transferring       |

```mermaid theme={null}
stateDiagram-v2
    state "State -> Completed" as C
    state "State -> Failed" as F
    state "State -> Closed" as CL
    state "Waiting For Approval = 40" as WA
    state "Crypto Queued = 44" as CQ
    state "Crypto Pending = 41" as CP
    state "Crypto Confirmed = 42" as CC
    state "Crypto Failed = 43" as CF

    [*] --> WA: POST /partners/orders/crypto-payout
    WA --> CQ: Operator approves; VND debited
    WA --> CL: Expired or closed manually
    CQ --> CP: Crypto send submitted on-chain
    CP --> CC: Transfer confirmed
    CC --> C
    CP --> CF: Transfer failed
    CF --> F
    Note right of CF: VND refunded; operator may re-settle
    F --> [*]
    C --> [*]
    CL --> [*]
```

## Currency Modes

The `currency` field controls how `amount` is interpreted:

| `currency` | Meaning                                                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `vnd`      | Spend exactly this many VND from the MID balance. The amount of stablecoin sent is derived from the live rate. Default. |
| `token`    | Send exactly this many tokens to the recipient. The VND debit is derived from the live rate.                            |

## Idempotency

Always send a unique `idempotency_key` for each distinct payout. You can pass it either in the request body or via the `X-Idempotency-Key` header. Replaying the same key returns the original order instead of creating a new one.

## Authentication

All requests require Ed25519 request signing. See [Request Signing](/guides/partner-authentication-signed-api/overview).