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.escalatedwith areviewtelling 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.succeededcarriesagreed,settledand a list ofdiscrepancies. 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_changedand 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#
- 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.failedwithfailure.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 withblockedBy: ["low_balance"]. - 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”).
- 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.
- 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.
- The checks
A verdict closes the trade only if every check below passes. The ones that failed are listed in
review.blockedByon the escalation.
The checks#
| blockedBy value | Applies to | What it means |
|---|---|---|
trusted_vendor | success, failure | The 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_enabled | success, failure | Automatic decisions are switched off for this project. |
value_cap | success | The card value is above your auto-approve limit. |
confidence | AI reads | The AI was less sure than your threshold (success 95%, failure 85% by default). |
evidence_grounded | AI reads | Something the AI cited isn’t actually in the vendor’s messages. |
verifier_agrees | AI reads | The independent second pass disagreed or didn’t answer. |
unambiguous_card | all | Another similar card of yours is open with the same vendor and the reply isn’t tied to this one. |
no_failure_signal | success | The vendor also wrote something that reads as a failure (“invalid”, “used”). |
rate_plausible | credit lines | The 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_rate | AI success | The amount the vendor stated is below the agreed rate. |
value_exact | AI success | The value the vendor stated differs from the card’s. |
country_match | AI success | The vendor named another country than the card’s. |
code_echo | AI success | The vendor typed a code that doesn’t match the card’s. |
rate_in_band | AI success | The rate is outside the sane range for your customer rate. |
redeemed_values_known | partial | Several cards, only some redeemed, and a redeemed card’s value is unknown. |
low_balance | before sending | Your Kardlane balance can’t cover the fee — the card was not sent. |
["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).
| discrepancy | Example | Typical handling |
|---|---|---|
rate_lower | Agreed 1,140, credited at 1,130 | Pass the drop on, or absorb it — your policy. |
rate_higher | Credited above the agreed rate | Usually keep your customer’s quote. |
value_partial | $20 of a $25 card loaded | Pay 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_higher | Credited more than the card | Rare; worth a look. |
currency_changed | Loaded as a CAD card, not USD | Re-price at your rate for the actual currency. |
card_type_changed | Loaded as another card | Usually a person decides. |
Default thresholds#
| Setting | Default | Where |
|---|---|---|
| Rate window | 180 s (closes early when every vendor answered) | Project settings |
| Confirmation timeout | 10 min, per card type override | Project settings → timing |
| AI success / failure confidence | 95% / 85% | Project settings → AI |
| Second-pass verifier | required | Project settings → AI |
| Auto-fail needs a trusted vendor | yes | Project settings → AI |
| Trades before a vendor is trusted | 10 completed | Per vendor |
| Auto-approve value cap | none | Project settings |
| Wait for the rest of a partial credit | 10 min (0 settles at once) | Project settings → timing |
| Watching for changes after close | 48 h | Fixed |
Next: the scenario map walks through real situations, and Building your integration shows a complete handler.