​

Transfer API Documentation

​

Overview

​

Base URL

​

Authentication

• X-API-KEY: Your API key
• X-Tenant-ID: Tenant identifier

​

Endpoints

​

Intra-Wallet Transfer

• X-API-KEY (optional): API key for authentication
• X-Tenant-ID: Tenant identifier

{
  "debitAccountId": "string",
  "recipientAccountId": "string",
  "amount": "number",
  "narration": "string",
  "requestId": "string",
  "currency": "string"
}

{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​

Deposit

• X-API-KEY (optional): API key for authentication
• X-Tenant-ID: Tenant identifier

{
  "recipientAccountId": "string",
  "amount": "number",
  "requestId": "string",
  "currency": "string",
  "narration": "string",
  "senderName": "string",
  "senderBank": "string",
  "senderAccountNumber": "string",
  "bankCode": "string"
}

{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​

Interbank Transfer

• X-API-KEY (optional): API key for authentication
• X-Tenant-ID: Tenant identifier

{
  "requestId": "string",
  "debitAccountId": "string",
  "currency": "string",
  "bankCode": "string",
  "recipientAccountNumber": "string",
  "amount": "number",
  "narration": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryPhone": "string"
}

{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​

Withdrawal

• X-API-KEY (optional): API key for authentication
• X-Tenant-ID: Tenant identifier

{
  "requestId": "string",
  "debitAccountId": "string",
  "recipientNuban": "string",
  "bankCode": "string",
  "bankName": "string",
  "bvn": "string",
  "narration": "string",
  "amount": "number",
  "currency": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryPhone": "string"
}

{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​

Error Responses

{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}

{
  "statusCode": 404,
  "message": "Account not found",
  "data": null
}

{
  "statusCode": 409,
  "message": "Duplicate request ID",
  "data": null
}

{
  "statusCode": 422,
  "message": "Insufficient funds",
  "data": null
}

​

Notes

• All timestamps are in ISO-8601 format
• Transfer types:
  • Intra-wallet: Transfer between accounts in the same wallet
  • Deposit: Funds coming into the wallet
  • Interbank: Transfer to external bank accounts
  • Withdrawal: Transfer to settlement bank accounts
• Transfer requirements:
  • Minimum transfer amount is 100
  • Accounts must be active
  • Source account must have sufficient balance
  • Currencies must match for intra-wallet transfers
  • Bank codes must be valid and supported
• Transfer processing:
  • All transfers are processed asynchronously
  • Response includes a request ID for tracking
  • Status updates are sent via notifications
  • Failed transfers can be retried
• Security measures:
  • All transfers require authentication
  • User must own the source account
  • Platform admins cannot perform transfers
  • Duplicate request IDs are rejected
• Transfer limits:
  • Subject to account tier limits
  • Subject to daily and monthly limits
  • Subject to bank-specific limits
• Transfer notifications:
  • Users are notified of transfer status changes
  • Notifications include transfer details
  • Failed transfers include reason for failure
• Transfer tracking:
  • All transfers are logged
  • Transfer history is maintained
  • Transfer status can be queried
• Transfer fees:
  • Fees are calculated based on transfer type
  • Fees are included in the transfer amount
  • Fee formulas are configurable
• Transfer validation:
  • Account numbers are validated
  • Bank codes are validated
  • Amounts are validated
  • Currencies are validated
• Transfer settlement:
  • Interbank transfers are settled via NIBSS
  • Withdrawals are settled to settlement accounts
  • Settlement status is tracked
  • Settlement failures are handled