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.

cardFindings is here too when the photos showed something you should know — see trade.succeeded.

failure.kind is one of already_redeemed, invalid, duplicate (also: a certain repeat of a card that sold, is in progress, or was rejected — closed before any vendor saw it), wrong_card, unreadable, blocked (zombie card), not_active, vendor_refused, other.

failure.class says whether it was the card’s fault: card_dead, card_problem, not_active, resend, vendor_refused. failure.retryable: true means the card may be fine — the customer can submit it again and Kardlane won’t treat it as a repeat. See Failure reasons.

failure.proof is the vendor’s own evidence: their screenshots (type: "image", download from url with your API key) and words (type: "text", card codes masked). Attach it if you mark cards as bad.

failure.duplicateOf: for a repeat card, your externalRef of the earlier sale it repeats.

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 balance is $0",
      "class": "card_dead",
      "retryable": false,
      "proof": [
        {
          "type": "image",
          "mediaId": "9b2f…",
          "url": "https://api.kardlane.com/v1/trades/6abea25d-…/media/9b2f…",
          "at": "2026-10-03T09:20:41.000Z",
          "caption": "balance check"
        },
        {
          "type": "text",
          "text": "used …4F2K",
          "at": "2026-10-03T09:20:44.000Z"
        }
      ]
    },
    "evidence": {},
    "idempotencyKey": "b1e2…:6abe…:failed"
  }
}