Kardlane
Decisions

Scenario map

Real vendor situations, what Kardlane does with each, what you receive, and what to do.

Every row below happens in production. The vendor wording is real (codes shortened). Use it to make sure your handler covers each case.

Before the card is sent#

SituationKardlaneYou receiveWhat to do
The same card (same photo or code) already sold on an earlier tradeNot sent to any vendor; closedtrade.failed, kind: "duplicate", “This card was already sold”Reject; possible double sale.
The same card is already in progress, or was rejected as used beforeNot sent; closedtrade.failed, kind: "duplicate", the earlier reasonReject with failure.message.
The same card was rejected before only as “not active yet”, unreadable, or refused by one vendorTreated as a new attempt — sent normallyThe usual outcome—
Card type you sent isn’t supportedRejected at POST /v1/trades (400, with a suggestion); recorded so the Kardlane team sees demandHTTP 400Keep the sale with your staff.
Vendors decline (“no need”, “pause Apple for few days”) or don’t answerWindow closes early on clear declines; escalates if nobody quotestrade.escalated “No vendor quoted”Retry later or handle by hand.
Your prepaid balance is too lowNot senttrade.escalated, blockedBy: ["low_balance"]Top up; resolve by hand.

The vendor confirms#

SituationKardlaneYou receiveWhat to do
+25*1140#IT-US-/…AB12+25/ — credit with this card’s code, at the agreed rateSucceeds from the credit line — no AItrade.succeeded, discrepancies: []Pay your customer.
CODE1/50 CODE2/50+100*1145 — one total for two of your cardsSplit per card by code; each trade succeeds at 1,145Two trade.succeededPay each.
+25*1130… — agreed was 1,140Succeeds at 1,130; vendorRate/margin are the settled onestrade.succeeded with rate_lowerApply your rate-drop policy.
+20*1140… on a $25 cardWaits 10 min for the rest, then succeeds as partialtrade.succeeded with value_partialPay for 20.
Credit tagged #IT-CA on a USD cardSucceeds as loadedtrade.succeeded with currency_changedRe-price at your CAD rate.
“+100 done” — only card open with this vendorSucceeds at the agreed ratetrade.succeededPay.
“done” while two similar cards of yours are open with this vendorCan’t tell which — escalatestrade.escalated, unambiguous_cardCheck the vendor chat; resolve.
Clear success, but the vendor isn’t trusted yet / value above your cap / auto-approval offEscalates with the readtrade.escalated, suggestedVerdict: "succeeded", settled termsAccept per your policy, or mark the vendor trusted.
Credited rate wildly off (e.g. +25*2900 on a 1,140 deal)Treated as a misreadtrade.escalated, rate_plausible, no termsCheck with the vendor.

The vendor rejects#

SituationKardlaneYou receiveWhat to do
Balance screenshot showing $0, “used”Fails it (confident, grounded, verified, trusted vendor)trade.failed, failure.kind: "already_redeemed", message “Card balance is $0”Reject; show failure.message to your customer.
Same, but vendor not trusted (or the AI isn’t sure)Escalates with the readtrade.escalated, suggestedVerdict: "failed", review.failureReject if you agree.
“invalid” then later “done”Mixed signals — escalatestrade.escalated, no_failure_signalRead the chat.
“invalid… maybe not active yet”Fails it as retryabletrade.failed, kind: "not_active", retryable: trueReject; tell the customer to try again later.
“bro send again, we can’t see it”, “send clear and complete cards one by one”Crops each card out of the photos, turns it upright and sends one image per card (the card itself is never altered); if nothing needs cropping, sends the photos again onceNothing yet — then the usual verdict (still unreadable → trade.failed, kind unreadable, retryable). A flat image fee applies if the trade then succeeds—
“sceen card” / “Screen card not accepted” (the customer photographed the card on another phone)Sends the card — as the customer took it — to the vendors that have completed a screen photo for you before, highest quote first; if none has, the next-best vendorNothing yet — then the usual verdict. No vendor left → trade.failed, kind vendor_refused, retryableIf failed: ask the customer for a photo of the physical card.
“we don’t take this card”Sends the card to the next vendor that quoted for this trade, highest quote first (quotes from this trade only, not older than 30 min)Nothing yet — then the usual verdict. No vendor left → trade.failed, kind vendor_refused, retryable—
A dead card reported after the trade went to a personFails it if every check passestrade.failed (after your trade.escalated)Make sure staff stop working it.

