Kardlane
API Reference

Create a trade

POSThttps://api.kardlane.com/v1/trades

Hand a gift card to Kardlane. The bot asks your vendors for rates, sends the card to the best one, reads their reply and tells you the outcome by webhook.

Idempotent on externalRef: posting the same reference again returns the trade you already created (200, status: "duplicate").

Answered immediately with 202 — the card read, rate requests and everything after run in the background.

Authorization#

Authorizationheaderrequired

Bearer token: Bearer <your project API key>. Create keys in the dashboard under your project’s Integration page.

Body#

externalRefstringrequired

Your own id for this sale. Echoed on every webhook; the idempotency key.

cardTypestringrequired

A card-type code from List card types, e.g. APPLE_ITUNES. An unknown value is rejected with a suggestion.

countrystringrequired

The card’s currency / region, e.g. USD, CAD, GBP.

valuenumberrequired

Face value of the card (for several cards, their total).

customerRatenumberrequired

The rate you pay your customer per 1 unit of card value, in your payout currency. Never replaced by a vendor rate.

assetsstring[]

HTTPS links to the card photos — every card, front and back (up to 20 are read). HEIC is converted before vendors see it.

codestring

The redemption code, for e-codes. Vendors are asked with ECODE.

pinstring

The card’s PIN, when it has one (e.g. Razer Gold). Stored encrypted, sent only to the chosen vendor, never returned.

Responses#

202Accepted — the bot is on it.
200This externalRef was already sent.
400Invalid payload (e.g. an unknown card type).
409The bot is switched off for this project (or by Kardlane). Handle the trade with your own team.
curl -X POST https://api.kardlane.com/v1/trades \
  -H "Authorization: Bearer $KARDLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalRef": "sale_8213",
    "cardType": "APPLE_ITUNES",
    "country": "USD",
    "value": 150,
    "customerRate": 1080,
    "assets": [
      "https://cdn.example.com/cards/8213-front.jpg",
      "https://cdn.example.com/cards/8213-back.jpg"
    ]
  }'
{
  "tradeId": "6abea25d-0c1f-4a43-9d1e-3b5c2f0edad5",
  "status": "accepted"
}