trade.succeeded
The vendor redeemed the card and paid, and Kardlane verified it (or you resolved it as succeeded). In verdict-only mode, this is where you pay your customer.
A success is reported at the terms the vendor actually settled on. agreed is what was quoted, settled is what the vendor did (from its own credit line, or the agent’s read), and discrepancies lists every difference — empty when it went exactly as agreed. vendorRate and margin at the top level are the settled figures, and Kardlane’s fee follows them (no fee when the margin is zero or negative).
When a person decided the outcome rather than the vendor’s reply — someone on your team in the Kardlane dashboard, or your own system through Resolve a trade — the event carries resolvedByHuman: true, resolvedVia (dashboard or api) and, from the dashboard, resolvedBy (who). Use it to word your own notifications: “marked succeeded by your team”, not “the vendor paid”.
discrepancies[].kind is one of rate_lower, rate_higher, value_partial (only part of the value loaded), value_higher, currency_changed (e.g. loaded as a CAD card, not USD), card_type_changed. Each has expected, actual and a plain-English message.
Kardlane doesn’t decide what you pay your customer: check discrepancies and re-price if you need to — for example, pay for settled.value at your rate for settled.country / settled.cardType.
agreed, settled and discrepancies are also on trade.escalated when the vendor credited the card but a check held it back; there, the top-level vendorRate and margin stay at the agreed figures until you resolve.
requote is present when the vendor re-quoted after getting the card and it was accepted: from (first quote, also agreed.vendorRate), to (new rate), acceptedBy (kardlane — margin still at or above your threshold; negative_margin — your negative-margin setting; person), marginAfter, marginThreshold. It’s also present when, after a re-quote, the trade was resolved as succeeded through Resolve a trade or by a person in the dashboard.
lowMargin is present when the trade went ahead with a margin under your threshold because your negative-margin setting is on: stage selection (every quote was low) or requote (a lower re-quote no other vendor beat), margin, threshold. Re-price your customer — e.g. settled vendor rate − your margin. With margins on your price list, suggestedCustomerRate is exactly that, for the cards actually traded (and yourMargin the margin used). With the setting off, those trades come to you as trade.escalated carrying the same lowMargin, plus bestQuote — the best of the low quotes — so a person can re-price and go ahead.
cardFindings (on every trade webhook and on Retrieve a trade) is present when the card photos showed something you should know. cards = the cards found (when several), declared = your cards, orientation (Apple: horizontal or vertical) / screenPhoto = what the photo shows, printedValue = the value printed when it differs, and findings[] = each difference with kind and a plain-English message. Kinds: several_cards (several cards sold as one, nothing declared), split (declared one way, the photos show more cards), combined (declared as several, the photos show one), value, vertical (a vertical Apple card — vendors usually pay less than for the usual horizontal card), screen_photo (the card shown on another screen), variant (the card looks like a different variant than the one sold — e.g. { "kind": "variant", "declared": "RAZER_GOLD", "found": "RAZER_GOLD_16", "basis": "code shape" }; Kardlane asks vendors for the variant it found and reports it so you can adjust the customer’s rate — it doesn’t change the rate itself), value_check (the declared value is far outside the usual range for this card; the trade is held for review before any vendor is asked). Vendors were asked for the card(s) as found, so re-price your customer the same way. With your price list (Send your price list), Kardlane does it for you before choosing a vendor: customerRate on the webhook is already the re-priced rate, and cardFindings.reprice is { from, to, lines: [{ value, count, rate }], source: "price_list" }; if your list couldn’t be used, cardFindings.repriceSkipped says why.
Delivery#
Sent as a signed POST to your project’s webhook URL — see the Webhooks guide to verify the signature. Delivery is at-least-once: dedupe on the X-Kardlane-Delivery header (or data.idempotencyKey).