Transfers

Overview

The Transfers API allows you to send funds from your accounts to beneficiaries both domestically and internationally. It provides a flexible set of endpoints to create, track, and manage outgoing payments to individuals, businesses, and other financial institutions.

Key features of the Transfers API:

Create domestic and international transfers
Support for multiple payment methods (SWIFT, ACH, FedWire, NUBAN, SEPA, Faster Payments)
Check transfer status and track progress
Support for currency conversion within transfers
Add supporting documentation to transfers
Retrieve transfer history with detailed filtering options

The Transfer Object

Property	Type	Required	Description
id	string (UUID)	✅	Unique identifier of the transfer.
state	enum	✅	Current state of the transfer (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, PENDING_APPROVAL, AWAITING_FUNDS).
status_description	string	✅	Human-readable description of the transfer's current state.
created_date	string (datetime)	✅	Date and time when the transfer was created.
updated_date	string (datetime)	✅	Date and time when the transfer was last updated.
completion_date	string (datetime)	❌	Date and time when the transfer was completed (only for COMPLETED transfers).
internal_reference	string	✅	Internal reference for the transfer (system-generated).
client_reference	string	❌	Client-provided reference for the transfer.
client_metadata	object	❌	Client-provided metadata for the transfer.
account_id	string (UUID)	✅	ID of the source account for the transfer.
source_amount	object	✅	Original instructed amount for the transfer.
source_amount.value	number	✅	Amount in minor units (cents, pence, etc).
source_amount.currency	string	✅	Currency code (ISO 4217).
billing_amount	object	✅	Total amount debited from the source account.
billing_amount.value	number	✅	Amount in minor units (cents, pence, etc).
billing_amount.currency	string	✅	Currency code (ISO 4217).
total_fees	object	✅	Total fees charged for the transfer.
total_fees.value	number	✅	Fee amount in minor units (cents, pence, etc).
total_fees.currency	string	✅	Currency code (ISO 4217).
destination_amount	object	✅	Amount that the beneficiary will receive.
destination_amount.value	number	✅	Amount in minor units (cents, pence, etc).
destination_amount.currency	string	✅	Currency code (ISO 4217).
type	string	✅	internal or eternal
destination_account	object	❌	Destination Account details if type is internal
destination_account.id	string	✅	Destination account id
destination_account.name	string	✅	Destination account name
destination_account.classification	string	✅	institution_main_account, institution_sub_account or customer_sub_account
beneficiary	object	❌	Beneficiary details if type is external.
beneficiary.id	string (UUID)	✅	ID of the saved beneficiary.
beneficiary.name	string	✅	Name of the beneficiary.
beneficiary.country_code	string	❌	Country code of the beneficiary.
beneficiary.type	enum	❌	Type of the beneficiary (e.g., SWIFT, ACH, NUBAN).
beneficiary.kind	enum	❌	Kind of the beneficiary (INDIVIDUAL, BUSINESS).
beneficiary.bank_account	object	✅	Bank account details of the beneficiary (see Beneficiary Bank Account table).
payment_reference	string	❌	Reference displayed to the beneficiary on their bank statement.
memo	string	❌	Additional information about the transfer (not shared with the beneficiary).
reason	enum	✅	Purpose or reason for the transfer (e.g., bill_payment, salary_wages, business_expenses).
on_behalf_of	object	❌	If the transfer is made on behalf of a customer or sub-account.
on_behalf_of.customer_id	string (UUID)	❌	ID of the customer if POBO is specified
on_behalf_of.account_id	string (UUID)	❌	ID of the sub-account if POBO is specified.
quote_id	string (UUID)	❌	ID of the quote used for this transfer (if applicable).
fx	object	❌	Exchange rate details if currency conversion was involved.
fx.pair	string	✅	Currency pair (e.g., "USD/EUR").
fx.base_currency	string	✅	Base currency of the exchange rate.
fx.quote_currency	string	✅	Quote currency of the exchange rate.
fx.rate	number	✅	Exchange rate applied.
failure_reason	string	❌	Reason for failure if the transfer failed.
provider_references	array	✅	List of references from the payment provider.
provider_references[].type	enum	✅	Type of reference (e.g., SWIFT_UETR, END_TO_END_ID).
provider_references[].value	string	✅	Value of the reference.
balance_before	object	✅	Account balance before the transfer.
balance_before.value	number	✅	Balance before in minor units (cents, pence, etc).
balance_before.currency	string	✅	Currency code (ISO 4217).
balance_after	object	✅	Account balance after the transfer.
balance_after.value	number	✅	Balance after in minor units (cents, pence, etc).
balance_after.currency	string	✅	Currency code (ISO 4217).

