Load a card with a balance in one call, hand the code and PIN to your customer, and void it if you need to take it back. Your customer spends it online or at any of your branches.
Base URL https://gcc-core-api.qboon.app/api/partner/v1. Requests and error responses are JSON. Some success responses are 204 with no body.
Your key says who you are, the team ID says which organization you act for, and the idempotency key makes a retried issue safe.
| X-Api-Key | Your API key. Keep it on your server, never in a browser or mobile app. |
| X-Team-Id | Your organization's team ID. A card of another organization returns 404. |
| X-Partner-Source | A short name for your system, for example returns-app. Shows up in Qboon's request logs. |
| X-Branch-Code | Optional on issue to tie the card to a branch. Required on redeem. |
| Idempotency-Key | Send one on every issue. Up to 255 characters. |
Amounts are integers in piasters: 25000 is EGP 250.00. An issued card holds EGP 50 to 50,000 (5000 to 5000000), in EGP only.
Set cardType to pick the kind of card. TOPUP_CARD (the default) can be spent in parts until the balance runs out. GIFT_VOUCHER must be spent in full in one go. Cards expire 365 days after issue.
A network error after POST /cards/issue leaves you unsure whether a card exists. Retry with the same Idempotency-Key and the same body and you get the original card back with 200, not a second card.
| Status | When |
|---|---|
| 201 | New key: the card was issued |
| 200 | Same key, same request: the first card, in its current state |
| 409 | Same key, different amount, card type, reference or branch (request/idempotency-conflict) |
Issue a EGP 250 gift card for a return. reference is optional, up to 100 characters, and comes back in the response.
The four calls a card-issuing integration needs. The reference also covers sell, top-up and discount redemption for point-of-sale integrations.
Errors come back as { "code": "…", "errors": … }. Branch on code, not on the message.
| Status | Code | When |
|---|---|---|
| 400 | request/invalid-fields | Amount outside EGP 50 to 50,000, a currency other than EGP, or a fixed-amount category with a different amount |
| 400 | request/invalid-fields | Missing X-Partner-Source header |
| 400 | request/branch-code-not-found | X-Branch-Code matches no branch in your organization |
| 401 | plain-text body | Missing, invalid or revoked X-Api-Key |
| 403 | auth/insufficient-permissions | Your key can't make this call, for example redeem with an issuing key |
| 404 | server/not-found | Unknown card or card of another organization |
| 409 | request/idempotency-conflict | Idempotency key reused with a different request |
| 409 | cards/invalid-transition | The card's status doesn't allow the call, for example voiding a fully redeemed or expired card |
| 409 | cards/insufficient-balance | Redeem amount is more than the balance |
| 422 | cards/no-issue-category | Your organization has no category set up for the requested cardType yet. Contact Qboon |
Every field, request and response, with a try-it console. Add X-Team-Id under Headers before you send a request.