Gavekort

Kanseller kan ikke omgjøres — det finnes ingen reaktivering fordi et kort som ble slått ihjel og siden stille gjenopplivet, er en forpliktelse ingen har sagt ja til. Refunder er det eneste endepunktet som flytter penger: Stripe sender beløpet tilbake til det kortet som betalte, og ingen andre steder hen.

Prøv det her på siden

Konsollen herunder kjører de samme skjemaene og samme innløsningsregel som API'et, mot et kort som bare finnes i nettleseren din. Rett i kroppen, og se hvilken status ditt eget kall ville fått.

{
  "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,
    "noCashClaim": false,
    "productName": null
  }
}

Idempotens

Utsted og innløs kan begge bære en nøkkel som gjør kaltet trygt å gjenta. Samme nøkkel to ganger svarer med resultatet av den FØRSTE gangen — samme kort, samme postering — i stedet for å utstede eller trekke to ganger. De to verbene oppdager imidlertid ikke det samme: ved INNLØS svarer vi 409 idempotency_key_conflict hvis nøkkelen allerede er brukt på et annet kort eller på en utbetaling, i stedet for å treffe feil. Ved UTSTED sammenligner vi ikke kaltet — gjenbruker du en nøkkel med et annet beløp, får du 201 og det FØRSTE kortets data tilbake, uten feil. Bruk én nøkkel pr. kort.

Nøkkelen kan stå tre steder. Vi leser idempotencyKey i kroppen først, og ellers headeren Idempotency-Key og deretter X-Request-Guid. Kroppen vinner når det er både og.

Utsted et kort

Utsteder et kort utenfor betalingsflowet — solgt fra ditt eget system, fakturert til en bedrift, eller gitt med på huset.

origin er påkrevd her, hvor det er valgfritt i dashbordet. Et system utsteder uten at noen ser på, og valget følger kortet resten av dets levetid: sold betyr at en kunde har betalt for det, og så bærer kortet kundens rett til å få restbeløpet utbetalt kontant. b2b og comp gjø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øpet 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 bedriftens kort under giftCards.

Slå et kort opp

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 finnes på din bedrift.

Innløs

Trekker et beløp fra kortets saldo. Koden står i stien, beløpet 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 av innløsningen:

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

Gem id. Det er posteringen, og det er det eneste som kan angre nettopp denne innløsningen.

status er kortets tilstand etter innløsningen — en av active, redeemed, expired, void, disputed. Er saldoen brukt opp, skifter den til redeemed.

Går det ikke igjennom, er svaret én av disse. De er ikke like for kassen: noen er noe gjesten skal ha vite, og noen er noe bedriften skal ringes opp om.

Angre en innløsning

Legger beløpet tilbake på kortet. Det skjer som en ny postering med negativt beløp som peker på den som den angrer — ingenting slettes, og begge linjer blir stående i kortets historie. Var kortet brukt helt opp, blir det aktivt igjen.

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

Svarer 200 med posteringen som la beløpet tilbake:

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