Integrate

Deciding escalations

Everything you need to decide a trade without opening the dashboard.

A trade escalates when the bot wants a person: the agent wasn’t sure, a safety check held it back (most often — the vendor isn’t trusted yet), the vendor redeemed only some cards, re-quoted lower than another vendor, or someone stopped the bot. Every trade.escalated carries a review block.

data.review

{
  "suggestedVerdict": "failed",
  "confidence": 0.95,
  "failureKind": "already_redeemed",
  "failure": {
    "kind": "already_redeemed",
    "message": "Card already redeemed"
  },
  "partial": null,
  "requote": null,
  "blockedBy": [
    "trusted_vendor"
  ],
  "summary": "Vendor marked it used; balance screenshot shows $0.05.",
  "reviewUrl": "https://kardlane.com/t/6abea25d-…",
  "resolve": {
    "method": "POST",
    "url": "https://api.kardlane.com/v1/trades/6abea25d-…/resolve",
    "verdicts": [
      "succeeded",
      "failed",
      "cancelled"
    ]
  }
}

Field	Meaning
`suggestedVerdict`	The agent’s conclusion: `succeeded`, `failed`, `partial`, or `null` when it couldn’t tell.
`blockedBy`	The checks that stopped an automatic close. Empty means it needs judgement.
`partial`	For several cards with only some redeemed: each card’s outcome and the redeemed value.
`requote`	The vendor re-quoted after the card went out and it wasn’t accepted automatically.
`resolve`	The exact API call that decides it.

A typical policy#

Accept suggestedVerdict automatically when blockedBy is only ["trusted_vendor"] and confidence ≥ 0.9.
Show everything else in your admin with buttons that call resolve.url.
Better still: mark reliable vendors as trusted in the dashboard, and their clear outcomes settle without you.

Partial redemptions#

When the vendor redeems only some of the cards, pay your customer for what was redeemed and resolve the trade however suits your books. If Kardlane verified the redeemed cards, its fee applies to their value whichever way you resolve — see Billing.

Resolving#

Resolve

curl -X POST https://api.kardlane.com/v1/trades/6abea25d-…/resolve \
  -H "Authorization: Bearer $KARDLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "verdict": "failed", "note": "approved by ops" }'