Kardlane
Decisions

How Kardlane decides

The principles, the pipeline and every check behind a verdict — so you know exactly when Kardlane acts on its own and when it hands a trade to you.

Vendors don’t speak an API. They reply in WhatsApp with numbers, shorthand, screenshots, bot ledgers and the occasional “wait”. Kardlane turns that into a verdict your system can act on. This page explains how, so you can design your side around it.

Five principles#

  • Sure → decide. Unsure → hand it to you. Kardlane closes a trade on its own only when the evidence is unambiguous and every check passes. Anything else becomes trade.escalated with a review telling you what it concluded and why it stopped.
  • A success is reported as it actually happened. If the vendor paid a lower rate, loaded only part of the value, or loaded it as another currency, the trade still succeeded — trade.succeeded carries agreed, settled and a list of discrepancies. Kardlane doesn’t decide what you pay your customer; it gives you everything to decide.
  • Prices only come from the vendor, for this trade. A rate is taken only from the vendor’s reply to Kardlane’s question about this card — never from an earlier trade or a broadcast price list. (A price list sent as the reply counts, if the price for this card can be read from it.)
  • A closed trade is never flipped. Money has moved. If the vendor changes its word later, you get trade.verdict_changed and the trade stays as it was.
  • Everything is kept. Every vendor message, every reading, the agreed and settled terms and each check’s result are stored on the trade — the record you can point to if anything is disputed.

The pipeline#

  1. Before any vendor sees the card

    Kardlane reads the card photos (or e-code) and checks its history. A card that is certainly a repeat — same photo or same code as one that already sold, is in progress, or was rejected as used — is not sent: the trade closes as trade.failed with failure.kind: "duplicate" (or escalates, if your project prefers). Cards rejected only because they weren’t active yet, were unreadable, or one vendor wouldn’t take them don’t count as repeats. If your prepaid balance is too low, it escalates with blockedBy: ["low_balance"].

  2. Asking for rates

    Every vendor that takes this card type and country is asked, in the format that vendor expects. The window (default 180 s) closes early once every vendor has quoted or clearly declined (“no need”, “pause Apple”). Quotes are read by code first and by the AI only when needed; every number used must appear in the vendor’s words. The best rate that passes your margin wins; ties go by your vendor priority, then reliability. No usable quote → escalated (“No vendor quoted”).

  3. Sending the card

    The card goes to the chosen vendor and the confirmation clock starts (default 10 minutes, set per card type — slow cards like Sephora can be given hours). A stated wait (“wait 40 mins”, “1–3h”) extends it, up to a limit.

  4. Reading the outcome

    First, the ledger check: vendors and their bookkeeping bots usually post a credit line — +25*1130#IT-US-/…AB12+25/, or one total for several cards (CODE1/50 CODE2/50+100*1145). A credit line tied to this card (by its code ending, a reply to it, or because it’s the only card of yours open with that vendor) is the verdict — read exactly, no AI. Bot echoes and replays count only when they carry this card’s code.

    Otherwise the AI reads the conversation (text, screenshots, quoted replies) and proposes a verdict with citations. Code then checks every citation is real — the quoted words are in that message — and an independent second pass must agree.

  5. The checks

    A verdict closes the trade only if every check below passes. The ones that failed are listed in review.blockedBy on the escalation.

The checks#

blockedBy valueApplies toWhat it means
trusted_vendorsuccess, failureThe vendor isn’t marked trusted and hasn’t completed enough trades to earn it (default 10). The most common reason. Mark reliable vendors trusted.
auto_approval_enabledsuccess, failureAutomatic decisions are switched off for this project.
value_capsuccessThe card value is above your auto-approve limit.
confidenceAI readsThe AI was less sure than your threshold (success 95%, failure 85% by default).
evidence_groundedAI readsSomething the AI cited isn’t actually in the vendor’s messages.
verifier_agreesAI readsThe independent second pass disagreed or didn’t answer.
unambiguous_cardallAnother similar card of yours is open with the same vendor and the reply isn’t tied to this one.
no_failure_signalsuccessThe vendor also wrote something that reads as a failure (“invalid”, “used”).
rate_plausiblecredit linesThe credited rate is too far from what was agreed to be a price — treated as a misread; no terms are reported from it.
paid_at_agreed_rateAI successThe amount the vendor stated is below the agreed rate.
value_exactAI successThe value the vendor stated differs from the card’s.
country_matchAI successThe vendor named another country than the card’s.
code_echoAI successThe vendor typed a code that doesn’t match the card’s.
rate_in_bandAI successThe rate is outside the sane range for your customer rate.
redeemed_values_knownpartialSeveral cards, only some redeemed, and a redeemed card’s value is unknown.
low_balancebefore sendingYour Kardlane balance can’t cover the fee — the card was not sent.
Tip: Most escalations are ["trusted_vendor"] alone with a confident suggestedVerdict. You can accept those automatically on your side — or mark the vendor trusted and Kardlane will close them itself.

Agreed vs settled#

Every success carries what was agreed with the vendor and what the vendor actually did. vendorRate and margin at the top level of trade.succeeded are the settled figures, and Kardlane’s fee follows them (no fee when the margin is zero or below).

discrepancyExampleTypical handling
rate_lowerAgreed 1,140, credited at 1,130Pass the drop on, or absorb it — your policy.
rate_higherCredited above the agreed rateUsually keep your customer’s quote.
value_partial$20 of a $25 card loadedPay for what loaded. Kardlane waits for a second credit first (10 minutes by default; Settings → Timing). With several cards, a credit for some of them waits for the others until the confirmation timeout, then comes to you.
value_higherCredited more than the cardRare; worth a look.
currency_changedLoaded as a CAD card, not USDRe-price at your rate for the actual currency.
card_type_changedLoaded as another cardUsually a person decides.

Default thresholds#

SettingDefaultWhere
Rate window180 s (closes early when every vendor answered)Project settings
Confirmation timeout10 min, per card type overrideProject settings → timing
AI success / failure confidence95% / 85%Project settings → AI
Second-pass verifierrequiredProject settings → AI
Auto-fail needs a trusted vendoryesProject settings → AI
Trades before a vendor is trusted10 completedPer vendor
Auto-approve value capnoneProject settings
Wait for the rest of a partial credit10 min (0 settles at once)Project settings → timing
Watching for changes after close48 hFixed

Next: the scenario map walks through real situations, and Building your integration shows a complete handler.