Skip to main content
GET
Get customer balances

Overview

Returns the available, pending, and locked NGN balance held for one of your customers. Use this endpoint after creating a permanent funding account with settlement_destination.type: CUSTOMER_NGN_BALANCE. The balance belongs to the customer identified by id; it is separate from your merchant balances returned by GET /v1/merchant/balance.

Authentication

string
required
Your merchant API key.

Path Parameters

string
required
Customer ID (UUID).

Request Example

Response

array
required
Balance entries for the customer. Customer balances currently use NGN.

Using the Balance

To send an NGN bank transfer from this balance, create the transfer with:
  • currency: NGN
  • debit_currency: NGN
  • debit_scope: CUSTOMER
  • on_behalf_of.customer_id set to this customer ID
The saved or inline recipient must belong to the same customer, and the customer must have completed Tier 1 KYC. See Create transfer.

Errors

  • 400: Invalid customer ID.
  • 401: Missing or invalid API key.
  • 403: Customer NGN balances are not enabled for the environment.
  • 404: Customer not found for the authenticated merchant.
  • 502: The balance provider could not return the balance.