Create Card

user_id = the usr_... ID returned by Create User (required — it determines which user the card belongs to).

ASYNC: the card fee is reserved from your tenant balance immediately and the response is 202 Accepted with status: "pending" — the response contains no PAN and no masked PAN yet. The card is issued on our queue; when it completes you receive a card.created webhook (or card.creation_failed — see the Webhooks folder), or poll GET /cards/{id} until pending becomes active/failed.

If your balance is insufficient, the request fails immediately and synchronously (422 insufficient_balance) — nothing is queued.
If the provider declines, the fee is refunded automatically and the card becomes failed (webhook card.creation_failed, data.reason).

Replaying the same Idempotency-Key returns the stored first 202 — the card is NOT reserved twice.

⚠️ PAN/CVV are only ever available from GET /cards/{id}/details (once the card is active).

Mock scenario: if the user's first_name="DECLINE" → webhook card.creation_failed (reason: card_declined).

curl --location 'https://api.paylandcard.com/api/v1/cards' \ --header 'X-Api-Key: {{api_key}}' \ --header 'X-Timestamp: {{timestamp}}' \ --header 'X-Signature: {{signature}}' \ --header 'Accept: application/json' \ --header 'Idempotency-Key: {{$guid}}' \ --header 'Content-Type: application/json' \ --data '{ "user_id": "{{user_id}}", "currency": "USD" }'

{ "data": { "id": "card_01kx0hqyr1v9ravmyhqdwzky7c", "user_id": "usr_01kx0hq7p3y52m0fbwn4gftzht", "brand": null, "masked_pan": null, "last4": null, "exp_month": null, "exp_year": null, "status": "pending", "balance": 0, "currency": "USD", "created_at": "2026-07-08T12:01:00+00:00" }, "status": true }

Request

Responses