Issue card

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

curl --location --request POST '/cards/issue' \ --header 'idempotency-key;' \ --header 'Content-Type: application/json' \ --data-raw '{ "account_id": "b2c3d4e5-f6a7-5890-b123-c4d5e6f7a8b9", "type": "individualVirtualDebitCard", "pin": "1357" }'

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

Request

Responses