Beneficiaries API

This is the Beneficiaries API that provides programmatic access to various resources and services. The API supports the following areas: Beneficiary Management. All endpoints require authentication using a Bearer token.

The beneficiaries model

The beneficiaries model contains all the information about your beneficiaries entities.

Properties

Name
accountNumber
Type
string
Description
Value for accountNumber
Name
accountName
Type
string
Description
Value for accountName
Name
bankCode
Type
string
Description
Value for bankCode
Name
bankName
Type
string
Description
Value for bankName
Name
nickname
Type
string
Description
Value for nickname
Name
transferType
Type
string
Description
Value for transferType
Name
isFavorite
Type
boolean
Description
Boolean flag indicating isFavorite

Create Beneficiaries for External Transfer

Saves a new recipient's details for future inter-bank transfers.

Request

POST

/v1/payments/beneficiaries/external

curl -X POST https://api.adiba.app/v1/payments/beneficiaries/external \
  -H "Authorization: Bearer {token}" \
  -d '{
"accountNumber": "1234567890",
"accountName": "John Doe",
"bankCode": "044",
"bankName": "Access Bank",
"nickname": "John's Account",
"transferType": "EXTERNAL",
"isFavorite": true
}'

{
"beneficiaryId": "BEN_001_20241201_001",
"status": "CREATED",
"accountNumber": "1234567890",
"accountName": "John Doe",
"bankCode": "044",
"bankName": "Access Bank",
"nickname": "John's Account",
"transferType": "EXTERNAL",
"isFavorite": true,
"createdAt": "2024-12-01T10:30:00Z",
"message": "Beneficiary created successfully"
}

Create Beneficiaries for Internal Transfer

Saves a new recipient's details for future intra-bank transfers.

Request

POST

/v1/payments/beneficiaries/internal

curl -X POST https://api.adiba.app/v1/payments/beneficiaries/internal \
  -H "Authorization: Bearer {token}" \
  -d '{
"accountNumber": "9876543210",
"accountName": "Jane Smith",
"nickname": "Jane's Savings",
"transferType": "INTERNAL",
"isFavorite": false
}'

{
"beneficiaryId": "BEN_002_20241201_001",
"status": "CREATED",
"accountNumber": "9876543210",
"accountName": "Jane Smith",
"nickname": "Jane's Savings",
"transferType": "INTERNAL",
"isFavorite": false,
"createdAt": "2024-12-01T10:35:00Z",
"message": "Internal beneficiary created successfully"
}

Create Beneficiaries for Bills Payments

Saves a new biller account for streamlined, future bill payments.

Request

POST

/v1/payments/beneficiaries/bills

curl -X POST https://api.adiba.app/v1/payments/beneficiaries/bills \
  -H "Authorization: Bearer {token}" \
  -d '{
"billerId": "IKEDC001",
"billerName": "Ikeja Electric",
"accountNumber": "123456789",
"customerName": "John Doe",
"nickname": "Home Electricity",
"transferType": "BILLS",
"isFavorite": true
}'

{
"beneficiaryId": "BEN_003_20241201_001",
"status": "CREATED",
"billerId": "IKEDC001",
"billerName": "Ikeja Electric",
"accountNumber": "123456789",
"customerName": "John Doe",
"nickname": "Home Electricity",
"transferType": "BILLS",
"isFavorite": true,
"createdAt": "2024-12-01T10:40:00Z",
"message": "Bills beneficiary created successfully"
}

Create Beneficiaries for Mobile Wallet

Adds and saves a new mobile wallet recipient for transfers.

Request

POST

/v1/payments/beneficiaries/mwallet

curl -X POST https://api.adiba.app/v1/payments/beneficiaries/mwallet \
  -H "Authorization: Bearer {token}" \
  -d '{
"phoneNumber": "+2348012345678",
"walletProvider": "PAGA",
"nickname": "Mom's Wallet",
"transferType": "MWALLET",
"isFavorite": true
}'

{
"beneficiaryId": "BEN_004_20241201_001",
"status": "CREATED",
"phoneNumber": "+2348012345678",
"walletProvider": "PAGA",
"nickname": "Mom's Wallet",
"transferType": "MWALLET",
"isFavorite": true,
"createdAt": "2024-12-01T10:45:00Z",
"message": "Mobile wallet beneficiary created successfully"
}

Delete Payment Beneficiary

Removes a saved payment recipient from the user's beneficiary list.

Required attributes

Name
beneficiaryId
Type
string
Description
Unique identifier specified in the URL path

Request

DELETE

/v1/payments/beneficiaries/{beneficiaryId}

curl -X DELETE https://api.adiba.app/v1/payments/beneficiaries/{beneficiaryId} \
  -H "Authorization: Bearer {token}" \
  -d '{
"example": "data"
}'

{
"status": "SUCCESS",
"beneficiaryId": "BEN_001_20241201_001",
"deletedAt": "2024-12-01T11:00:00Z",
"message": "Beneficiary deleted successfully"
}