Kardlane
Webhook event

trade.failed

The vendor rejected the card. failure.message is a short reason you can show your customer as-is — written from what the vendor reported, with any card code removed.

failure.kind is one of already_redeemed, invalid, duplicate, wrong_card, unreadable, blocked (zombie card), other.

Delivery#

Sent as a signed POST to your project’s webhook URL — see the Webhooks guide to verify the signature. Delivery is at-least-once: dedupe on the X-Kardlane-Delivery header (or data.idempotencyKey).

Payload
{
  "id": "0f3c9a52-8d6e-4f0e-9b7a-2c1d5e8f4a10",
  "apiVersion": "2026-09-01",
  "type": "trade.failed",
  "createdAt": "2026-10-03T09:21:07.512Z",
  "tenantId": "b1e2c3d4-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "data": {
    "tradeId": "6abea25d-0c1f-4a43-9d1e-3b5c2f0edad5",
    "externalRef": "sale_8213",
    "projectId": "ac8b35cc-e64c-4062-96b9-4161a2a6c157",
    "settlementMode": "verdict_only",
    "cardType": "APPLE_ITUNES",
    "country": "USD",
    "value": 150,
    "customerRate": 1080,
    "vendorRate": 1150,
    "margin": 70,
    "vendor": "Vendor Alpha",
    "verdict": "failed",
    "failure": {
      "kind": "already_redeemed",
      "message": "Card already redeemed"
    },
    "evidence": {},
    "idempotencyKey": "b1e2…:6abe…:failed"
  }
}