Partner API · v1.0

Issue Qboon gift cards from your own system

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.

01 Quickstart

Four steps to your first card

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.

01
Get your credentials
Qboon ops sets up your integration and sends you an API key and a team ID. The team ID is your organization; every card you issue belongs to it.
Ask for credentials →
02
Send three headers
X-Api-Key, X-Team-Id and X-Partner-Source, a short name for your system, on every call.
Headers →
03
Issue a card
POST /cards/issue with an amount in piasters and an Idempotency-Key. The card comes back ACTIVE.
Example request →
04
Deliver the code and PIN
Show or send code and pin to your customer from your own app. Qboon doesn't email the card for you.
Response fields →
02 Core concepts

Headers, amounts and retries

Your key says who you are, the team ID says which organization you act for, and the idempotency key makes a retried issue safe.

Headers

X-Api-KeyYour API key. Keep it on your server, never in a browser or mobile app.
X-Team-IdYour organization's team ID. A card of another organization returns 404.
X-Partner-SourceA short name for your system, for example returns-app. Shows up in Qboon's request logs.
X-Branch-CodeOptional on issue to tie the card to a branch. Required on redeem.
Idempotency-KeySend one on every issue. Up to 255 characters.

Amounts and card type

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.

Idempotency and retries

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.

StatusWhen
201New key: the card was issued
200Same key, same request: the first card, in its current state
409Same key, different amount, card type, reference or branch (request/idempotency-conflict)
Pitfall: without a key, every retry issues a new card. Derive the key from your own record, like the return ID, so a crash and restart still sends the same key.
// one key per card you mean to issue
Idempotency-Key: RET-20481:refund
03 Example

Issue a card

Issue a EGP 250 gift card for a return. reference is optional, up to 100 characters, and comes back in the response.

04 Endpoints

What you can call

The four calls a card-issuing integration needs. The reference also covers sell, top-up and discount redemption for point-of-sale integrations.

05 Errors

When a call fails

Errors come back as { "code": "…", "errors": … }. Branch on code, not on the message.

StatusCodeWhen
400request/invalid-fieldsAmount outside EGP 50 to 50,000, a currency other than EGP, or a fixed-amount category with a different amount
400request/invalid-fieldsMissing X-Partner-Source header
400request/branch-code-not-foundX-Branch-Code matches no branch in your organization
401plain-text bodyMissing, invalid or revoked X-Api-Key
403auth/insufficient-permissionsYour key can't make this call, for example redeem with an issuing key
404server/not-foundUnknown card or card of another organization
409request/idempotency-conflictIdempotency key reused with a different request
409cards/invalid-transitionThe card's status doesn't allow the call, for example voiding a fully redeemed or expired card
409cards/insufficient-balanceRedeem amount is more than the balance
422cards/no-issue-categoryYour organization has no category set up for the requested cardType yet. Contact Qboon

Full API reference

Every field, request and response, with a try-it console. Add X-Team-Id under Headers before you send a request.