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

# Payout

> Send funds from a user's Qash balance to an external destination.

<Note>
  Requires `Authorization: Bearer <user-access-token>` — the token from [Verify login code](/api-reference/users/verify-otp). See [Authentication](/api-reference/financials/introduction#authentication) for details.
</Note>

Initiates a payout to an external destination. The `transactionId` field acts as an idempotency key — use a unique UUID per operation to safely retry requests without creating duplicate payouts.

Payouts are asynchronous. A successful response means the request was accepted for processing; use transaction status endpoints or partner notifications to track the final result.

## Request

```http theme={null}
POST /api/v1/user/payout
Authorization: Bearer <user-access-token>
```

### Body

| Field                             | Type   | Required | Description                                                                                                     |
| --------------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `transactionId`                   | string | Yes      | UUID idempotency key — unique per operation                                                                     |
| `amount`                          | number | Yes      | Decimal amount in the destination asset's major unit (e.g. `5000` = COP 5,000.00) — not a smallest-unit integer |
| `asset`                           | string | Yes      | Asset to send — e.g. `"COP"`                                                                                    |
| `description`                     | string | No       | Optional description                                                                                            |
| `provider`                        | string | Yes      | Payment provider — e.g. `"cobre"` or `"irisbank"`                                                               |
| `source`                          | object | Yes      | Funding account information provided during setup                                                               |
| `destination.accountNumber`       | string | Yes      | Bank account number                                                                                             |
| `destination.accountType`         | string | Yes      | `"H"` (savings) or `"C"` (checking)                                                                             |
| `destination.bankName`            | string | No       | Bank name                                                                                                       |
| `destination.bankNumber`          | string | No       | Bank code                                                                                                       |
| `destination.ownerName`           | string | Yes      | Account holder full name                                                                                        |
| `destination.ownerDocumentType`   | string | Yes      | `"CC"`, `"CE"`, `"NIT"`, `"PA"`, or `"PPT"`                                                                     |
| `destination.ownerDocumentNumber` | string | Yes      | Document number                                                                                                 |

```json theme={null}
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 5000,
  "asset": "COP",
  "description": "Bank withdrawal",
  "provider": "cobre",
  "source": {
    "metadata": {
      "cobreId": "src_abc123"
    }
  },
  "destination": {
    "accountNumber": "1234567890",
    "accountType": "H",
    "bankName": "Bancolombia",
    "bankNumber": "007",
    "ownerName": "Juan Pérez",
    "ownerDocumentType": "CC",
    "ownerDocumentNumber": "1234567890"
  }
}
```

## Response

**200 OK**

```json theme={null}
{
  "success": true,
  "paymentId": "pay_abc123",
  "status": "PROCESSING",
  "message": "Payout accepted"
}
```

| Field       | Type    | Description                                                        |
| ----------- | ------- | ------------------------------------------------------------------ |
| `success`   | boolean | `true` when the payout was accepted                                |
| `paymentId` | string  | Provider payment identifier                                        |
| `status`    | string  | Current processing status — commonly `"PENDING"` or `"PROCESSING"` |
| `message`   | string  | Human-readable processing message, when available                  |

<Info>
  Payouts are processed asynchronously. An accepted request is not the same as final settlement. Poll [Get transaction](/api-reference/financials/transaction-detail) or listen for partner notifications to track the final status.
</Info>