Building your integration
A complete webhook handler and pricing policy, taken from a production integration — copy the shape, adjust the policy.
This is how a production gift-card exchange runs Kardlane end to end: customers sell cards in its app, Kardlane sells them to vendors, and staff only see what genuinely needs a person.
The sale’s lifecycle on your side#
| Your sale | When | Who can act |
|---|---|---|
| Handed to Kardlane (locked) | After POST /v1/trades returns | Kardlane only — hide it from staff queues; keep a “take over” button that calls POST /resolve with cancelled |
| Back with staff (unlocked) | trade.escalated, trade.cancelled | Staff; their decision goes back via POST /resolve so both sides agree |
| Locked again | trade.resumed | Kardlane |
| Completed / rejected | trade.succeeded / trade.failed | Nobody — final. Later vendor changes arrive as trade.verdict_changed |
The handler#
// One handler for every Kardlane webhook. Verify the signature first
// (see Webhooks), then dedupe on the delivery id.
export async function onKardlaneEvent(event) {
const { type, data } = event;
const sale = await sales.findById(data.externalRef);
if (!sale || sale.kardlaneTradeId !== data.tradeId) return; // not ours / not this trade
if (await deliveries.seen(event.id)) return; // at-least-once delivery
switch (type) {
case 'trade.succeeded': {
if (sale.status !== 'PENDING') return; // already settled by a person
const { amount, rate, needsStaff } = priceFor(sale, data); // see "Pricing what happened"
if (needsStaff) return staff.notify(sale, needsStaff);
await sales.complete(sale, { amount, rate }); // pays the customer
if (data.discrepancies?.length) staff.notify(sale, describe(data.discrepancies));
break;
}
case 'trade.failed':
if (sale.status !== 'PENDING') return;
await sales.reject(sale, data.failure.message, // customer-safe as-is
await keepProof(data.failure.proof)); // vendor screenshots, if you record bad cards
// retryable: the card may be fine (not active yet, unreadable, refused by one
// vendor) — let the customer submit it again; Kardlane won't call it a repeat.
if (data.failure.retryable) await sales.allowResubmission(sale);
break;
case 'trade.escalated':
await sales.unlock(sale); // staff may act now
if (autoAccept(data.review)) await kardlane.resolve(data.tradeId, data.review.suggestedVerdict);
else staff.notify(sale, data.review.summary, data.review.reviewUrl);
break;
case 'trade.resumed': // a re-quote was accepted
await sales.lock(sale); // Kardlane has it again
break;
case 'trade.verdict_changed': // never flip it automatically
staff.notify(sale, data.change.message, data.change.vendorSaid);
break;
case 'trade.cancelled':
await sales.unlock(sale);
break;
}
}
// Escalations you can accept without a person: only "not trusted yet" held it back.
const autoAccept = (r) =>
r.suggestedVerdict && r.suggestedVerdict !== 'partial' && (r.confidence ?? 0) >= 0.9 &&
r.blockedBy.length === 1 && r.blockedBy[0] === 'trusted_vendor';Rules worth keeping#
- Act only on events for the trade the sale was handed to (
tradeId), and only while the sale is still pending. - Dedupe on
X-Kardlane-Deliveryand keep the handler idempotent — a non-2xx or a timeout means the same event comes again. - Show
failure.messageto your customer as-is; it never contains codes or vendor chatter. - When staff decide an escalated sale on your side, send the decision to
POST /v1/trades/:id/resolveso Kardlane’s records (and vendor track records) match.
Pricing what happened#
When discrepancies isn’t empty the vendor paid for something other than what was agreed — a lower rate, part of the value, another currency. Kardlane reports it; you decide what your customer gets. This is the policy the production integration uses — keep its own margin, never pay above the quote, and hand anything odd to a person:
// What does the customer get, given what the vendor actually did?
function priceFor(sale, data) {
const kinds = new Set((data.discrepancies ?? []).map((d) => d.kind));
if (kinds.has('card_type_changed')) return { needsStaff: 'loaded as another card type' };
let amount = sale.amount;
if (kinds.has('value_partial')) amount = data.settled.value; // pay for what loaded
let rate = sale.rate;
const paid = data.settled?.vendorRate ?? data.vendorRate; // what the vendor pays per unit
if (kinds.has('currency_changed')) {
const own = yourRateFor(sale.cardType, data.settled.country); // your price list
if (!own) return { needsStaff: 'no rate for ' + data.settled.country };
rate = Math.min(own, paid ?? own); // never pay more than you got
} else if (data.lowMargin && paid) {
// Negative margin (before or after sending): vendor rate − your margin.
rate = paid - yourMarginFor(sale);
}
// A lower rate that still leaves margin (rate_lower without lowMargin): keep the quote.
rate = Math.min(rate, sale.rate); // never above the quote
if (rate <= sale.rate * 0.5) return { needsStaff: 'adjusted values look wrong' };
return { amount, rate };
}| Vendor did | Customer gets |
|---|---|
| As agreed, or paid more | The quote |
| Loaded part of the value | Paid for what loaded |
| Paid a lower rate, margin still at or above your threshold | The quote (you keep a smaller margin) |
| Negative margin — lowMargin present (every quote was low, or a lower re-quote no one beat) | The vendor’s rate − your margin, never above the quote |
| Loaded as another currency | Your rate for that currency, capped at what the vendor paid |
| Loaded as another card type, or numbers look wrong | A person decides |
Negative margin and re-quotes: your choice#
Gift-card rates move faster than any price list, so sometimes every vendor’s quote is below what your customer was shown, or a vendor lowers its price after getting the card. Two project settings cover this. Re-quote (on by default) moves the card to a better quote when a vendor lowers its price and another vendor quoted more. Negative margin (off by default) decides what happens when the margin still ends up under your threshold: a person decides, or Kardlane trades the card anyway and trade.succeeded carries lowMargin (stage, margin, threshold) — plus requote (first quote, new rate, who accepted it) when a re-quote was involved. How you re-price is up to you:
| Your policy | Customer at 1,000, vendor re-quoted 1,000, your margin 100 |
|---|---|
| Keep your full margin | Confirm at 900 |
| Take a smaller margin | e.g. 15 → confirm at 985 |
| Absorb it this time | Confirm at 1,000 (no profit) |
Kardlane’s fee follows the settled margin, so a re-quote that leaves no margin carries no fee.
Getting fewer escalations#
- Mark reliable vendors trusted. It removes the most common hold (
trusted_vendor). - Set confirmation timeouts per card type. Slow cards (Sephora, some Apple) take hours; a 10-minute default escalates real successes.
- Accept clear “not trusted yet” escalations automatically (see
autoAcceptabove) until those vendors earn trust. - Send clear, original photos. Some vendors refuse photos of a screen.
See also: How Kardlane decides · Scenario map · Deciding escalations