See Failure reasons for failure.class and failure.retryable. Resending and re-routing can be switched off per project.

Every quote is too low (before sending)#

SituationKardlaneYou receiveWhat to do
All vendors quote, but even the best leaves less than your margin threshold (e.g. customer at 1,000, best quote 1,010, threshold 20) — negative margin OFFSends nothing; escalatestrade.escalated (“none passed the margin”) with lowMargin (bestQuote: 1010, and suggestedCustomerRate from your price list)Re-price your customer and resolve by hand, or raise your rate later.
Same — negative margin ONSends the card to the best quote anywaytrade.succeeded with lowMargin (stage: "selection", margin: 10)Re-price your customer — e.g. vendor rate − your margin.

The vendor changes the price (after sending)#

SituationKardlaneYou receiveWhat to do
After getting the card the vendor restates the price (“26400 for this”, “100×1150 + 50×1100 proceed?”) — no worse than agreed, or still the best quote, and above your marginAccepts and tells the vendor to proceed; the new rate becomes the agreed oneNothing yet — then the usual verdict—
Re-quote (after sending): the vendor asks to proceed at a lower price, and another vendor quoted more for this tradeAsks this vendor not to load (your decline reply) and sends the card to the highest other quoteNothing yet — then the usual verdict from the new vendor—
Re-quote no other vendor beats, margin still at or above your thresholdTells the vendor to proceedtrade.succeeded with requote and a rate_lower discrepancyUsually keep your customer’s quote (your margin is smaller but positive).
Re-quote no other vendor beats, margin below your threshold — negative margin OFFDoesn’t reply; escalatestrade.escalated with review.requoteAccept (POST /requote — vendor told to load, trade.resumed) or decline (vendor asked to return the card).
Same — negative margin ON. E.g. customer at 1,000, vendor first 1,100, now “25000 for this” = 1,000Tells the vendor to proceedtrade.succeeded with requote (acceptedBy: "negative_margin") and lowMargin (stage: "requote", margin: 0)Re-price your customer — e.g. vendor rate − your margin.
A re-quote under half of the first quoteAlways a person, whatever the policy — likely a misread or a tricktrade.escalatedCheck with the vendor.
Warning: Don’t resolve a pending re-quote as succeeded — the vendor hasn’t loaded the card yet. Use Decide a re-quote.

Timing#

SituationKardlaneYou receiveWhat to do
“WAIT ADD 40 MINUTES”, “loading may take 60 to 90 minutes”Extends the confirmation clock to the stated time (capped)Nothing—
No verdict before the timeoutEscalatestrade.escalated “vendor confirmation timed out”Wait or chase the vendor; or resolve by hand.
Credit arrives after the trade was escalated (late load)Closes it if every check passestrade.succeeded (after your trade.escalated)Make sure staff stop working it.

After the trade closed (48 hours)#

SituationKardlaneYou receiveWhat to do
/撤回 — the vendor reverses the creditRecords it; the trade stays succeededtrade.verdict_changed, change.kind: "reversed"Your customer was paid — check with the vendor before acting.
“this card is invalid” in reply to a card that succeededRecords ittrade.verdict_changed, failure_after_successSame.
A credit for a card that was marked failedRecords it with the settled termstrade.verdict_changed, credit_after_failureIf the vendor really paid, undo the rejection and pay.
The rest of a trade credited after it succeeded on some of its cardsRecords it and updates the trade’s settled termstrade.verdict_changed, rest_creditedPay your customer the difference once — check nobody on your team already did.

People and the system#

SituationKardlaneYou receiveWhat to do
Someone pauses the bot on a tradeSends nothing, decides nothing; clocks stopNothing—
Someone stops the botEscalates (no alert)trade.escalatedResolve by hand.
A person resolves (dashboard or API)—trade.succeeded / failed / cancelled, resolvedByHuman: trueSettle as usual.
Closed as handled outside, then the vendor credits itKeeps reading the chat for 6h without acting; a credit it can confirm is charged as a successNothing more (the trade stays cancelled)Nothing — the fee shows on your billing ledger.
The AI is unavailableWaits, then escalates; not billedtrade.escalatedResolve by hand.