Partner Voucher API · v1

API Documentation

Closed-loop digital grocery voucher, issued and activated in real time via API. Sandbox ready — live keys issued per partner after joint testing is signed off.

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.

  1. 1A buyer pays the partner for an AfghanBasket grocery voucher ($25 / $50 / $100, or any amount $10–$500).
  2. 2The partner calls POST /vouchers in real time to issue and activate a closed-loop voucher. AfghanBasket returns a unique voucher code.
  3. 3The recipient in Afghanistan receives groceries fulfilled by AfghanBasket; the voucher is marked via POST /vouchers/{code}/redeem.
  4. 4AfghanBasket fires a signed webhook to the partner on every status change, and the partner can also pull GET /transactions for reconciliation.
  5. 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:

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.
Note: we intentionally use x-api-key (notAuthorization: Bearer) so the partner channel is fully isolated from end-user authentication.

3. Commercial parameters (sandbox defaults)

CurrencyUSD
Recommended denominations$25, $50, $100
Custom amountsallowed, $10–$500
Commissionconfigured per partner agreement (sandbox default 12.5%)
Net remittanceamount × (1 − commission%)
Voucher validity365 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

GET/ping
Response
{ "ok": true, "service": "AfghanBasket Partner API", "partner": "<partner-id>",
  "version": "v1", "mode": "sandbox", "time": "2026-10-17T07:11:36Z" }

4.2 Catalog — denominations & terms

GET/catalog
Response
{
  "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)

POST/vouchers

Call this once the partner has collected payment from the buyer.

FieldTypeRequiredNotes
partner_referencestringyesThe partner’s own transaction id. Idempotency anchor — replays return the same voucher.
amountnumberyes10–500 USD.
currencystringnoDefaults USD (only USD supported now).
buyerobjectno{ name, email }
recipientobjectno{ name, phone, city }
notestringnoFree text (max 300).
expires_in_daysnumbernoDefaults 365.
metadataobjectnoEchoed back on every response/webhook.
Request
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).

Response 201
{
  "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

GET/vouchers/{code}

Returns the voucher object. 404 not_found if unknown.

4.5 Redeem against fulfilment

POST/vouchers/{code}/redeem

Idempotent — 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

POST/vouchers/{code}/cancel

Optional body { "reason": "buyer refunded" }. Returns 409 already_redeemed if the voucher was already redeemed.

4.7 Reconciliation

GET/transactions
Request
GET /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

State machine
ACTIVE  ──redeem──▶  REDEEMED
  │
  ├──cancel──▶  CANCELLED
  └──(past expiry)──▶  EXPIRED

6. Webhooks (AfghanBasket → Partner)

AfghanBasket POSTs a signed JSON event to a URL the partner provides, on: voucher.issued,voucher.redeemed, voucher.cancelled.

Headers
X-AfghanBasket-Event: voucher.redeemed
X-AfghanBasket-Signature: sha256=<hex HMAC of the raw body>
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": "..." } }.

HTTPcodeMeaning
400missing_reference / invalid_amount / invalid_currency / invalid_jsonBad request
401unauthorizedMissing/invalid API key
404not_foundUnknown voucher code
409cancelled / expired / already_redeemedInvalid state transition
503partner_disabledAPI not configured on that environment

8. Getting started

  1. 1Request a sandbox API key and webhook signing secret for your platform (shared securely out-of-band).
  2. 2Point your integration at the sandbox base URL and run GET /ping to confirm connectivity.
  3. 3Provide the webhook URL where you want status events delivered.
  4. 4Complete joint end-to-end testing (issue → redeem → reconcile).
  5. 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