Transfer flow

Complete guide to executing transfers across traditional banking, mobile money, and cryptocurrency networks. This overview covers the universal steps required for all transfer types, with specific handling for crypto transactions that require blockchain signing.

Overview

All transfers follow the same foundational steps regardless of transfer type. The process branches only when cryptocurrency networks are involved, requiring additional transaction signing steps for blockchain security.

Universal Steps (All Transfers):

1. Discover available channels - Get supported rails and currencies
2. Create payment recipients - Set up destination account details for outbound transfers
3. Generate pricing quotes - Get real-time fees and exchange rates
4. Create transfers - Initialize the payment with quote and recipient
5. Complete transfer - Follow payment instructions or sign crypto transactions

Transfer Types:

• Fiat → Fiat: Traditional banking and mobile money transfers
• Crypto → Fiat: Cryptocurrency off-ramp to bank accounts
• Fiat → Crypto: Bank account funding to cryptocurrency wallets

Step-by-Step Flow

1. Get Available Channels

Discover which payment rails and currencies are available for your transfers.

GET /channels

Purpose: Understand supported combinations of rails (ACH, SEPA, Ethereum, etc.) and currencies (USD, EUR, USDC, etc.) with their current fees and processing speeds.

See: Payment Channels Documentation

2. Create Recipients (Outbound Transfers Only)

Set up payment destinations with the required account details for your chosen rails.

POST /recipients

Purpose: Create reusable payment destinations with properly formatted account details (bank accounts, crypto addresses, mobile money accounts). Only required for outbound transfers where you're sending money to external accounts.

See: Recipients Documentation

3. Generate Quote

Get real-time pricing for your specific transfer amount and rail combination.

POST /transfers/quote

Purpose: Calculate exact fees, exchange rates, and amounts. Quotes are valid for 2 minutes and required for transfer creation.

See: Quotes Documentation

4. Create Transfer

Initialize the transfer using your quote token and recipient details.

POST /transfers

Request:

{
  "quote": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sender": "wallet_1234567890abcdef",
  "recipient": "recipient_1234567890abcdef", 
  "memo": "Invoice #12345",
  "purposeCode": "OTHER"
}

Purpose: Create the transfer record with TransferStatusAwaitingFunds status. Transfer expires in 5 minutes.

The purposeCode field is optional and can be omitted, however, for channels including a non-empty purposeCodes object it is mandatory and has to be set to a correct value.

5. Transfer Completion (Branches by Type)

The final step depends on whether your transfer involves cryptocurrency networks:

For Fiat-to-Fiat Transfers

Follow deposit instructions provided in the transfer response to fund your transfer through banking or mobile money networks.

For Crypto Transfers

Create transfer intent to generate blockchain transaction data for signing:

POST /transfers/{transfer_id}/intent

Then sign and submit the blockchain transaction using your wallet infrastructure.

Transfer Flow Diagram

Transfer Types Explained

Fiat-to-Fiat Transfers

Examples: USD ACH → EUR SEPA, mobile money transfers, domestic bank transfers

Completion: Follow the deposit instructions provided in the transfer response. This typically involves:

• Bank wire transfers with the provided routing details
• Mobile money deposits to specified accounts
• ACH transfers using the provided account information

Crypto-to-Fiat Transfers

Examples: USDC → USD bank account, ETH → EUR SEPA transfer

Completion: Create a transfer intent to generate blockchain transaction data, then:

• Sign the transaction with your crypto wallet
• Submit the signed transaction to the blockchain network
• Monitor transaction confirmation

Fiat-to-Crypto Transfers

Examples: USD bank → USDC wallet, EUR → ETH address

Completion: Similar to crypto-to-fiat, requiring transfer intent creation and blockchain transaction signing for the destination crypto network.

Transfer status model

awaiting_funds

Indicates that a transfer has been initiated, and the system is waiting for funds to be received. At this stage, the transfer request has been created, but the funds have not yet arrived on our side.

funds_received

Indicates that the funds have been successfully received. Once the funds are received, the transfer moves to one of the following statuses:

• approved
• manual_review

approved

Indicates that the incoming transfer has successfully passed all policy checks. The transfer is now ready for payout processing. The next statuses will be:

• payment_submitted
• payment_processed

payment_submitted

Indicates that the payout request has been submitted to the payout partner and is currently being processed.

payment_processed

The final successful state of the transfer. This means that the funds were received from the client, and the payout has been completed on our side. If a transfer remains in the approved or payment_submitted status for an extended period, please contact our support.

manual_review

Indicates that the transfer did not pass automatic policy checks and requires manual review by our team. After the review is completed, the transfer will move to one of the following statuses:

• approved
• canceled
• action_required
• refund_submitted

action_required

Indicates that additional information or documents are required from the client to proceed with the transfer.

refund_submitted

Indicates that a refund process has been initiated and the funds will be returned to the sender.

refund_processed

Indicates that the refund has been completed and the funds have been returned to the sender.

failed

Indicates that the transaction has failed on the partner side. This status is set when our partner reports that the transaction could not be completed successfully. In such cases, the transfer will be handled according to internal procedures.

canceled

Indicates that the transfer has been manually canceled by our financial team. This typically happens when funds need to be returned to the sender through a manual process. After the refund is completed, the transfer status is updated to canceled.

The diagram below illustrates the transfer status flow described above.

Important Timing Considerations

Best Practices:

• Generate quotes immediately before transfer creation
• Complete crypto transaction signing promptly after intent creation
• Monitor transfer status for successful completion confirmation