Initiate Transfer

Send money from your virtual account to any bank account.

POST /v1/virtual-account/transfer

Headers

Header	Required	Description
`X-Api-Key`	Yes	Your API key
`X-Idempotency-Key`	Yes	Unique key to prevent duplicate transfers
`Content-Type`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`currency`	string	Yes	Currency: `NGN` or `GHS`
`accountId`	integer	Yes	Source virtual account ID
`amount`	number	Yes	Amount to transfer
`destinationBankCode`	string	Yes	Destination bank code (retrieve from Banks endpoint)
`destinationAccountNumber`	string	Yes	Destination account number
`destinationAccountName`	string	Yes	Destination account name
`description`	string	Yes	Transfer description/narration
`externalReference`	string	No	Your unique reference for this transfer. Can be used to query the transfer later. Must be unique per account.

Account Verification

Before processing a transfer, the API automatically verifies the destination account.

Verification Error Examples

Account not found:

{
  "statusCode": 400,
  "status": false,
  "message": "Could not verify destination account. Please check the bank code and account number."
}

Name mismatch:

{
  "statusCode": 400,
  "status": false,
  "message": "Account name mismatch. Resolved: 'JOHN ADEBAYO DOE', Provided: 'JANE DOE'"
}

Tip: Use the Account Query endpoint to verify account details before initiating a transfer.

Example Request

curl -X POST "https://api.esca.finance/v1/virtual-account/transfer" \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Idempotency-Key: transfer-550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "accountId": 12345,
    "amount": 10000,
    "destinationBankCode": "000007",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JOHN DOE",
    "description": "Payment for services",
    "externalReference": "INV-2026-001"
  }'

Example Response

{
  "status": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Using External Reference

The externalReference field allows you to attach your own identifier to a transfer. This is useful for:

Reconciliation: Link transfers to your internal records (invoices, orders, etc.)
Querying: Retrieve transfer status using your own reference instead of the UUID
Idempotency: While X-Idempotency-Key prevents duplicate API calls, externalReference helps you track transfers in your system

Uniqueness

External references are unique per account. This means:

Account A can have a transfer with externalReference: "INV-001"
Account B can also have a transfer with externalReference: "INV-001"
But Account A cannot have two transfers with the same external reference

If you attempt to create a transfer with a duplicate external reference for the same account, you will receive a 400 Bad Request error:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "A transfer with external reference 'INV-001' already exists for this account"
}

Querying by External Reference

See Get Transfer Status to learn how to query transfers using your external reference.

Transfer Status Flow

PENDING → SUCCESS
        → FAILED
        → REVERSED

Transfer Fee

Transfer Status