Version
v1
Base URL
https://afghanbasket.shop/api/partner/v1
1. How the integration works
A partner platform (reseller, wallet, remittance provider, marketplace, etc.) integrates into this AfghanBasket API to sell AfghanBasket grocery vouchers to its own customers.
- 1A buyer pays the partner for an AfghanBasket grocery voucher ($25 / $50 / $100, or any amount $10–$500).
- 2The partner calls
POST /vouchersin real time to issue and activate a closed-loop voucher. AfghanBasket returns a unique vouchercode. - 3The recipient in Afghanistan receives groceries fulfilled by AfghanBasket; the voucher is marked via
POST /vouchers/{code}/redeem. - 4AfghanBasket fires a signed webhook to the partner on every status change, and the partner can also pull
GET /transactionsfor reconciliation. - 5The partner withholds its agreed commission and remits the net amount to AfghanBasket on the agreed settlement cycle.
2. Authentication
Every request must include the API key in the x-api-key header:
x-api-key: <YOUR_AFGHANBASKET_API_KEY>- Each partner receives its own environment-scoped keys (
sandbox/live). - The sandbox key is shared separately (securely), never in an email/chat body.
- The live key is issued after integration sign-off.
- Missing/invalid key →
401 unauthorized. - All traffic is HTTPS only.
x-api-key (notAuthorization: Bearer) so the partner channel is fully isolated from end-user authentication.3. Commercial parameters (sandbox defaults)
| Currency | USD |
| Recommended denominations | $25, $50, $100 |
| Custom amounts | allowed, $10–$500 |
| Commission | configured per partner agreement (sandbox default 12.5%) |
| Net remittance | amount × (1 − commission%) |
| Voucher validity | 365 days (configurable per voucher) |
GET /catalog returns these live for the calling key, including the computednet_amount per denomination.
4. Endpoints
4.1 Connectivity & key check
/ping{ "ok": true, "service": "AfghanBasket Partner API", "partner": "<partner-id>",
"version": "v1", "mode": "sandbox", "time": "2026-10-17T07:11:36Z" }4.2 Catalog — denominations & terms
/catalog{
"currency": "USD", "commission_pct": 12.5, "min_amount": 10, "max_amount": 500,
"custom_amounts_allowed": true,
"denominations": [
{ "sku": "AB-BASKET-25", "amount": 25, "net_amount": 21.88, "currency": "USD", "commission_pct": 12.5 },
{ "sku": "AB-BASKET-50", "amount": 50, "net_amount": 43.75, "currency": "USD", "commission_pct": 12.5 },
{ "sku": "AB-BASKET-100", "amount": 100, "net_amount": 87.50, "currency": "USD", "commission_pct": 12.5 }
]
}4.3 Issue & activate a voucher (real-time)
/vouchersCall this once the partner has collected payment from the buyer.
| Field | Type | Required | Notes |
|---|---|---|---|
| partner_reference | string | yes | The partner’s own transaction id. Idempotency anchor — replays return the same voucher. |
| amount | number | yes | 10–500 USD. |
| currency | string | no | Defaults USD (only USD supported now). |
| buyer | object | no | { name, email } |
| recipient | object | no | { name, phone, city } |
| note | string | no | Free text (max 300). |
| expires_in_days | number | no | Defaults 365. |
| metadata | object | no | Echoed back on every response/webhook. |
POST /api/partner/v1/vouchers
x-api-key: <KEY>
Content-Type: application/json
{
"partner_reference": "partner-txn-abc123",
"amount": 50,
"buyer": { "name": "Diaspora Buyer", "email": "[email protected]" },
"recipient": { "name": "Bibi Haji", "phone": "+93700000000", "city": "Kabul" }
}Responds 201 Created (or 200 with "idempotent_replay": true on a replay).
{
"voucher": {
"code": "AB-W5AK-Z5CZ-D4CW",
"partner": "<partner-id>",
"partner_reference": "partner-txn-abc123",
"status": "ACTIVE",
"amount": 50, "currency": "USD",
"commission_pct": 12.5, "net_amount": 43.75,
"buyer": { "name": "Diaspora Buyer", "email": "[email protected]" },
"recipient": { "name": "Bibi Haji", "phone": "+93700000000", "city": "Kabul" },
"issued_at": "2026-10-17T07:11:36Z",
"activated_at": "2026-10-17T07:11:36Z",
"expires_at": "2027-10-17T07:11:36Z"
}
}4.4 Status lookup
/vouchers/{code}Returns the voucher object. 404 not_found if unknown.
4.5 Redeem against fulfilment
/vouchers/{code}/redeemIdempotent — redeeming an already-redeemed voucher returns 200. Optional body { "order_id": "AB-123456" }. Returns 409 if the voucher is cancelled or expired.
4.6 Void before redemption
/vouchers/{code}/cancelOptional body { "reason": "buyer refunded" }. Returns 409 already_redeemed if the voucher was already redeemed.
4.7 Reconciliation
/transactionsGET /api/partner/v1/transactions?status=REDEEMED&from=2026-01-01&to=2026-02-01&limit=100&cursor=<id>
x-api-key: <KEY>Filters: status (ISSUED|ACTIVE|REDEEMED|CANCELLED|EXPIRED), from, to(ISO dates), limit (1–200), cursor (pagination). Response:{ "data": [ ... ], "next_cursor": "ckx...", "count": 100 }.
5. Voucher lifecycle
ACTIVE ──redeem──▶ REDEEMED
│
├──cancel──▶ CANCELLED
└──(past expiry)──▶ EXPIRED6. Webhooks (AfghanBasket → Partner)
AfghanBasket POSTs a signed JSON event to a URL the partner provides, on: voucher.issued,voucher.redeemed, voucher.cancelled.
X-AfghanBasket-Event: voucher.redeemed
X-AfghanBasket-Signature: sha256=<hex HMAC of the raw body>{ "event": "voucher.redeemed", "sent_at": "2026-10-17T07:12:00Z", "data": { /* voucher object */ } }Verification: computeHMAC-SHA256(raw_body, <shared webhook secret>) and compare to the signature header. The shared secret is exchanged securely out-of-band. Reconciliation can always fall back toGET /transactions.
7. Errors
All errors return { "error": { "code": "...", "message": "..." } }.
| HTTP | code | Meaning |
|---|---|---|
| 400 | missing_reference / invalid_amount / invalid_currency / invalid_json | Bad request |
| 401 | unauthorized | Missing/invalid API key |
| 404 | not_found | Unknown voucher code |
| 409 | cancelled / expired / already_redeemed | Invalid state transition |
| 503 | partner_disabled | API not configured on that environment |
8. Getting started
- 1Request a sandbox API key and webhook signing secret for your platform (shared securely out-of-band).
- 2Point your integration at the sandbox base URL and run
GET /pingto confirm connectivity. - 3Provide the webhook URL where you want status events delivered.
- 4Complete joint end-to-end testing (issue → redeem → reconcile).
- 5On sign-off, we issue your live key and enable your partner account.
Ready to integrate?
Request sandbox credentials and our team will set you up with keys, a webhook secret and a joint test plan.
Request sandbox access