Kardlane
Decisions

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 saleWhenWho can act
Handed to Kardlane (locked)After POST /v1/trades returnsKardlane only — hide it from staff queues; keep a “take over” button that calls POST /resolve with cancelled
Back with staff (unlocked)trade.escalated, trade.cancelledStaff; their decision goes back via POST /resolve so both sides agree
Locked againtrade.resumedKardlane
Completed / rejectedtrade.succeeded / trade.failedNobody — final. Later vendor changes arrive as trade.verdict_changed
Note: Lock the sale while Kardlane has it. If staff also redeem the card elsewhere, the vendor sees a repeat and both sides lose.

The handler#

kardlane-webhook.js
// 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-Delivery and keep the handler idempotent — a non-2xx or a timeout means the same event comes again.
  • Show failure.message to 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/resolve so 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:

pricing.js
// 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 didCustomer gets
As agreed, or paid moreThe quote
Loaded part of the valuePaid for what loaded
Paid a lower rate, margin still at or above your thresholdThe 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 currencyYour rate for that currency, capped at what the vendor paid
Loaded as another card type, or numbers look wrongA 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 policyCustomer at 1,000, vendor re-quoted 1,000, your margin 100
Keep your full marginConfirm at 900
Take a smaller margine.g. 15 → confirm at 985
Absorb it this timeConfirm 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 autoAccept above) 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