Get Transfer Status

Check the status of a transfer using its UUID or your external reference.

Get Transfer by UUID

GET /v1/virtual-account/transfer/:uuid

Path Parameters

Parameter	Type	Required	Description
`uuid`	string	Yes	Transfer UUID returned when the transfer was initiated

Example Request

curl -X GET "https://api.esca.finance/v1/virtual-account/transfer/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: your_api_key_here"

Example Response

{
  "status": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SUCCESS",
    "amount": 10000,
    "fee": 10.75,
    "currency": "NGN",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JOHN DOE",
    "destinationBankCode": "000007",
    "destinationBankName": "Fidelity Bank Plc",
    "description": "Payment for services",
    "externalReference": "INV-2026-001",
    "createdAt": "2026-01-18T10:30:00.000Z",
    "updatedAt": "2026-01-18T10:30:05.000Z"
  }
}

Get Transfer by External Reference

If you provided an externalReference when creating the transfer, you can use it to query the transfer status.

GET /v1/virtual-account/transfer-by-reference/:accountId/:externalReference

Path Parameters

Parameter	Type	Required	Description
`accountId`	integer	Yes	The virtual account ID the transfer was made from
`externalReference`	string	Yes	Your external reference provided when creating the transfer

Example Request

curl -X GET "https://api.esca.finance/v1/virtual-account/transfer-by-reference/12345/INV-2026-001" \
  -H "X-Api-Key: your_api_key_here"

Example Response

{
  "status": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "SUCCESS",
    "amount": 10000,
    "fee": 10.75,
    "currency": "NGN",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "JOHN DOE",
    "destinationBankCode": "000007",
    "destinationBankName": "Fidelity Bank Plc",
    "description": "Payment for services",
    "externalReference": "INV-2026-001",
    "createdAt": "2026-01-18T10:30:00.000Z",
    "updatedAt": "2026-01-18T10:30:05.000Z"
  }
}

Why Use External Reference?

Using your own external reference has several advantages:

No need to store UUIDs: You can query transfers using your existing identifiers (invoice numbers, order IDs, etc.)
Easier reconciliation: Match transfers directly to your business records
Simpler integration: Use the same identifiers across your system

External Reference Uniqueness

External references are unique per account:

Each virtual account has its own namespace for external references
Two different accounts can use the same external reference
The same account cannot reuse an external reference for a different transfer

Response Fields

Field	Type	Description
`uuid`	string	Unique transfer identifier
`status`	string	Transfer status (see below)
`amount`	number	Transfer amount
`fee`	number	Transfer fee charged
`currency`	string	Currency code (`NGN` or `GHS`)
`destinationAccountNumber`	string	Recipient account number
`destinationAccountName`	string	Recipient account name
`destinationBankCode`	string	Recipient bank code
`destinationBankName`	string	Recipient bank name
`description`	string	Transfer description
`externalReference`	string	Your external reference (if provided)
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update

Status Values

Status	Description
`PENDING`	Transfer is being processed
`SUCCESS`	Transfer completed successfully
`FAILED`	Transfer failed
`REVERSED`	Transfer was reversed

Error Responses

Transfer Not Found

{
  "status": false,
  "message": "Transfer not found"
}

This error is returned when:

The UUID does not exist
The external reference does not exist for the specified account

Initiate Transfer

Bulk Transfer