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

# Issue a card

> Create a RainCards application and issue the user's card after KYC is approved.

<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` needed; this is a post-login endpoint.
</Note>

Creates a RainCards application for the authenticated user and issues their card. This is the last step of the partner flow, after the user has completed [KYC](/api-reference/users/start-kyc) and logged in via [OTP](/api-reference/users/verify-otp).

## Prerequisites

Qash validates all of the following before creating the application. If any is missing, the request fails with `422` rather than partially creating the card:

* The user has an **approved** KYC verification (see [KYC status](/api-reference/users/kyc-status)).
* The user's [personal profile](/api-reference/users/get-profile) is complete — name, date of birth, government ID, and address.
* The user does not already have a card application in progress or issued.
* The user's Qash wallet address has been provisioned. This happens automatically shortly after registration; if you call this endpoint immediately after login, retry after a few seconds if you hit the `wallet not ready` error below.

## Request

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

```json theme={null}
{
  "cardType": "virtual",
  "occupation": "engineer",
  "annualSalary": "50000-100000",
  "accountPurpose": "personal_savings",
  "expectedMonthlyVolume": "5000-10000"
}
```

| Field                   | Type   | Required | Description                                                      |
| ----------------------- | ------ | -------- | ---------------------------------------------------------------- |
| `cardType`              | string | Yes      | `"virtual"` or `"physical"`                                      |
| `occupation`            | string | Yes      | User's occupation                                                |
| `annualSalary`          | string | Yes      | Salary bracket, e.g. `"50000-100000"`                            |
| `accountPurpose`        | string | Yes      | Intended use of the account, e.g. `"personal_savings"`           |
| `expectedMonthlyVolume` | string | Yes      | Expected monthly transaction volume bracket, e.g. `"5000-10000"` |

## Response — 202 Accepted

The application is created asynchronously with Rain. A `202` means the request was accepted, not that the card is immediately active — poll [Get card status](/api-reference/cards/status) until it reports `active`.

```json theme={null}
{
  "success": true,
  "message": "Application submitted successfully. Your card will be created once approved.",
  "applicationId": "bfc7083b-75a2-11f1-86bf-42010a400007",
  "status": "pending"
}
```

| Field           | Type    | Description                                                       |
| --------------- | ------- | ----------------------------------------------------------------- |
| `success`       | boolean | `true` when the application was accepted                          |
| `message`       | string  | Human-readable confirmation message                               |
| `applicationId` | string  | Qash's internal application record ID — not Rain's application ID |
| `status`        | string  | Application status — e.g. `"pending"`                             |

## Errors

All error responses share this shape:

```json theme={null}
{
  "statusCode": 422,
  "error": "BUSINESS_RULE_VIOLATION",
  "message": "Approved Persona KYC verification required before creating a RainCards application",
  "requestId": "...",
  "timestamp": "2026-07-14T12:00:00.000Z"
}
```

| HTTP status | Message                                                                              | Cause                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `400`       | Validation message                                                                   | Missing or invalid field in the request body                                                                     |
| `401`       | `Invalid or expired token`                                                           | Missing, expired, or malformed access token                                                                      |
| `404`       | `PersonalProfile not found: <userId>`                                                | No personal profile exists for this user — call [Create user profile](/api-reference/users/create-profile) first |
| `409`       | `RainCards application already exists with status: <status>`                         | This user already has a card application, regardless of its status                                               |
| `422`       | `Approved Persona KYC verification required before creating a RainCards application` | The user's KYC verification is missing or not yet `approved`                                                     |
| `422`       | `Approved KYC is missing Persona inquiry ID (personaShareToken)`                     | KYC is approved but missing an expected Persona reference                                                        |
| `422`       | Profile-field-specific message (name, date of birth, government ID, or address)      | The personal profile is missing one of these required fields                                                     |
| `422`       | `User wallet address not available yet`                                              | The user's wallet address has not been provisioned yet — retry shortly                                           |

<Tip>
  Once the card is issued, use [Get card status](/api-reference/cards/status), [Get card details](/api-reference/cards/details), and the rest of the [Cards](/api-reference/cards/introduction) endpoints — all authenticated with the same access token.
</Tip>