Transfer Initiation

These APIs perform the following actions:

Check Transfer Eligibility – Verify if a transfer can be processed.
Estimate transfer costs – Determine the total fees, exchange rates etc to perform a transfer.
Create an Outbound Transfer – Send money to a beneficiary.

Check Transfer Eligibility

This endpoint checks whether a transfer is eligible based on the source account and counterparty details. It validates whether a payment transfer can be processed between a specified source account and a saved beneficiary/counterparty.

This pre-validation endpoint helps prevent failed transfers by identifying potential issues before initiating a payment. It can also return additional requirements that must be included in payments to this beneficiary, e.g., purpose codes for certain jurisdictions.

❗️
Notes

This endpoint does not initiate any actual funds transfer

All validations are performed without affecting account balances

The eligibility check reflects the current system status and may change

Request Parameters

Parameter	Type	Required	Description
`source_account_id`	uuid	✅ Yes	The ID of the source account for the transfer.
`counterparty_id`	string	✅ Yes	The ID of the counterparty/beneficiary.
`amount`	integer	❌ No	Estimated transfer amount in smallest currency unit (e.g., cents, kobo)
`currency`	string	❌ No	Currency code for the transfer (defaults to source account currency)

Example Request

{
    "source_account_id": "0191db23-369e-73c6-aa53-9f5f9a1c534e",
    "counterparty_id": "01922d50-b3d0-7e3e-af73-1a8d460cd2fa"
}

Example Response

{
  "data": {
    "supported": true,
    "reason": null
  }
}

{
  "data": {
    "supported": false,
    "reason": "Unsupported currency"
  }
}

Estimate Transfer Costs

Estimations can be generated using the Quote API

Create Transfer

This endpoint allows users to initiate a new outbound transfer to a specified beneficiary. If a supporting document is provided in the request, it should use form-data; otherwise, it should use regular JSON.

Types of Transfer

There are two ways to transfer funds: Simple transfers move money directly by specifying the amount and recipient in one step, while Transfers from Quoteare transfers based on a previously generated quote

Transfer Request Schema

The transfer API supports two instruction types within a single schema structure:

Common Fields

Field	Type	Description
`reason`	`string`	Purpose or reason for the transfer
`payment_reference`	`string`	Reference number for the payment
`memo`	`string`	Optional memo or note for the transfer
`client_reference`	`string`	Client-provided reference for tracking
`additional_info`	`array`	List of additional key-value pairs for the transfer
`client_metadata`	`object`	Client-provided metadata for the transfer
`on_behalf_of_customer_id`	`string`	Optional Unique Identifier of the customer on whose behalf the transfer is being made
`instruction`	`string`	The execution details of the transfer, see section below

Instruction Object:

Field	Type	Description
`type`	String	Required. Determines the transfer method. Must be either `"simple"` or `"quote"`.
`amount`	Number	Required for Simple Transfer only. Amount to transfer in minor units (cents/pence).
`source_account_id`	UUID	Required for Simple Transfer only. ID of the account sending the funds.
`beneficiary_id`	UUID	Required for Simple Transfer only. ID of the beneficiary receiving the funds.
`destination_currency`	String	Optional for Simple Transfer only. Currency code for FX transfers via SWIFT.
`quote_id`	UUID	Required for Transfer from Quote only. ID of a previously created quote that defines amount, source, destination, and rate information.

Transfer Request Example

{
    "reason": "business_expenses",
    "client_metadata": {
        "hello": "world"
    },
    "payment_reference": "293389483-009",
    "instruction": {
        "type": "simple",
        "source_account_id": "01961ef1-b21d-718f-8f06-9da328e8361e",
        "amount": 1000,
        "beneficiary_id": "019638b9-c63d-76c6-91f6-a7ccec3707ed"
    }
}

{
    "reason": "business_expenses",
    "client_metadata": {
        "hello": "world"
    },
    "payment_reference": "293389483-009",
    "instruction": {
        "type": "quote",
        "quote_id": "01961ef1-b21d-718f-8f06-9da328e8361e"
    }
}

