Gift card

Cancel cannot be reversed — there is no reactivation, because a card that was killed and later quietly brought back is an obligation nobody has agreed to. Refund is the only endpoint that moves money: Stripe sends the amount back to the card that paid, and nowhere else.

Try it here on the page

The console below runs the same schemas and the same redemption rule as the API, against a card that exists only in your browser. Edit the body, and see what status your own call would get.

{
  "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
  }
}

Idempotency

Issue and redeem can both carry a key that makes the call safe to repeat. The same key twice answers with the result of the FIRST time — same card, same posting — instead of issuing or debiting twice. The two verbs do not detect the same thing, though: on REDEEM we answer 409 idempotency_key_conflict if the key was already used on a different card or on a payout, instead of going wrong. On ISSUE we do not compare the call — if you reuse a key with a different amount, you get 201 and the FIRST card's data back, with no error. Use one key per card.

The key can be in three places. We read idempotencyKey in the body first, and otherwise the Idempotency-Key header and then X-Request-Guid. The body wins when there is both.

Issue a card

Issues a card outside the payment flow — sold from your own system, invoiced to a company, or given on the house.

origin is required here, whereas it is optional in the dashboard. A system issues with no one watching, and the choice follows the card for the rest of its life: sold means a customer has paid for it, and then the card carries the customer's right to have the remaining balance paid out in cash. b2b and comp do not.

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"
  }'

Responds 201 with the card under giftCard. The amount is in øre — 50000 is 500.00 kr.

List cards

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

Responds 200 with the business's cards under giftCards.

Look up a card

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

Responds 200 with the card under giftCard, or 404 if the code is not found on your business.

Redeem

Debits an amount from the card's balance. The code is in the path, the amount in the body.

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"
  }'

Responds 200 with the result of the redemption:

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

Save the id. It is the posting, and it is the only thing that can reverse this specific redemption.

status is the card's state after redemption — one of active, redeemed, expired, void, disputed. If the balance is used up, it changes to redeemed.

If it does not go through, the response is one of these. They are not all the same for the till: some are something the guest needs to know, and some are something the business needs to be called about.

Reverse a redemption

Puts the amount back on the card. It happens as a new posting with a negative amount that points to the one it reverses — nothing is deleted, and both lines stay in the card's history. If the card was used up entirely, it becomes active again.

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

Responds 200 with the posting that put the amount back:

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