Transactions¶

List, resolve and inspect the transactions your integration created.

List transactions¶

GET/api/v1/transactions/

Auth: API key or session.

curl "https://api.instapaybill.com/api/v1/transactions/?type=airtime" \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0"

Query param	Required	Description
`type`	✅	Transaction type filter, e.g. `airtime`, `data`, `electricity`, `cables`, `education`.

The response is paginated. Default page size is 10 (configurable via DEFAULT_PAGE_LIMIT in config/constants.js).

Session vs API shape

With an API key, data contains the transaction list. With a session JWT, the same endpoint returns the same list but the platform also applies admin-only behaviour — an admin sees every user's transactions.

Resolve a transaction¶

GET/api/v1/transactions/resolve

Finds a single transaction by your reference or by the platform's internal reference. This is the endpoint to use for reconciliation and for checking on a purchase that returned 300.

curl -G https://api.instapaybill.com/api/v1/transactions/resolve \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0" \
  --data-urlencode "apiRefID=order-1001"

curl -G https://api.instapaybill.com/api/v1/transactions/resolve \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0" \
  --data-urlencode "reference=IP|TN|A|123|20260918120000_ASDFG"

Query param	Description
`apiRefID`	Your reference, as sent in the `apiRefId` request field. Note the capital `ID` here versus `apiRefId` on the request.
`reference`	The platform's internal reference (`item_id`).

At least one is required. Sending neither returns 300 with "Our Reference or Your Reference is required".

{
  "msg": "Transaction retrieved successfully",
  "data": {
    "item_id": "IP|TN|A|123|20260918120000_ASDFG",
    "apiRefId": "order-1001",
    "type": "airtime",
    "status": true,
    "statusText": "Airtime Purchase Successful",
    "code": 200,
    "amount": 500,
    "properties": {
      "phone": "08012345678",
      "network": "MTN"
    }
  }
}

Read code to learn the final outcome:

`code`	Meaning
`200`	Delivered
`300`	Still pending — the provider has not confirmed
`400`	Failed and refunded

The resolve loop for pending purchases

A purchase that returns 300 is still being verified. Poll resolve every 60 seconds until code becomes 200 or 400. The webhook is the better option when you have a public HTTPS endpoint — it pushes the result to you.

Success rates¶

GET/api/v1/transactions/success-rates

Auth: API key or session.

curl https://api.instapaybill.com/api/v1/transactions/success-rates \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0"

Returns the success rate per service — useful for monitoring your integration's health and for alerting on provider degradation.

Transaction lifecycle¶

   Request
      │
      ▼
 ┌─────────────┐
 │  Debit      │  wallet debited atomically; pending intent row written
 └──────┬──────┘
        │
        ▼
 ┌─────────────┐
 │  Provider   │  airtime / data / electricity / cables / education
 └──────┬──────┘
        │
   ┌────┴─────┐
   │          │
   ▼          ▼
 code 200   code 300            code 400
   │          │                    │
   ▼          ▼                    ▼
 Settled   Held — wallet stays    Failed —
   │       debited, platform       wallet refunded
   │       polls the provider
   │          │
   │          ├──────► 200 (settled later)
   │          └──────► 400 (refunded later)
   ▼
 Webhook: code 200

The webhook fires when the transaction is resolved — which may be immediately, or much later if the purchase was held. See Webhooks.

Reading the transaction fields¶

Field	Type	Description
`item_id`	string	The platform's internal reference. Returned as `data.reference` on purchase responses.
`apiRefId`	string	Your reference. Present only for API-channel purchases.
`type`	string	`airtime`, `data`, `electricity`, `cables`, `education`.
`status`	boolean	`true` on success, `false` on failure.
`statusText`	string	Human-readable outcome.
`code`	number	`200` / `300` / `400`. The authoritative verdict.
`amount`	number	Face value charged.
`reference`	string	The provider's reference, when the provider supplied one.
`provider`	string	Which upstream provider served the request.
`properties`	object	Service-specific detail — `phone`, `network`, `token`, `unit`, `data_pin`, `customerName`, `customerAddress`.
`hold`	boolean	`true` when the transaction is held pending provider confirmation.
`domain`	string	`live` or `test` — which wallet it drew from.
`channel`	string	`api`, `app`, `web`, `whatsapp-agent`.
`createdAt`	date	When the purchase was created.

Other transaction endpoints¶

These are app/web or admin only and are listed for completeness.

Method	Path	Access	Description
`GET`	`/api/v1/transactions/{id}`	App/web	Transaction detail
`PUT`	`/api/v1/transactions/{id}`	App/web	Delete a transaction
`GET`	`/api/v1/transactions/{id}/receipt.pdf`	App/web	Receipt PDF
`PUT`	`/api/v1/transactions/`	App/web	Bulk delete own transactions
`GET`	`/api/v1/transactions/analytics-by-product`	Admin	Product analytics
`GET`	`/api/v1/transactions/profit-stats`	Superadmin	Profit statistics
`GET`	`/api/v1/transactions/profit-comparison`	Superadmin	Profit comparison
`GET`	`/api/v1/transactions/admin/success-rates`	Admin	Platform-wide success rates
`GET`	`/api/v1/transactions/manage-unresloved-transactions`	Admin	Unresolved transactions

Webhooks — the push-based alternative to polling
Errors — what each code means
Rate Limits — the duplicate-request guard