Beneficiary Bank Account

The beneficiary.bank_account object provides details about the beneficiary's bank account. The structure varies depending on the payment method type:

Field	Type	Is Always Available	Description
bank_name	string	❌	Name of the beneficiary bank.
account_number	string	❌	Account number at the beneficiary bank.
routing_number	string	❌	Routing number for US banks.
swift_code	string	❌	SWIFT/BIC code of the beneficiary bank.
sort_code	string	❌	Sort code for UK banks.
iban	string	❌	IBAN for European accounts.
local_bank_code	string	❌	Bank code if a local scheme was used. example NUBAN will have the Nigerian bank's bank_code here

Transfer State Lifecycle

Transfers move through various states during their lifecycle. Understanding these states and their transitions is crucial for properly monitoring and managing transfers.

Transfer States

State	Description
PENDING	The transfer has been initiated but not yet processed. Initial validation checks have passed, but the transfer hasn't been submitted to the payment network.
PENDING_APPROVAL	The transfer is awaiting approval from an authorized user or system before it can be processed. This only occurs for transfers created from the dashboard where the Institution configured approvals.
AWAITING_FUNDS	The transfer is valid, but it must have sufficient funds in the source account before it can be processed. This only happens for transfers created via OTC
PROCESSING	The transfer is currently being processed and sent to the payment network. This is an intermediate state where the funds are in transit.
COMPLETED	The transfer has been successfully processed, and the funds sent to the beneficiary. This is a terminal successful state.
FAILED	The transfer could not be completed due to an error. This could be due to invalid beneficiary details, compliance issues, or other processing problems. This is a terminal failure state.
CANCELLED	The Institution or an administrator manually canceled the transfer before it was fully processed. This is a terminal state.

State Transition Flow


stateDiagram-v2
    [*] --> PENDING: Create Transfer
    [*] --> PENDING_APPROVAL: Create Transfer (requires approval)
    [*] --> AWAITING_FUNDS: Create Transfer (insufficient funds)
    
    PENDING --> PROCESSING: Automatic processing
    PENDING_APPROVAL --> PROCESSING: After approval
    AWAITING_FUNDS --> PROCESSING: Funds received
    
    PROCESSING --> COMPLETED: Success
    PROCESSING --> FAILED: Error
    
    COMPLETED --> [*]
    FAILED --> [*]
    
    PENDING --> CANCELLED: Manual cancellation
    PENDING_APPROVAL --> CANCELLED: Manual cancellation
    AWAITING_FUNDS --> CANCELLED: Manual cancellation
    
    CANCELLED --> [*]

Important Notes About Transfer States

Initial State: All transfers begin in the PENDING state after creation.
Terminal States: There are three terminal states:
- COMPLETED: The transfer was successful
- FAILED: The transfer failed due to an error
- CANCELLED: The transfer was deliberately cancelled
Intermediate States:
- PENDING_APPROVAL: May require manual action from an authorized user
- AWAITING_FUNDS: Will proceed automatically once funds are available
- PROCESSING: No further action required; awaiting network processing
Cancellation:
- Transfers can only be cancelled in the PENDING, PENDING_APPROVAL, or AWAITING_FUNDS states
- Once a transfer reaches the PROCESSING state, cancellation is generally not possible
Finality:
- Once a transfer reaches a terminal state (COMPLETED, FAILED, or CANCELLED), it cannot transition to any other state
- If a transfer fails, a new transfer must be created rather than retrying the failed one

Monitoring Transfer States

It's recommended to implement the following monitoring strategies:

Webhooks: Set up webhooks to receive real-time notifications of state changes
Reporting: Implement daily reconciliation processes to ensure all transfers have reached appropriate terminal states