Issue card - vrtx Docs

Issues a new card for an eligible wallet holder associated with the specified account.

Body Parameters:

Exactly one of account_id or account_reference_id must be provided

idempotency-key header (UUID) is required to deduplicate issuance requests

pin (optional): 4-digit numeric PIN to set during issuance. Must not be sequential (e.g., 1234) or repeated (e.g., 1111)
PIN Validation Rules:

Must be exactly 4 digits

Must be numeric only

Cannot be sequential (e.g., 1234, 5678)

Cannot be repeated (e.g., 1111, 2222)

Error Responses:

400 INVALID_INPUT: Invalid PIN format, weak PIN (sequential/repeated), or invalid request body

400 INVALID_CITY: Invalid city provided. City must be one of the valid Saudi cities

400 INVALID_REQUEST: Missing required information (e.g., emboss name for physical cards)

404 ACCOUNT_NOT_FOUND: Specified account does not exist

409 CARD_LIMIT_REACHED: Account has reached the maximum number of cards

409 CARD_TYPE_CONFLICT: Account already has an active physical card. Only one active physical card is allowed per account

503 SERVICE_UNAVAILABLE: Service temporarily unavailable

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Header Params

Body Params application/json

Examples

example1example2example3

{
    "account_id": "b2c3d4e5-f6a7-5890-b123-c4d5e6f7a8b9",
    "type": "individualVirtualDebitCard",
    "pin": "1357"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Default Response

Body

Examples

example1example2

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z",
    "account_id": "b2c3d4e5-f6a7-5890-b123-c4d5e6f7a8b9",
    "account_number": "ACC-2024-00123",
    "customer_id": "c3d4e5f6-a7b8-9012-c345-d6e7f8a9b0c1",
    "status": "ISSUED",
    "idempotency_key": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
    "card": {
        "id": "f5a4b3c2-d1e0-9876-5432-1a0b9c8d7e6f",
        "account_id": "b2c3d4e5-f6a7-5890-b123-c4d5e6f7a8b9",
        "token": 987654321,
        "status": "ACTIVE",
        "last_4_digits": "1234",
        "expiry_date": "2027-12-31",
        "design": "standard",
        "created_at": "2024-01-15T10:35:00Z",
        "updated_at": "2024-01-15T10:35:00Z"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Not Found

🟠405Method Not Allowed

🟠409Conflict

🟠410Gone

🟠422Unprocessable Entity

🟠429Too Many Requests

🔴500Internal Server Error

🔴501Not Implemented

🔴503Service Unavailable

🔴504Gateway Timeout

🔴505HTTP Version Not Supported