Virtual Account

Getting Started with the Virtual Account API

This guide will help you integrate virtual bank accounts into your application.

Try out the API in the reference page

Overview

The Virtual Account API allows you to:

Create virtual bank accounts for your users in NGN (Nigeria) and GHS (Ghana)
Query account details and balances
Retrieve transaction history
Calculate transfer fees

Quick Start

Step 1: Create a Virtual Account

Create a virtual bank account for your user:

curl -X POST "https://api.sandbox.esca.finance/v1/virtual-account" \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "email": "user@example.com",
    "externalReference": "user_12345"
  }'

Request Body Parameters:

Parameter	Type	Required	Description
`currency`	string	Yes	Currency for the account (`NGN` or `GHS`)
`email`	string	Yes	Email address for the account holder
`externalReference`	string	No	Your system's reference ID for this account

Step 2: Retrieve Account Details

Get the virtual account details, including the account number:

curl -X GET "https://api.sandbox.esca.finance/v1/virtual-account?currency=NGN" \
  -H "X-Api-Key: your_api_key_here"

To get a specific account by ID:

curl -X GET "https://api.sandbox.esca.finance/v1/virtual-account/123" \
  -H "X-Api-Key: your_api_key_here"

Step 3: Get Supported Banks

Get the list of supported banks for a country:

curl -X GET "https://api.sandbox.esca.finance/v1/virtual-account/banks?country=NG" \
  -H "X-Api-Key: your_api_key_here"

Query Parameters:

Parameter	Type	Required	Description
`country`	string	No	Country code (`NG` or `GH`, default: `NG`)

Response:

{
  "status": true,
  "data": [
    { "bankCode": "044", "bankName": "Access Bank" },
    { "bankCode": "023", "bankName": "Citibank Nigeria" }
  ]
}

Step 4: Query External Bank Accounts

Before making transfers, verify the recipient bank account details:

curl -X GET "https://api.sandbox.esca.finance/v1/virtual-account/account-query?bankCode=044&accountNumber=0123456789&country=NG" \
  -H "X-Api-Key: your_api_key_here"

Query Parameters:

Parameter	Type	Required	Description
`bankCode`	string	Yes	Bank code
`accountNumber`	string	Yes	Account number to query
`country`	string	No	Country code (default: `NG`)

Step 5: Get Transfer Fees

Calculate fees before initiating a transfer:

curl -X GET "https://api.sandbox.esca.finance/v1/virtual-account/transfer-fee?currency=NGN&amount=10000" \
  -H "X-Api-Key: your_api_key_here"

Query Parameters:

Parameter	Type	Required	Description
`currency`	string	Yes	Currency code (`NGN` or `GHS`)
`amount`	number	Yes	Transfer amount

Step 6: Initiate a Transfer

Send money from a virtual account to an external bank account:

curl -X POST "https://api.sandbox.esca.finance/v1/virtual-account/transfer" \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "accountId": 123,
    "amount": 10000,
    "destinationBankCode": "044",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "John Doe",
    "description": "Payment for services",
    "externalReference": "txn_abc123"
  }'

Request Body Parameters:

Parameter	Type	Required	Description
`currency`	string	Yes	Currency for the transfer (`NGN` or `GHS`)
`accountId`	integer	Yes	Source virtual account ID
`amount`	number	Yes	Transfer amount (min: 100 NGN or 15 GHS)
`destinationBankCode`	string	Yes	Recipient's bank code
`destinationAccountNumber`	string	Yes	Recipient's account number (10-15 digits)
`destinationAccountName`	string	Yes	Recipient's account name
`description`	string	Yes	Transfer narration/description
`externalReference`	string	No	Your system's reference for this transfer

Step 7: Monitor Transactions

Fetch transaction history for an account:

curl -X GET "https://api.sandbox.esca.finance/v1/virtual-account/transactions?accountId=123&page=1&limit=20" \
  -H "X-Api-Key: your_api_key_here"

Query Parameters:

Parameter	Type	Required	Description
`accountId`	integer	Yes	Account ID to fetch transactions for
`type`	string	No	Filter by type: `CREDIT` or `DEBIT`
`fromDate`	string	No	Start date (ISO 8601 format)
`toDate`	string	No	End date (ISO 8601 format)
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 20)

Supported Currencies

Currency	Country	Description
NGN	Nigeria	Nigerian Naira
GHS	Ghana	Ghanaian Cedi

Error Handling

The API uses standard HTTP response codes:

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
500	Internal Server Error

Error Response Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}