Skip to main content

​
Transfer API Documentation

​
Overview

The Transfer API provides endpoints for managing various types of transfers in the wallet service, including intra-wallet transfers, deposits, interbank transfers, and withdrawals.

​
Base URL

/api/v1/transfers

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key
  • X-Tenant-ID: Tenant identifier

​
Endpoints

​
Intra-Wallet Transfer

Transfer funds between accounts within the same wallet. Endpoint: POST /intra Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
Request Body: 
{
  "debitAccountId": "string",
  "recipientAccountId": "string",
  "amount": "number",
  "narration": "string",
  "requestId": "string",
  "currency": "string"
}
Response: 
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​
Deposit

Deposit funds into a wallet account. Endpoint: POST /deposit Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
Request Body: 
{
  "recipientAccountId": "string",
  "amount": "number",
  "requestId": "string",
  "currency": "string",
  "narration": "string",
  "senderName": "string",
  "senderBank": "string",
  "senderAccountNumber": "string",
  "bankCode": "string"
}
Response: 
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​
Interbank Transfer

Transfer funds from a wallet account to an external bank account. Endpoint: POST /inter Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
Request Body: 
{
  "requestId": "string",
  "debitAccountId": "string",
  "currency": "string",
  "bankCode": "string",
  "recipientAccountNumber": "string",
  "amount": "number",
  "narration": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryPhone": "string"
}
Response: 
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​
Withdrawal

Withdraw funds from a wallet account to a settlement bank account. Endpoint: POST /withdrawal Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
Request Body: 
{
  "requestId": "string",
  "debitAccountId": "string",
  "recipientNuban": "string",
  "bankCode": "string",
  "bankName": "string",
  "bvn": "string",
  "narration": "string",
  "amount": "number",
  "currency": "string",
  "beneficiaryName": "string",
  "beneficiaryEmail": "string",
  "beneficiaryPhone": "string"
}
Response: 
{
  "statusCode": 202,
  "message": "string",
  "data": "string"
}

​
Error Responses

All endpoints may return the following error responses: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "Account not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "Duplicate request ID",
  "data": null
}
422 Unprocessable Entity 
{
  "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