Payland Card
    • Authentication
    • Users
      • Create User
        POST
      • Get User
        GET
      • City Codes
        GET
    • Cards
      • Create Card
        POST
      • Get Card
        GET
      • Load Funds
        POST
      • Card Transactions
        GET
      • Freeze Card
        POST
      • Unfreeze Card
        POST
      • Card Details
        GET
      • Delete Card
        DELETE
    • Webhooks (Payland → your server)
      • SIMULATE card.created
        POST
      • SIMULATE card.creation_failed
        POST

    Webhooks (Payland → your server)

    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.

    Event catalog#

    Live today:
    card.created — the card was issued and is ACTIVE (data: masked card view — never the PAN)
    card.creation_failed — issuing failed; the card fee was refunded automatically (data.reason: e.g. card_declined, kyc_rejected, provider_unavailable)
    card.frozen / card.unfrozen — card state was changed by the Payland operations team
    card.deleted — the card was deleted by the Payland operations team; data.refunded_amount carries the remaining balance refunded to your tenant balance
    Freeze/unfreeze/delete operations you perform through YOUR OWN API calls do NOT produce a webhook — you already receive the result synchronously. These events only notify out-of-band changes made on the Payland side.
    Planned (will be enabled later — announced before rollout):
    card.transaction.created — a spend/refund transaction was posted to a card
    ⚠️ Forward compatibility: new event types may be added over time. Your endpoint MUST respond 2xx and ignore event types it does not recognize (filter on X-Payland-Event / body event) — do not error on unknown events.

    Delivery format#

    Envelope: { "id": "evt_...", "event": "...", "created_at": "...", "data": { ... } }
    Headers on every delivery: X-Payland-Event, X-Payland-Delivery (unique delivery id — stable across retries), X-Payland-Signature: sha256=<hex> where <hex> = HMAC-SHA256(raw request body, signing key).
    Verify (PHP):
    Delivery guarantee: retried with exponential backoff (1 → 5 → 15 → then every 30 minutes) for 12 hours until your endpoint returns 2xx; afterwards the delivery is marked failed (visible in the portal under Webhook Ayarları → Son Teslimatlar). Respond fast (2xx within 10s) and process asynchronously on your side. Your endpoint must be idempotent — dedupe by X-Payland-Delivery or the body id.
    ⚠️ The payload NEVER contains PAN/CVV (only the masked form). For the full PAN use GET /cards/{id}/details.
    The two requests below SIMULATE our deliveries byte-for-byte (same headers, same signature algorithm) against your own webhook_url — point them at your staging receiver to test signature verification and idempotent handling before go-live.
    Modified at 2026-07-17 06:22:50
    Previous
    Delete Card
    Next
    SIMULATE card.created
    Built with