Payments API

This is the Payments API that provides programmatic access to various resources and services. The API supports the following areas: Fund Own Accounts, Bill Payments, Bank Transactions, Mobile Money Transactions, Loan Repayments. All endpoints require authentication using a Bearer token.

The payments model

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

Properties

Name
billerId
Type
string
Description
Value for billerId
Name
accountNumber
Type
string
Description
Value for accountNumber
Name
customerName
Type
string
Description
Value for customerName
Name
amount
Type
integer
Description
Integer value for amount
Name
currency
Type
string
Description
Value for currency
Name
paymentType
Type
string
Description
Value for paymentType
Name
sourceAccount
Type
string
Description
Value for sourceAccount
Name
narration
Type
string
Description
Value for narration
Name
reference
Type
string
Description
Value for reference

Initiate Bills Payment

Executes a payment transaction for a biller using account funds.

Request

POST

/v1/payments/bills

curl -X POST https://api.adiba.app/v1/payments/bills \
  -H "Authorization: Bearer {token}" \
  -d '{
"billerId": "IKEDC001",
"accountNumber": "123456789",
"customerName": "John Doe",
"amount": 5000,
"currency": "NGN",
"paymentType": "POSTPAID",
"sourceAccount": "ACC_001",
"narration": "Electricity bill payment",
"reference": "BILL_REF_001"
}'

{
"status": "SUCCESS",
"transactionId": "TXN_001_20241201_001",
"billerId": "IKEDC001",
"billerName": "Ikeja Electric",
"accountNumber": "123456789",
"customerName": "John Doe",
"amount": 5000,
"currency": "NGN",
"paymentType": "POSTPAID",
"sourceAccount": "ACC_001",
"narration": "Electricity bill payment",
"reference": "BILL_REF_001",
"processedAt": "2024-12-01T10:30:00Z",
"receiptUrl": "https://receipts.bank.com/TXN_001_20241201_001.pdf",
"message": "Bill payment processed successfully"
}

Fund Saving Account From Card

Transfers funds into a savings account from a linked debit/credit card.

Request

POST

/v1/payments/fund/via/card

curl -X POST https://api.adiba.app/v1/payments/fund/via/card \
  -H "Authorization: Bearer {token}" \
  -d '{
"cardId": "CARD_001",
"destinationAccount": "SAV_001",
"amount": 100000,
"currency": "NGN",
"narration": "Monthly savings contribution",
"reference": "SAV_REF_001"
}'

{
"status": "SUCCESS",
"transactionId": "TXN_002_20241201_001",
"cardId": "CARD_001",
"cardNumber": "**** **** **** 1234",
"destinationAccount": "SAV_001",
"amount": 100000,
"currency": "NGN",
"narration": "Monthly savings contribution",
"reference": "SAV_REF_001",
"processedAt": "2024-12-01T10:35:00Z",
"message": "Account funded successfully"
}

Fund Saving Account From Mobile Wallet

Moves money from a mobile wallet into a savings account.

Request

POST

/v1/payments/fund/via/mwallet

curl -X POST https://api.adiba.app/v1/payments/fund/via/mwallet \
  -H "Authorization: Bearer {token}" \
  -d '{
"walletProvider": "PAGA",
"phoneNumber": "+2348012345678",
"destinationAccount": "SAV_001",
"amount": 50000,
"currency": "NGN",
"narration": "Wallet to savings transfer",
"reference": "WALLET_REF_001"
}'

{
"status": "SUCCESS",
"transactionId": "TXN_003_20241201_001",
"walletProvider": "PAGA",
"phoneNumber": "+2348012345678",
"destinationAccount": "SAV_001",
"amount": 50000,
"currency": "NGN",
"narration": "Wallet to savings transfer",
"reference": "WALLET_REF_001",
"processedAt": "2024-12-01T10:40:00Z",
"message": "Account funded successfully from wallet"
}

Initiate Intra-Bank Transfer

Transfers funds between accounts within the same bank.

Request

POST

/v1/payments/transfer/internal

curl -X POST https://api.adiba.app/v1/payments/transfer/internal \
  -H "Authorization: Bearer {token}" \
  -d '{
"sourceAccount": "ACC_001",
"destinationAccount": "9876543210",
"destinationName": "Jane Smith",
"amount": 25000,
"currency": "NGN",
"narration": "Lunch money",
"reference": "INT_REF_001",
"saveAsBeneficiary": true
}'

