Core Banking API Documentation

Generate Authentication Token

All clients who successfully register on our platform are issued access credentials with which they can generate a token. The generated token must be included in the Authorization header of every API request, using the required authentication scheme.

POST ${root_path_auth_server}/oauth2/token

Field	Type	Description	Constraints
`grant_type`	String	Specifies a server-to-server authentication type	Required
`scope`	String	Specific permissions or access rights (e.g. READ, WRITE)	Required

Note: This endpoint requires Basic Authentication. Username should be your client_id and password your client_secret, formatted as Authorization: Basic <Base64Encoded(client_id:client_secret)>

cURL Request

curl --location '${root_path}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <Base64Encoded(client_id:client_secret)>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=read'

Response : [200 OK]

{
  "access_token": "eyJraWQiOiJhNWE3YzQ2YS0y...",
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 86399
}

Add Customer

This operation provisions a new customer within the system and associates them with the specified institution. Once successfully created, the customer is granted the ability to initiate outbound transfers, access their wallet, and perform a wide range of supported banking transactions.

POST ${root_path}/api/client/add-customer

Field	Type	Description	Constraints
`firstName`	String	First name of the customer	Cannot be blank
`lastName`	String	Last name of the customer	Cannot be blank
`phoneNumber`	String	Phone number of the customer	Cannot be blank
`email`	String	Customer email	Must be valid and unique
`enableAccountNumber`	Boolean	Predicate to determine if account is enabled	Default: false
`bvn`	String	Bank Verification Number of the customer	Cannot be blank. Must be valid BVN
`dob`	LocalDate	Date of birth of the customer	Must follow pattern dd-MM-yyyy
`gender`	String	Gender	Male / Female
`address`	String	Customer address	Cannot be blank

Important: The access token required for this endpoint must be prefixed with Bearer_Auth in the Authorization header (e.g. Authorization: Bearer_Auth <token>).

cURL Request

curl --location '${root_path}/api/client/add-customer' \
--header 'Authorization: Bearer_Auth <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "firstName": "Richard",
  "lastName": "Stanley",
  "phoneNumber": "08061670369",
  "email": "rich.stan@gmail.com",
  "enableAccountNumber": true,
  "bvn": "22345678910",
  "dob": "19-09-2000",
  "gender": "Male",
  "address": "Richard'\''s avenue Houston Texas"
}'

Response : [200 OK]

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "id": 13,
    "accountNumber": "0007000011",
    "kycLevel": "ONE",
    "institutionCode": "REST1"
  }
}

Get Client Profile

Returns the calling client's own profile, resolved from the institutionCode in their access token.

GET ${root_path}/api/client/profile

cURL Request

curl -X GET '${root_path}/api/client/profile' \
--header 'Authorization: Bearer_Auth <token>'

Response : [200 OK]

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "id": 1,
    "companyName": "Richard_Soft",
    "institutionCode": "REST1",
    "status": "ACTIVE",
    "kycStatus": "VERIFIED",
    "accountNumber": "4011000115",
    "email": "stanley@richards.com"
  }
}

Get Customers

Returns a paged list of all customers belonging to the calling client's institution.

GET ${root_path}/api/client/customers

Field	Type	Description	Constraints
`pageNumber`	Integer	Page number (1-based)	Default: 1
`pageSize`	Integer	Number of records per page	Default: 20

cURL Request

curl -X GET '${root_path}/api/client/customers?pageNumber=1&pageSize=20' \
--header 'Authorization: Bearer_Auth <token>'

Response : [200 OK]

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "content": [ { "id": 13, "accountNumber": "0007000011" } ],
    "totalElements": 100,
    "totalPages": 5,
    "currentPage": 1
  }
}

Outbound Transfers (Client)

This allows institutions to make outward transfers to other financial institutions using funds from their wallet.

POST ${root_path}/api/transfer/process/client

Field	Type	Description	Constraints
`amount`	BigDecimal	Transaction amount	Not Null
`accountNumber`	String	Source account number	Cannot be blank. Must be valid
`narration`	String	Transaction narration	Optional
`beneficiaryName`	String	Transaction beneficiary name	Cannot be blank
`bankCode`	String	Destination bank code	Cannot be blank. Must be valid
`transactionPin`	String	Six-digit transaction PIN	Cannot be blank. Must be exactly 6 digits
`transactionReference`	String	Transaction reference	Cannot be blank
`remoteTransactionRef`	String	Remote transaction reference	Cannot be blank
`beneficiaryBvn`	String	BVN of the beneficiary	Cannot be blank. Must be valid BVN
`beneficiaryKyc`	String	KYC level of beneficiary	Cannot be blank
`channelCode`	String	Channel code of transaction	Cannot be blank

