Redeem a card onto a subscriber

POST /api/v1/cards/redeem prm_cards_verify

Spends a card and applies its effect to the named subscriber. Two authority checks run, both derived from your credential and neither from the body: the card must be in your subtree, and the subscriber must be one you may write to. Both denials are 404s identical to "no such card" and "no such subscriber".

A replay returns 200 with the same card_id, mode and effect_applied, and NO replay flag — but new_balance is ABSENT, because the replay path returns the stored effect without re-reading the wallet. A missing new_balance is not a failure and is not a reason to retry. Read the balance off the subscriber record if you need it.

At a glance

Authentication: Staff token or session
Requires permission: prm_cards_verify Verify / redeem cards
Rate limit: card_redeem
Idempotency key: request_id

Parameters

Parameter	Description
`code`required body · string	The plaintext card code.
`user_id`required body · integer	The subscriber to credit.
`request_id`required body · string	Idempotency key.

Errors

Code	When it is returned
`ERR_VALIDATION`400	code, user_id or request_id missing, or a reserved or over-long request_id
`ERR_NOT_FOUND`404	unknown code, a card outside your subtree, or a subscriber you may not write to
`ERR_CONFLICT`409	the card is already redeemed, or the request_id belongs to a redemption of a different card
`ERR_CONFLICT`410	the card has been revoked or has expired

Request

curl -X POST "$BASE/api/v1/cards/redeem" \
  -H "Authorization: Bearer $XR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "K7P4M2Q9XD",
  "user_id": 4711,
  "request_id": "3a1d0c77-8b52-4e19-9d64-1f7e2c5a9b30"
}'

Response 200 OK

{
  "data": {
    "card_id": 90211,
    "mode": "refill_balance",
    "user_id": 4711,
    "effect_applied": { "type": "add_balance", "amount": 150.00 },
    "new_balance": 400.00
  }
}

BASE is your tenant host: the same address you sign in on.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us