curl -X POST https://your-api-endpoint.com/transfers \
  -H "Authorization: Bearer your_token_here" \
  --form "reason=business_expenses" \
  --form "client_metadata[hello]=world" \
  --form "payment_reference=293389483-009" \
  --form "instruction[type]=simple" \
  --form "instruction[source_account_id]=01961ef1-b21d-718f-8f06-9da328e8361e" \
  --form "instruction[amount]=1000" \
  --form "instruction[beneficiary_id]=019638b9-c63d-76c6-91f6-a7ccec3707ed"

Transfer Response

A sample transfer response is provided below

Field	Type	Description
`id`	`string`	Unique identifier for the transfer transaction
`state`	`string`	Current state of the transfer ("PENDING")
`status_description`	`string`	Human-readable description of the transfer status
`created_date`	`string`	Timestamp when the transfer was initially created
`updated_date`	`string`	Timestamp when the transfer was last updated
`internal_reference`	`string`	System-generated internal reference for the transfer
`client_metadata`	`object`	Additional metadata provided by the client
`account_id`	`string`	Identifier of the account sending the transfer
`source_amount`	`object`	Amount to be debited from the source account see amount section
`total_fees`	`object`	Fees to be charged for the transfer see amount section
`destination_amount`	`object`	Amount to be credited to the destination account see amount section
`completion_date`	`string`	The actual time the transfer was completed. Only available when the state is "COMPLETED"
`reason`	`string`	Purpose or reason for the transfer
`payment_reference`	`string`	Reference number for the payment
`sender_reference`	`string`	Reference provided by the sender
`beneficiary`	`object`	Information about the recipient of the transfer see beneficiary section
`provider_references`	`array`	List of external references related to the transfer
`balance_before`	`object`	Account balance before the transfer was initiatedsee amount section
`balance_after`	`object`	Expected account balance after the transfer is processedsee amount section

Amount

Field	Type	Description
`value`	`string`	Amount in minor units (e.g., cents for USD)
`currency`	`string`	Currency code in ISO 4217 format

Beneficiary

Field	Type	Description
`id`	`string`	Unique identifier of the beneficiary
`type`	`string`	`Type of banking method used (e.g., "SWIFT")`
`name`	`string`	Name of the beneficiary
`country_code`	`string`	`ISO country code of the beneficiary`
`kind`	`string`	Type of beneficiary (e.g., "BUSINESS", "INDIVIDUAL")
`bank_account`	`object`	Banking details of the beneficiary see bank account section

Bank Account

Field	Type	Description
`bank_name`	`string`	Name of the beneficiary's bank
`swift_code`	`string`	SWIFT/BIC code of the beneficiary's bank
`account_number`	`string`	Account number or IBAN of the beneficiary

Note: For transfers in PENDING state, the balance_after reflects the projected balance after successful processing.

Sample Transfer Response Payload

{
    "data": {
        "id": "019648f3-44ae-7e26-8cdd-92fab31c52de",
        "state": "PENDING",
        "status_description": "Transfer waiting to be processed",
        "created_date": "2025-04-18T12:50:24.559Z",
        "updated_date": "2025-04-18T12:50:27.389Z",
        "internal_reference": "wz-payout-HTEb-1744980624557",
        "client_metadata": {},
        "account_id": "01958a45-02ba-7d3e-beeb-3a65d97230ab",
        "source_amount": {
            "value": 20000,
            "currency": "USD"
        },
        "total_fees": {
            "value": 100,
            "currency": "USD"
        },
        "destination_amount": {
            "value": 20000,
            "currency": "USD"
        },
        "reason": "Business Payments – Payments for goods, services, supplier invoices, or business expenses.",
        "payment_reference": "293389483-009",
        "beneficiary": {
            "id": "019638b9-c63d-76c6-91f6-a7ccec3707ed",
            "type": "SWIFT",
            "name": "Emmanuel Igbodudu",
            "country_code": "US",
            "kind": "BUSINESS",
            "bank_account": {
                "bank_name": "Revolut ltd",
                "swift_code": "REVOGB21",
                "account_number": "GB34REVO00997019274916"
            }
        },
        "sender_reference": "293389483-009",
        "provider_references": [],
        "balance_before": {
            "value": 320000,
            "currency": "USD"
        },
        "balance_after": {
            "value": 300000,
            "currency": "USD"
        }
    }
}