# Payland Card

## Docs
- [Authentication](https://docs.paylandcard.com/authentication-2260420m0.md): 
- [Webhooks (Payland → your server)](https://docs.paylandcard.com/webhooks-payland-your-server-9660097f0.md): Payland Card notifies YOUR endpoint when asynchronous work completes. Setup: partner portal (`https://portal.paylandcard.com` → **Webhook Ayarları**) → define your HTTPS endpoint URL and generate the **signing key**.

## API Docs
- Users [Create User](https://docs.paylandcard.com/create-user-40214379e0.md): Registers the end user a card will be issued for. Store the returned `data.id` (usr_...) on YOUR side — card creation is done with this ID. A successful response is written to the {{user_id}} variable automatically.
- Users [Get User](https://docs.paylandcard.com/get-user-40214380e0.md): Only users belonging to your tenant are visible; another tenant's ID returns 404.
- Users [City Codes](https://docs.paylandcard.com/city-codes-40214381e0.md): Valid city codes for the `town` field of Create User. Query param `country` is a 2-letter ISO code (default TR). Cached server-side for 24h.
- Cards [Create Card](https://docs.paylandcard.com/create-card-40214382e0.md): user_id = the usr_... ID returned by Create User (required — it determines which user the card belongs to).
- Cards [Get Card](https://docs.paylandcard.com/get-card-40214383e0.md): Masked view of the card + status + balance. Card statuses: `pending` (issuing in progress — just after the 202), `active`, `frozen`, `failed` (creation failed — fee refunded), `deleted`. Poll this endpoint after Create Card if you prefer not to consume webhooks. A deleted card is still readable (status: deleted).
- Cards [Load Funds](https://docs.paylandcard.com/load-funds-40214384e0.md): Amount is in minor units (25000 = 250.00 USD). It is deducted from your tenant balance and added to the card balance (+ a load fee, if configured).
- Cards [Card Transactions](https://docs.paylandcard.com/card-transactions-40214385e0.md): Card transaction history, newest first. Types: load (top-up), unload (delete refund), fee, spend/refund (card purchases — via provider). Query params: page (default 1), page_size (default 20, max 100). History of a deleted card remains readable.
- Cards [Freeze Card](https://docs.paylandcard.com/freeze-card-40214386e0.md): Idempotent: freezing an already-frozen card is not an error (still returns 200/frozen).
- Cards [Unfreeze Card](https://docs.paylandcard.com/unfreeze-card-40214387e0.md): 
- Cards [Card Details](https://docs.paylandcard.com/card-details-40214388e0.md): ⚠️ Sensitive endpoint: 10 calls per minute per API key. The response carries Cache-Control: no-store — do NOT store or log the PAN/CVV; display it to the user and discard. Every call is written to an audit log on our side.
- Cards [Delete Card](https://docs.paylandcard.com/delete-card-40214389e0.md): The card is terminated at the provider; any remaining card balance is automatically refunded to your tenant balance (refunded_amount). Irreversible.
- Webhooks (Payland → your server) [SIMULATE card.created](https://docs.paylandcard.com/simulate-card-created-40214390e0.md): Sends a signed, production-identical `card.created` delivery to {{webhook_url}}. Set the `webhook_url` and `webhook_secret` collection variables first (the signature is computed with `webhook_secret`). Your endpoint should: verify the signature over the RAW body → respond 2xx quickly → activate the card on your side (match by `data.id` = the card_... you stored at Create Card).
- Webhooks (Payland → your server) [SIMULATE card.creation_failed](https://docs.paylandcard.com/simulate-card-creation-failed-40214391e0.md): Sends a signed `card.creation_failed` delivery to {{webhook_url}}. `data.reason` explains the failure (e.g. card_declined, kyc_rejected, provider_unavailable). The card creation fee was already refunded to your tenant balance automatically — no action needed on billing; just mark the card failed on your side.