cURL Request

curl --location '${root_path}/api/transfer/process/client' \
--header 'Authorization: Bearer_Auth <token>' \
--header 'Content-Type: application/json' \
--data '{
  "amount": 100,
  "accountNumber": "1010101010",
  "narration": "This is a test Transaction",
  "beneficiaryName": "Richard",
  "bankCode": "000005",
  "transactionPin": "123456",
  "transactionReference": "5014c2f9-9452-4ec2-a705-7a0b681df856",
  "remoteTransactionRef": "090789250528144706456462487659",
  "beneficiaryBvn": "22345678912",
  "beneficiaryKyc": "1",
  "channelCode": "2"
}'

Response : [200 OK]

{
  "success": true,
  "responseCode": "200",
  "data": {
    "amount": 100,
    "transactionRef": "5014c2f9-9452-4ec2-a705-7a0b681df856"
  }
}

Outbound Transfers (Customer)

This functionality enables customers to initiate outward transfers to other financial institutions, utilizing the funds available in their wallet.

POST ${root_path}/api/transfer/process/customer

cURL Request

curl --location '${root_path}/api/transfer/process/customer' \
--header 'Authorization: Bearer_Auth <token>' \
--header 'Content-Type: application/json' \
--data '{
  "amount": 100,
  "customerId": 12,
  "accountNumber": "1010101010",
  "narration": "This is a test Transaction",
  "beneficiaryName": "Richard",
  "bankCode": "000005",
  "transactionPin": "123456",
  "transactionReference": "5014c2f9-9452-4ec2-a705-7a0b681df856",
  "remoteTransactionRef": "080789250528144706456462481111",
  "beneficiaryBvn": "22345678912",
  "beneficiaryKyc": "1",
  "channelCode": "2"
}'

Get Transactions

Returns all transactions for the calling client, paged and optionally filtered by date range and direction.

GET ${root_path}/api/client/transactions

Field	Type	Description	Constraints
`pageNumber`	Integer	Page number (1-based)	Default: 1
`pageSize`	Integer	Records per page	Default: 20
`startDateTime`	LocalDateTime	Start of date range	Format: yyyy-MM-dd HH:mm:ss
`endDateTime`	LocalDateTime	End of date range	Format: yyyy-MM-dd HH:mm:ss
`direction`	String	Filter by direction	OUTWARD \| INWARD

Get Transaction by Reference

Fetches a single transaction by its provider reference or internal transaction reference.

GET ${root_path}/api/client/transactions/{ref}

Get Customer Transactions

Fetches all transactions for a specific customer belonging to the calling client.

GET ${root_path}/api/client/customers/{customerId}/transactions

Check Transaction Status

Query the status of a previously initiated transaction by providing its unique reference number.

GET ${root_path}/api/transfer/transaction?transactionId={ref}

Get Transaction History [Inward]

Retrieves the complete history of all inward transactions associated with the customer's wallet.

GET ${root_path}/api/transfer/

Change PIN

Allows customers to securely update their transaction PIN.

POST ${root_path}/api/customer/set-transaction-pin

cURL Request

curl --location '${root_path}/api/customer/set-transaction-pin' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "transactionPin": "123456", "customerId": 12 }'

Partner Webhook Specification (Inward Transfer)

Specifies the webhook API that a partner must implement to receive inward transfer notifications from BankEasy Fulfillment Service.

POST {baseUrl}/inward-transfer

Field	Type	Description	Required
`accountNumber`	string	Beneficiary account number	Yes
`amount`	number (decimal)	Transfer amount	Yes
`transactionFee`	number (decimal)	Fee amount (nullable)	No
`narration`	string	Transfer narration	Yes
`transactionTime`	string	e.g. 2026-03-04T10:15:30	Yes
`originatingAccountName`	string	Sender account name	Yes
`originatingAccountNumber`	string	Sender account number	Yes
`signature`	string (Base64)	Ed25519 signature generated by BankEasy	Yes
`transactionReference`	string	Payment reference	Yes
`sessionId`	string	Unique session ID for idempotency	Yes

Signature Verification (Java)

Java Example

String payload = String.format("%s-%s-%s-%s",
  accountNumber, originatingAccountNumber, amount, sessionId);
byte[] keyBytes = Base64.getDecoder().decode(publicKeyBase64);
PublicKey publicKey = KeyFactory.getInstance("Ed25519")
  .generatePublic(new X509EncodedKeySpec(keyBytes));
Signature verifier = Signature.getInstance("Ed25519");
verifier.initVerify(publicKey);
verifier.update(payload.getBytes(StandardCharsets.UTF_8));
byte[] sig = Base64.getDecoder().decode(signatureBase64);
return verifier.verify(sig);