Issue a card
curl --request POST \
--url https://api.example.com/api/v1/auth/cards/setupconst options = {method: 'POST'};
fetch('https://api.example.com/api/v1/auth/cards/setup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.example.com/api/v1/auth/cards/setup"
response = requests.post(url)
print(response.text)Cards
Issue a card
Create a RainCards application and issue the user’s card after KYC is approved.
POST
/
api
/
v1
/
auth
/
cards
/
setup
Issue a card
curl --request POST \
--url https://api.example.com/api/v1/auth/cards/setupconst options = {method: 'POST'};
fetch('https://api.example.com/api/v1/auth/cards/setup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.example.com/api/v1/auth/cards/setup"
response = requests.post(url)
print(response.text)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.Prerequisites
Qash validates all of the following before creating the application. If any is missing, the request fails with422 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 readyerror 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. A202 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.