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.
نظرة سريعة
- المصادقة
- رمز موظّف أو جلسة
- تتطلب صلاحية
-
prm_cards_verifyVerify / redeem cards - حد المعدل
card_redeem- مفتاح عدم التكرار
request_id
المعاملات
| المعامل | الوصف |
|---|---|
codeمطلوب
body · string
|
The plaintext card code. |
user_idمطلوب
body · integer
|
The subscriber to credit. |
request_idمطلوب
body · string
|
Idempotency key. |
الأخطاء
| الرمز | متى تُرجَع |
|---|---|
ERR_VALIDATION400
|
code, user_id or request_id missing, or a reserved or over-long request_id |
ERR_NOT_FOUND404
|
unknown code, a card outside your subtree, or a subscriber you may not write to |
ERR_CONFLICT409
|
the card is already redeemed, or the request_id belongs to a redemption of a different card |
ERR_CONFLICT410
|
the card has been revoked or has expired |