The Nomba Transfers API provides endpoints for initiating and managing fund transfers. Developers can look up bank codes and names, verify account details, and initiate transfers to Nigerian bank accounts. The API supports domestic money transfers and provides the necessary bank metadata for building payment flows within applications.
openapi: 3.1.0
info:
title: Nomba Transfers API
description: >-
The Nomba Transfers API provides endpoints for initiating and managing
fund transfers. Developers can look up bank codes and names, verify
account details, initiate transfers to Nigerian bank accounts, and
transfer funds between Nomba wallets. The API supports domestic money
transfers and provides the necessary bank metadata for building payment
flows within applications.
version: '1.0.0'
contact:
name: Nomba Developer Support
url: https://developer.nomba.com
termsOfService: https://nomba.com/terms
externalDocs:
description: Nomba Transfers API Documentation
url: https://developer.nomba.com/nomba-api-reference/transfers/fetch-bank-codes-and-names
servers:
- url: https://api.nomba.com
description: Production Server
- url: https://sandbox.nomba.com
description: Sandbox Server
tags:
- name: Transfers
description: >-
Endpoints for bank lookups, account verification, and initiating
domestic fund transfers to bank accounts and between wallets.
security:
- bearerAuth: []
paths:
/v1/transfers/banks:
get:
operationId: fetchBankCodes
summary: Fetch bank codes and names
description: >-
Retrieves a list of all supported Nigerian banks along with their
corresponding bank codes. These codes are required when initiating
transfers to bank accounts.
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/accountId'
responses:
'200':
description: Bank list retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BankListResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/transfers/bank/lookup:
post:
operationId: performBankAccountLookup
summary: Perform bank account lookup
description: >-
Verifies a bank account by looking up the account number and bank
code. Returns the account holder name if the account is valid. This
should be called before initiating a transfer to confirm the
recipient details.
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- accountNumber
- bankCode
properties:
accountNumber:
type: string
description: >-
The bank account number to look up.
pattern: '^\d{10}$'
example: '0123456789'
bankCode:
type: string
description: >-
The bank code identifying the financial institution.
example: '058'
responses:
'200':
description: Account lookup successful
content:
application/json:
schema:
$ref: '#/components/schemas/BankAccountLookupResponse'
'400':
description: Invalid account number or bank code
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/transfers/bank:
post:
operationId: transferToBank
summary: Transfer to a bank account
description: >-
Initiates a fund transfer from the authenticated Nomba account to an
external Nigerian bank account. Requires the recipient account
number, bank code, amount, and a unique merchant transaction
reference.
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount
- accountNumber
- accountName
- bankCode
- merchantTxRef
properties:
amount:
type: number
format: double
description: >-
The amount to transfer in the smallest currency unit (kobo).
minimum: 1
example: 10000
accountNumber:
type: string
description: >-
The recipient bank account number.
pattern: '^\d{10}$'
example: '0123456789'
accountName:
type: string
description: >-
The name of the recipient account holder.
example: John Doe
bankCode:
type: string
description: >-
The bank code of the recipient financial institution.
example: '058'
merchantTxRef:
type: string
description: >-
A unique transaction reference provided by the merchant
for idempotency and reconciliation.
example: txn_ref_12345
narration:
type: string
description: >-
An optional description or note for the transfer.
maxLength: 100
example: Payment for services
responses:
'200':
description: Transfer initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TransferResponse'
'400':
description: Invalid transfer parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/transfers/wallet:
post:
operationId: transferBetweenAccounts
summary: Transfer between Nomba accounts
description: >-
Initiates a wallet-to-wallet transfer between two Nomba accounts.
Enables instant movement of funds between accounts on the Nomba
platform without going through external banking rails.
tags:
- Transfers
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount
- receiverAccountId
- merchantTxRef
properties:
amount:
type: number
format: double
description: >-
The amount to transfer.
minimum: 1
example: 5000
receiverAccountId:
type: string
description: >-
The account ID of the recipient Nomba account.
example: 5f04b9ee600f1c00084affa2
merchantTxRef:
type: string
description: >-
A unique transaction reference for idempotency and
reconciliation.
example: wallet_txn_12345
narration:
type: string
description: >-
An optional description or note for the transfer.
maxLength: 100
responses:
'200':
description: Wallet transfer completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TransferResponse'
'400':
description: Invalid transfer parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth2 bearer token obtained from the Nomba Authentication API.
parameters:
accountId:
name: accountId
in: header
required: true
description: >-
The unique identifier of the parent business account.
schema:
type: string
schemas:
BankListResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
data:
type: object
properties:
results:
type: array
description: >-
List of supported banks.
items:
$ref: '#/components/schemas/Bank'
BankAccountLookupResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
data:
type: object
properties:
accountNumber:
type: string
description: >-
The verified bank account number.
accountName:
type: string
description: >-
The name of the account holder as registered with the bank.
bankCode:
type: string
description: >-
The bank code of the financial institution.
TransferResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
data:
type: object
properties:
transactionId:
type: string
description: >-
The unique identifier for the transfer transaction.
status:
type: string
description: >-
The current status of the transfer.
enum:
- pending
- successful
- failed
amount:
type: number
format: double
description: >-
The amount transferred.
fee:
type: number
format: double
description: >-
The fee charged for the transfer.
merchantTxRef:
type: string
description: >-
The merchant transaction reference provided in the request.
createdAt:
type: string
format: date-time
description: >-
The date and time the transfer was initiated.
Bank:
type: object
properties:
bankCode:
type: string
description: >-
The unique code identifying the bank.
example: '058'
bankName:
type: string
description: >-
The official name of the bank.
example: Guaranty Trust Bank
ErrorResponse:
type: object
properties:
code:
type: string
description: >-
Error status code.
description:
type: string
description: >-
Human-readable description of the error.
errors:
type: array
description: >-
List of specific error details.
items:
type: string