{
"status": "SUCCESS",
"transactionId": "TXN_004_20241201_001",
"sourceAccount": "ACC_001",
"destinationAccount": "9876543210",
"destinationName": "Jane Smith",
"amount": 25000,
"currency": "NGN",
"narration": "Lunch money",
"reference": "INT_REF_001",
"transferType": "INTERNAL",
"processedAt": "2024-12-01T10:45:00Z",
"message": "Internal transfer completed successfully"
}

Initiate Own Account Transfer

Moves funds between a user's personal accounts at the same institution.

Request

POST

/v1/payments/transfer/self

curl -X POST https://api.adiba.app/v1/payments/transfer/self \
  -H "Authorization: Bearer {token}" \
  -d '{
"sourceAccount": "ACC_001",
"destinationAccount": "SAV_001",
"amount": 75000,
"currency": "NGN",
"narration": "Transfer to savings",
"reference": "SELF_REF_001"
}'

{
"status": "SUCCESS",
"transactionId": "TXN_005_20241201_001",
"sourceAccount": "ACC_001",
"destinationAccount": "SAV_001",
"amount": 75000,
"currency": "NGN",
"narration": "Transfer to savings",
"reference": "SELF_REF_001",
"transferType": "SELF",
"processedAt": "2024-12-01T10:50:00Z",
"message": "Self transfer completed successfully"
}

Initiate Inter-Bank Transfer

Executes a transfer of funds to an account at a different bank.

Request

POST

/v1/payments/transfer/external

curl -X POST https://api.adiba.app/v1/payments/transfer/external \
  -H "Authorization: Bearer {token}" \
  -d '{
"sourceAccount": "ACC_001",
"destinationAccount": "1234567890",
"destinationName": "John Doe",
"bankCode": "044",
"bankName": "Access Bank",
"amount": 100000,
"currency": "NGN",
"narration": "Business payment",
"reference": "EXT_REF_001",
"saveAsBeneficiary": true
}'

{
"status": "SUCCESS",
"transactionId": "TXN_006_20241201_001",
"sourceAccount": "ACC_001",
"destinationAccount": "1234567890",
"destinationName": "John Doe",
"bankCode": "044",
"bankName": "Access Bank",
"amount": 100000,
"currency": "NGN",
"narration": "Business payment",
"reference": "EXT_REF_001",
"transferType": "EXTERNAL",
"processedAt": "2024-12-01T10:55:00Z",
"estimatedDeliveryTime": "Within 24 hours",
"message": "External transfer initiated successfully"
}

Initiate Mobile Wallet Payment

Sends funds from a bank account to a specified mobile wallet.

Request

POST

/v1/payments/transfer/mwallet

curl -X POST https://api.adiba.app/v1/payments/transfer/mwallet \
  -H "Authorization: Bearer {token}" \
  -d '{
"sourceAccount": "ACC_001",
"phoneNumber": "+2348012345678",
"walletProvider": "PAGA",
"amount": 15000,
"currency": "NGN",
"narration": "Wallet funding",
"reference": "MWALLET_REF_001",
"saveAsBeneficiary": true
}'

{
"status": "SUCCESS",
"transactionId": "TXN_007_20241201_001",
"sourceAccount": "ACC_001",
"phoneNumber": "+2348012345678",
"walletProvider": "PAGA",
"amount": 15000,
"currency": "NGN",
"narration": "Wallet funding",
"reference": "MWALLET_REF_001",
"transferType": "MWALLET",
"processedAt": "2024-12-01T11:00:00Z",
"estimatedDeliveryTime": "Instant",
"message": "Mobile wallet payment completed successfully"
}

List Internal Destination Banks

Fetches a list of all banks supported for intra-bank transfers.

Request

GET

/v1/payments/banks/internal

curl -G https://api.adiba.app/v1/payments/banks/internal \
  -H "Authorization: Bearer {token}"

{
"banks": [
    {
        "bankCode": "001",
        "bankName": "Digital Bank",
        "bankType": "COMMERCIAL",
        "isActive": true,
        "logo": "https://cdn.bank.com/banks/digital-bank.png",
        "transferChannels": [
            "MOBILE_APP",
            "WEB",
            "USSD"
        ]
    },
    {
        "bankCode": "002",
        "bankName": "Digital Microfinance",
        "bankType": "MICROFINANCE",
        "isActive": true,
        "logo": "https://cdn.bank.com/banks/digital-mf.png",
        "transferChannels": [
            "MOBILE_APP",
            "USSD"
        ]
    }
],
"totalBanks": 2
}

List External Destination Banks

Retrieves a comprehensive list of all banks for inter-bank transfers.

Request

GET

/v1/payments/banks/external

curl -G https://api.adiba.app/v1/payments/banks/external \
  -H "Authorization: Bearer {token}"

