> ## 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.

# Deposit funds

> Create a hosted payment link so a user can add funds to their account.

<Note>
  Requires `Authorization: Bearer <user-access-token>` — the token from [Verify login code](/api-reference/users/verify-otp). No `X-Api-Key`, `X-Api-Secret`, or `userId` — the token already identifies the user.
</Note>

Creates a hosted payment link for a user deposit. Send the returned `paymentLink` to your user so they can complete the payment with the selected provider.

The deposit is created with `status: "PENDING"`. The user's balance is updated after the payment is completed and confirmed by the provider.

```
Your backend calls POST /api/v1/transactions/deposit
    → Qash returns paymentLink
    → User completes payment
    → Deposit is confirmed asynchronously
```

<Tip>
  Call [`GET /api/v1/user/accounts`](/api-reference/account-management/list-accounts) first to get the user's `toAccountId`. The USDC account is provisioned automatically the first time the user logs in — you don't need to create it manually.
</Tip>

## Request

```http theme={null}
POST /api/v1/transactions/deposit
Authorization: Bearer <user-access-token>
Content-Type: application/json
```

### Body

| Field                           | Type   | Required | Description                                                                                                                   |
| ------------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `toAccountId`                   | number | **Yes**  | Account ID that will receive the deposit — use the `id` from [List accounts](/api-reference/account-management/list-accounts) |
| `amount`                        | number | **Yes**  | Decimal amount in USDC (e.g. `100` = USDC 100.00) — not a smallest-unit integer                                               |
| `currency`                      | string | **Yes**  | Currency code matching the account's asset — `"USDC"`                                                                         |
| `provider`                      | string | **Yes**  | Payment provider — e.g. `"mock"`, `"irisbank"`, `"cobre"`, `"stripe"`                                                         |
| `description`                   | string | **Yes**  | Description of the deposit — e.g. `"USDC deposit"`                                                                            |
| `metadata.payer.documentType`   | string | **Yes**  | Payer document type — e.g. `"CC"`, `"PASSPORT"`, `"RFC"`                                                                      |
| `metadata.payer.documentNumber` | string | **Yes**  | Payer document number                                                                                                         |

```json theme={null}
{
  "toAccountId": 659,
  "amount": 100,
  "currency": "USDC",
  "provider": "mock",
  "description": "USDC deposit",
  "metadata": {
    "payer": {
      "documentType": "passport",
      "documentNumber": "A1234567"
    }
  }
}
```

## Response

**201 Created**

```json theme={null}
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "inferredTransactionType": "DEPOSIT",
  "paymentLink": "/api/pay/1234?transactionId=550e8400-e29b-41d4-a716-446655440000&amount=100&currency=USDC",
  "message": "Transaction enqueued for processing"
}
```

| Field           | Type          | Description                                         |
| --------------- | ------------- | --------------------------------------------------- |
| `transactionId` | string (UUID) | Deposit transaction identifier — use to poll status |
| `status`        | string        | `"PENDING"` while the user completes the payment    |
| `paymentLink`   | string        | Hosted payment URL to share with the user           |

<Info>
  Amounts are decimal USDC values (e.g. `100` = USDC 100.00), not smallest-unit integers. Never use floating point arithmetic to compute the value before sending it.
</Info>

## Errors

| HTTP status | Error                                                      | Cause                                                       |
| ----------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
| `400`       | Validation message                                         | Missing required field or invalid format                    |
| `400`       | `description must be a string`                             | `description` field missing from body                       |
| `400`       | `Payer information is required for deposits`               | `metadata.payer` missing from body                          |
| `400`       | `Payer document type and number are required for deposits` | `metadata.payer.documentType` or `documentNumber` missing   |
| `401`       | `Invalid or expired token`                                 | Missing, expired, or malformed access token                 |
| `404`       | `Account not found`                                        | `toAccountId` does not exist or belongs to a different user |