Kardlane
Webhook event

trade.escalated

A person needs to decide — the agent wasn’t sure, a check held it back (e.g. the vendor isn’t trusted yet), the vendor redeemed only some cards, or someone stopped the bot. review carries the agent’s conclusion and how to resolve it via the API.

review.suggestedVerdict is succeeded, failed, partial or null (couldn’t tell).

review.partial lists each card’s outcome when only some were redeemed; Kardlane’s fee applies to the verified-redeemed cards however you resolve.

review.requote is set when the vendor re-quoted after the card went out and the new rate wasn’t accepted automatically.

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.escalated",
  "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": "escalated",
    "reason": "Partial: 1 of 2 cards redeemed (value 100 of 150)",
    "review": {
      "suggestedVerdict": "partial",
      "confidence": 0.96,
      "failureKind": null,
      "failure": null,
      "partial": {
        "cards": [
          {
            "codeLast4": "1111",
            "value": 100,
            "status": "redeemed",
            "failureKind": null
          },
          {
            "codeLast4": null,
            "value": 50,
            "status": "failed",
            "failureKind": "already_redeemed"
          }
        ],
        "redeemedCount": 1,
        "totalCards": 2,
        "redeemedValue": 100,
        "totalValue": 150
      },
      "requote": null,
      "blockedBy": [],
      "summary": "The vendor credited the $100 card and reported the $50 card as used.",
      "reviewUrl": "https://kardlane.com/t/6abea25d-0c1f-4a43-9d1e-3b5c2f0edad5",
      "resolve": {
        "method": "POST",
        "url": "https://api.kardlane.com/v1/trades/6abea25d-0c1f-4a43-9d1e-3b5c2f0edad5/resolve",
        "verdicts": [
          "succeeded",
          "failed",
          "cancelled"
        ]
      }
    },
    "evidence": {},
    "idempotencyKey": "b1e2…:6abe…:escalated"
  }
}