{
"banks": [
    {
        "bankCode": "044",
        "bankName": "Access Bank",
        "bankType": "COMMERCIAL",
        "isActive": true,
        "logo": "https://cdn.bank.com/banks/access-bank.png",
        "transferChannels": [
            "NIBSS",
            "RTGS"
        ],
        "processingTime": "Within 24 hours"
    },
    {
        "bankCode": 58,
        "bankName": "GT Bank",
        "bankType": "COMMERCIAL",
        "isActive": true,
        "logo": "https://cdn.bank.com/banks/gt-bank.png",
        "transferChannels": [
            "NIBSS",
            "RTGS"
        ],
        "processingTime": "Within 24 hours"
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 150,
    "hasNext": true,
    "hasPrevious": false
}
}

List Beneficiaries of External Transfer

Displays saved recipients for transfers to other banks.

Request

GET

/v1/payments/beneficiaries/external

curl -G https://api.adiba.app/v1/payments/beneficiaries/external \
  -H "Authorization: Bearer {token}"

{
"beneficiaries": [
    {
        "beneficiaryId": "BEN_001",
        "accountNumber": "1234567890",
        "accountName": "John Doe",
        "bankCode": "044",
        "bankName": "Access Bank",
        "nickname": "John's Account",
        "isFavorite": true,
        "lastUsed": "2024-12-01T10:55:00Z",
        "transferCount": 5
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 1,
    "hasNext": false,
    "hasPrevious": false
}
}

List Beneficiaries of Internal Transfer

Shows saved recipients for transfers within the same bank.

Request

GET

/v1/payments/beneficiaries/internal

curl -G https://api.adiba.app/v1/payments/beneficiaries/internal \
  -H "Authorization: Bearer {token}"

{
"beneficiaries": [
    {
        "beneficiaryId": "BEN_002",
        "accountNumber": "9876543210",
        "accountName": "Jane Smith",
        "nickname": "Jane's Account",
        "isFavorite": false,
        "lastUsed": "2024-12-01T10:45:00Z",
        "transferCount": 3
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 1,
    "hasNext": false,
    "hasPrevious": false
}
}

List Beneficiaries of Bills Payments

Fetches a list of all saved biller accounts for quick payments.

Request

GET

/v1/payments/beneficiaries/bills

curl -G https://api.adiba.app/v1/payments/beneficiaries/bills \
  -H "Authorization: Bearer {token}"

{
"beneficiaries": [
    {
        "beneficiaryId": "BEN_003",
        "billerId": "IKEDC001",
        "billerName": "Ikeja Electric",
        "accountNumber": "123456789",
        "customerName": "John Doe",
        "nickname": "Home Electricity",
        "isFavorite": true,
        "lastUsed": "2024-12-01T10:30:00Z",
        "paymentCount": 12
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 1,
    "hasNext": false,
    "hasPrevious": false
}
}

List Beneficiaries for Mobile Wallet

Displays saved mobile wallet recipients for future transfers.

Request

GET

/v1/payments/beneficiaries/mwallet

curl -G https://api.adiba.app/v1/payments/beneficiaries/mwallet \
  -H "Authorization: Bearer {token}"

{
"beneficiaries": [
    {
        "beneficiaryId": "BEN_004",
        "phoneNumber": "+2348012345678",
        "walletProvider": "PAGA",
        "nickname": "Mom's Wallet",
        "isFavorite": true,
        "lastUsed": "2024-12-01T11:00:00Z",
        "transferCount": 8
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 1,
    "hasNext": false,
    "hasPrevious": false
}
}

Initiate a Loan Repayment

Makes a scheduled or ad-hoc payment towards an outstanding loan.

Required attributes

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

Request

POST

/v1/payments/loans/{loanId}

curl -X POST https://api.adiba.app/v1/payments/loans/{loanId} \
  -H "Authorization: Bearer {token}" \
  -d '{
"amount": 48500,
"currency": "NGN",
"paymentType": "SCHEDULED",
"sourceAccount": "ACC_001",
"narration": "Monthly loan repayment",
"reference": "LOAN_REF_001"
}'

{
"status": "SUCCESS",
"transactionId": "TXN_008_20241201_001",
"loanId": "LOAN_001_20241201_001",
"loanNumber": "LN_20241201_001",
"amount": 48500,
"currency": "NGN",
"paymentType": "SCHEDULED",
"sourceAccount": "ACC_001",
"narration": "Monthly loan repayment",
"reference": "LOAN_REF_001",
"processedAt": "2024-12-01T11:05:00Z",
"remainingBalance": 958333,
"nextPaymentDate": "2025-02-01T00:00:00Z",
"message": "Loan repayment processed successfully"
}