Failure reasons
A short reason you can show your customer when a card is rejected.
Every trade.failed carries failure: { kind, message }. The message is written from what the vendor actually reported — “Card already redeemed”, “Zombie card (blocked)”, “Card balance is $0” — with any card code or PIN removed, so you can show it to your customer as-is.
| kind | Typical message |
|---|---|
already_redeemed | Card already redeemed |
duplicate | Card already used — or a repeat of a card that already sold, is in progress, or was rejected (“This card was already sold”) |
invalid | Invalid card or code |
wrong_card | Card doesn’t match the type, value or country submitted |
unreadable | Card images weren’t clear enough to redeem |
blocked | Card is blocked (zombie card) |
other | Card could not be redeemed |
not_active | Card isn’t active yet — please try again later |
vendor_refused | Card could not be accepted in this form — e.g. “Screen card not accepted” |
Was it the card’s fault?#
Not every vendor rejection means the card is bad. Kardlane classifies each one and says so in failure.class and failure.retryable:
| class | Meaning | What Kardlane does first | retryable |
|---|---|---|---|
card_dead | Used, redeemed, $0 balance, blocked — or a certain repeat | Fails it | false |
card_problem | Rejected for another reason (invalid code, wrong type or value) | Fails it | false |
not_active | “Not active yet” — may work later | Fails it | true |
resend | “Can’t see it, send again” | Sends the photos again once; still unreadable → fails (kind unreadable) | true |
vendor_refused | This vendor won’t take it (photo of a screen, a format they don’t buy, “money still inside”) | Offers the card to the next vendor that quoted for this trade; none left → fails | true |
When retryable is true, tell your customer they can submit the card again (later, or as a clear photo of the original). Kardlane won’t treat that resubmission as a repeat. When it’s false, a resubmission of the same card is closed straight away as duplicate.
Proof#
failure.proof carries the vendor’s own evidence behind the rejection: their screenshots (a balance check showing $0, a redemption error) and the words they used, with card codes masked. Image links point at Download a vendor screenshot — fetch them with your API key and store them with the sale if you keep a record of bad cards. For a repeat card, failure.duplicateOf names your earlier sale.
Use kind for your own logic and message for people. Escalations where the agent read a failure carry the same object in review.failure.