Issue a card

Requires Authorization: Bearer <user-access-token> — the token from Verify login code. No X-Api-Key/X-Api-Secret needed; this is a post-login endpoint.

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 and logged in via 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).
The user’s personal 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

POST /api/v1/auth/cards/setup
Authorization: Bearer <user-access-token>
Content-Type: application/json

{
  "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 until it reports active.

{
  "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:

{
  "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 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

Once the card is issued, use Get card status, Get card details, and the rest of the Cards endpoints — all authenticated with the same access token.

Exchange rates / TRM

Cards

Users

Login

User profile

KYC

Account Management

Financials

Prerequisites

Request

Response — 202 Accepted

Errors

​Prerequisites

​Request

​Response — 202 Accepted

​Errors

Prerequisites

Request

Response — 202 Accepted

Errors