Customer Bank Accounts

Manage a customer's saved payout accounts (bank transfer & mobile money).

Off-ramp payouts go to a saved payout account that belongs to the customer. These endpoints let a customer add, list, set primary, and remove their accounts. The off-ramp checkout confirm step references one of these accounts by id.

All routes are authenticated as the customer (Authorization: Bearer <customer_jwt>) and operate on the authenticated customer's own accounts (/customers/me/...). The hosted checkout manages these for the customer; you only need them if you build your own UI. See how to get a customer JWT.

Account types & rails

There are two account types. The right one is determined by the payout currency:

Type	Currencies	Required fields
BANK_TRANSFER	NGN (NIBSS), ZAR (EFT), USD	accountName, accountNumber, bankCode
MOBILE_MONEY	UGX, GHS, KES, TZS, RWF, ZMW, XOF, XAF, CDF, ETB, LSL, MWK, MZN, SLE	accountNumber (E.164 phone), operator

---

Add a bank account

POST /v1/customers/me/bank-accounts

Request body

Field	Type	Required	Description
type	string	Yes	BANK_TRANSFER or MOBILE_MONEY
countryId	string (UUID)	Yes	A supported country id. Fetch from GET /v1/countries (public, no auth).
currency	string	Yes	Payout currency. See Supported Currencies
accountNumber	string	Yes	Bank account number (BANK_TRANSFER) or E.164 phone (MOBILE_MONEY)
accountName	string	BANK_TRANSFER only	Account holder name (resolve via Resolve Bank Account)
bankCode	string	BANK_TRANSFER only	Bank code. See Get Banks by Currency
bankName	string	No	Display name of the bank
operator	string	MOBILE_MONEY only	Mobile-money operator code, e.g. MTN_MOMO_UGA, MPESA_KEN, MTN_MOMO_GHA

Getting countryId: call GET /v1/countries (public, no auth) and use the matching country's id. Filter to a single currency with GET /v1/countries/by-currency/:symbol (e.g. /by-currency/UGX).

Example — NGN bank account (BANK_TRANSFER)

curl -X POST https://ramp-api.ivorypay.io/api/v1/customers/me/bank-accounts \
  -H "Authorization: Bearer <customer_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BANK_TRANSFER",
    "countryId": "<nigeria_country_uuid>",
    "currency": "NGN",
    "accountName": "Amina Okafor",
    "accountNumber": "0123456789",
    "bankCode": "058",
    "bankName": "GTBank"
  }'

Example — ZAR EFT account (BANK_TRANSFER)

curl -X POST https://ramp-api.ivorypay.io/api/v1/customers/me/bank-accounts \
  -H "Authorization: Bearer <customer_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BANK_TRANSFER",
    "countryId": "<south_africa_country_uuid>",
    "currency": "ZAR",
    "accountName": "Amina Okafor",
    "accountNumber": "62012345678",
    "bankCode": "250655",
    "bankName": "FNB"
  }'

Example — UGX mobile money (MOBILE_MONEY)

curl -X POST https://ramp-api.ivorypay.io/api/v1/customers/me/bank-accounts \
  -H "Authorization: Bearer <customer_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MOBILE_MONEY",
    "countryId": "<uganda_country_uuid>",
    "currency": "UGX",
    "accountNumber": "[phone]",
    "operator": "MTN_MOMO_UGA"
  }'

Example response

{
  "success": true,
  "message": "Query successful",
  "data": {
    "id": "9f1c2b34-5d6e-7f80-91a2-b3c4d5e6f708",
    "type": "MOBILE_MONEY",
    "currency": "UGX",
    "accountName": null,
    "accountNumber": "[phone]",
    "bankCode": null,
    "bankName": "MTN Mobile Money",
    "operator": "MTN_MOMO_UGA",
    "isPrimary": true,
    "status": "ACTIVE",
    "createdAt": "2026-03-26T12:00:00.000Z"
  }
}

The id is what you pass as bankAccountId to Confirm Off-Ramp Checkout.

---

List bank accounts

GET /v1/customers/me/bank-accounts

Returns the authenticated customer's saved accounts.

{
  "success": true,
  "message": "Query successful",
  "data": [
    {
      "id": "9f1c2b34-5d6e-7f80-91a2-b3c4d5e6f708",
      "type": "MOBILE_MONEY",
      "currency": "UGX",
      "accountNumber": "[phone]",
      "operator": "MTN_MOMO_UGA",
      "bankName": "MTN Mobile Money",
      "isPrimary": true,
      "status": "ACTIVE"
    },
    {
      "id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
      "type": "BANK_TRANSFER",
      "currency": "NGN",
      "accountName": "Amina Okafor",
      "accountNumber": "0123456789",
      "bankCode": "058",
      "bankName": "GTBank",
      "isPrimary": false,
      "status": "ACTIVE"
    }
  ]
}

---

Set an account as primary

PATCH /v1/customers/me/bank-accounts/:id/primary

Marks the account as the customer's default payout destination.

Remove a bank account

DELETE /v1/customers/me/bank-accounts/:id

Related

• Confirm Off-Ramp Checkout

• Resolve Bank Account

• Get Banks by Currency

• Hosted Checkout guide