Purchase
Buy a value-added service — debit the asserted wallet, vend, refund on failure. All amounts in kobo.
Buy or redeem
POST /purchase
Debits the customer's asserted funding wallet, vends the good, and refunds if the
vend fails. Idempotent on reference.
The wallet debited is asserted by the perimeter (the portal-asserted identity), never a field in this body — a consumer cannot name an arbitrary wallet to debit.
Request
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | yes | Idempotency anchor. Re-sending the same reference does not double-debit or double-vend. |
vendor | string | yes | The vendor to route to, e.g. squad_vas (data — the layer routes to its adapter). |
product | string | yes | The good: airtime, data, or bill. |
target | string | yes | The recipient address — phone number or meter. |
costKobo | integer | yes | What the customer pays, in kobo. |
currency | string | yes | e.g. NGN. |
planCode | string | no | The vendor's plan code (data bundles, bill plans). |
amountKoboForVend | integer | no | The vend amount, when it differs from costKobo. |
billFields | object | no | Vendor-specific bill fields. |
requeryAttempts | integer | no | How many times to requery an uncertain outcome. |
Outcome
The response reports a terminal state: the vend succeeded (with any delivered artifact — e.g. a gift-card code), the debit was refused (nothing vended, nothing owed), or the outcome is pending and will be requeried. Posteering never fronts the money: a refused debit vends nothing.
Poll a purchase
GET /purchase/{reference}
Poll a purchase by reference. Wallet-scoped: returns only the asserted wallet's own purchase — you cannot read another wallet's purchase by guessing its reference.
VAS
Posteering's value-added-services rail. Buy airtime, data, and bills, or issue and redeem gift and reward instruments — the customer pays first, and Posteering never fronts the money.
Redemption
Issue a redeemable instrument and redeem it later — under principal authority, so a redeemer may only draw what they own or were granted.