Overview

The Balance API provides balance enquiry capabilities for merchant wallets and virtual cards. It supports retrieving the current wallet balance as well as the virtual card wallet balance for a Quickteller terminal.

Base URLs

Environment	Base URL
Production	`https://orion.interswitchng.com`
QA / UAT	`https://qa.interswitchng.com`

Authentication

All balance endpoints require a Bearer token obtained from the Interswitch Passport authentication service. The token must include the merchant-wallet audience and relevant wallet actions in the JWT claims.

Include the token in the request header as follows:

Authorization: Bearer <access_token>

Note: The access token is short-lived. Obtain a fresh token before making API calls.

1. Wallet Balance

Retrieve the current wallet balance for a Quickteller terminal.

Endpoint

GET /quicktellerservice/api/v5/wallet/balance

Request

HTTP Method

GET

Required Headers

Header	Value	Description
`Authorization`	`Bearer <access_token>`	OAuth 2.0 bearer token
`Content-Type`	`application/json`	Optional, but recommended

Path Parameters

None.

Query Parameters

None.

Request Body

None.

Response

Success Response

HTTP Status: 200 OK

Content-Type: application/json

{
  "Balance": 1006310,
  "LedgerBalance": 1006310,
  "AvailableBalance": 1006310,
  "ResponseCode": "90000",
  "ResponseCodeGrouping": "SUCCESSFUL"
}

Response Fields

Field	Type	Description
`Balance`	integer	Current wallet book balance in minor units (e.g., kobo for NGN). Divide by 100 for the main currency value.
`LedgerBalance`	integer	Ledger balance in minor units.
`AvailableBalance`	integer	Available/withdrawable balance in minor units.
`ResponseCode`	string	Internal response code from the Quickteller service. `90000` indicates success.
`ResponseCodeGrouping`	string	High-level status grouping. `SUCCESSFUL` indicates the request was processed successfully.

Sample Request

curl --location 'https://orion.interswitchng.com/quicktellerservice/api/v5/wallet/balance' \
--header 'Authorization: Bearer <access_token>'

Replace <access_token> with a valid bearer token retrieved from the Interswitch Passport service.

Sample Response

{
  "Balance": 1006310,
  "LedgerBalance": 1006310,
  "AvailableBalance": 1006310,
  "ResponseCode": "90000",
  "ResponseCodeGrouping": "SUCCESSFUL"
}

2. Virtual Card Balance

Retrieve the current virtual card wallet balance for a Quickteller terminal.

Endpoint

GET /quicktellerservice/api/v5/wallet/virtualcardbalance

Request

HTTP Method

GET

Required Headers

Header	Value	Description
`Authorization`	`Bearer <access_token>`	OAuth 2.0 bearer token
`Cookie`	`BIGipServeruat_quickteller_service_pool=<value>`	Required in QA/UAT to maintain session affinity with the load balancer

Path Parameters

None.

Query Parameters

None.

Request Body

None.

Sample Request

curl --location 'https://qa.interswitchng.com/quicktellerservice/api/v5/wallet/virtualcardbalance' \
--header 'Cookie: BIGipServeruat_quickteller_service_pool=<cookie_value>' \
--header 'Authorization: Bearer <access_token>'

Replace <access_token> and <cookie_value> with valid values for your environment.

Response

Pending: The response payload for this endpoint has not been provided yet. Please share a sample response to complete this section.

Expected Response Structure

Based on the wallet balance endpoint, the response is expected to contain balance fields and a response code grouping. Update the table below once the actual response is confirmed.

Field	Type	Description
`Balance`	integer	Current virtual card wallet balance in minor units.
`LedgerBalance`	integer	Ledger balance in minor units.
`AvailableBalance`	integer	Available balance in minor units.
`ResponseCode`	string	Internal response code.
`ResponseCodeGrouping`	string	High-level status grouping.

Sample Response

{
  "Balance": 0,
  "LedgerBalance": 0,
  "AvailableBalance": 0,
  "ResponseCode": "90000",
  "ResponseCodeGrouping": "SUCCESSFUL"
}

Note: The values above are placeholders. Replace them with the actual response sample once available.

Common Response Codes

Virtual Card Balance

Response Code	Grouping	Description
`90000`	`SUCCESSFUL`	Balance retrieved successfully.
`70012`	`FAILED`	Unrecognised terminal owner.
`70040`	`FAILED`	Financial transactional card not configured.
`10001`	`FAILED`	Unexpected error while performing balance enquiry.
`<upstream>`	`FAILED`	Upstream ESB/Postilion balance-inquiry response code on failure.

Wallet Balance

Response Code	Grouping	Description
`90000`	`SUCCESSFUL`	Wallet balance retrieved successfully.
`70081`	`FAILED`	Terminal owner wallet details not configured.
`70082`	`FAILED`	Wallet service exception.
`70084`	`FAILED`	Failed to retrieve wallet details.
`70086`	`FAILED`	Wallet balance request did not return a successful result.
`90006`	`FAILED`	Generic wallet failure (DLL mapped code `06`).
`90009`	`PENDING`	Wallet transaction still in progress (DLL mapped code `09`).
`90051`	`PENDING`	Insufficient wallet funds (DLL mapped code `51`).
`10005`	`FAILED`	Empty or missing response code from wallet remote call.

Note: Actual response codes may vary based on the Quickteller service implementation. Refer to the latest Interswitch integration guide for the complete list.

Important Notes

All monetary values are returned in minor units. For Nigerian Naira (NGN), divide by 100 to get the main currency value (e.g., 1006310 kobo = NGN 10,063.10).
Use a valid bearer token scoped for balance enquiries.
Use the production base URL (orion.interswitchng.com) only for live transactions. Use qa.interswitchng.com for testing and integration validation.
The virtualcardbalance endpoint in QA/UAT requires a Cookie header for load-balancer session affinity.

Related Endpoints

GET /quicktellerservice/api/v5/wallet/balance — Retrieve main wallet balance.
GET /quicktellerservice/api/v5/wallet/virtualcardbalance — Retrieve virtual card wallet balance.