API

Gavekort

Fem endepunkter dækker hele kortets liv gennem API'et: udsted, list, slå op, indløs, fortryd.

Prøv det her på siden

Konsollen herunder kører de samme skemaer og den samme indløsningsregel som API'et, mod et kort, der kun findes i din browser. Ret i kroppen, og se hvilken status dit eget kald ville få.

{
  "giftCard": {
    "id": "gc_3n8qk2vh",
    "code": "KUV-DLT2-9GPW",
    "orderId": null,
    "status": "active",
    "initialOre": 50000,
    "balanceOre": 50000,
    "expiresAt": "2029-01-15T12:00:00.000Z",
    "merchantSlug": "cafe-noir",
    "origin": "b2b",
    "reference": "Faktura 2026-114",
    "punchValueOre": null
  }
}

Udsted et kort

Udsteder et kort uden om betalingsflowet — solgt fra dit eget system, faktureret til en virksomhed, eller givet med på huset.

origin er påkrævet her, hvor det er valgfrit i dashboardet. Et system udsteder uden nogen kigger med, og valget følger kortet resten af dets levetid: sold betyder, at en kunde har betalt for det, og så bærer kortet kundens ret til at få restbeløbet udbetalt kontant. b2b og comp gør ikke.

curl -X POST https://api.kuvert.dk/v1/api/giftcards \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountOre": 50000,
    "origin": "b2b",
    "reference": "Faktura 2026-114"
  }'

Svarer 201 med kortet under giftCard. Beløbet er i øre — 50000 er 500,00 kr.

List kort

curl https://api.kuvert.dk/v1/api/giftcards \
  -H "Authorization: Bearer pk_live_..."

Svarer 200 med forretningens kort under giftCards.

Slå et kort op

curl https://api.kuvert.dk/v1/api/giftcards/KUV-XXXX-XXXX \
  -H "Authorization: Bearer pk_live_..."

Svarer 200 med kortet under giftCard, eller 404 hvis koden ikke findes på din forretning.

Indløs

Trækker et beløb fra kortets saldo. Koden står i stien, beløbet i kroppen.

curl -X POST https://api.kuvert.dk/v1/api/giftcards/KUV-XXXX-XXXX/redeem \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountOre": 6400,
    "location": "Vesterbro",
    "idempotencyKey": "pos-terminal-3-1753440000"
  }'

Svarer 200 med resultatet af indløsningen:

{
  "id": "red_8f21c0b4",
  "code": "KUV-XXXX-XXXX",
  "amountOre": 6400,
  "remainingBalanceOre": 43600,
  "status": "active"
}

Gem id. Det er posteringen, og det er det eneste, der kan fortryde netop denne indløsning.

status er kortets tilstand efter indløsningen — en af active, redeemed, expired, void, disputed. Er saldoen brugt op, skifter den til redeemed.

Fortryd en indløsning

Lægger beløbet tilbage på kortet. Det sker som en ny postering med negativt beløb, der peger på den, den fortryder — ingenting slettes, og begge linjer bliver stående i kortets historik. Var kortet brugt helt op, bliver det aktivt igen.

curl -X POST https://api.kuvert.dk/v1/api/redemptions/red_8f21c0b4/reverse \
  -H "Authorization: Bearer pk_live_..."

Svarer 200 med posteringen, der lagde beløbet tilbage:

{
  "id": "red_2c77af90",
  "code": "KUV-XXXX-XXXX",
  "amountOre": -6400,
  "remainingBalanceOre": 50000,
  "status": "active"
}