Rails & Transfers

Heron allows you to move funds between different payment "rails"—the underlying infrastructure for global money movement. This guide explains how to select the right rail and how transfers are validated.

Payment Rails

A Rail defines the network and rules for a transaction. Heron supports two primary types of rails:

1. Fiat Rails

Used for traditional bank transfers. When using a Fiat rail, you must specify:

• Country: The destination ISO country code (e.g., US, GB, AU).
• Currency: The asset being moved (e.g., USD, GBP, AUD).
• Method: The specific transfer protocol (e.g., ACH, SEPA, DOMESTIC).

2. Crypto Rails

Used for digital asset transfers across blockchains. When using a Crypto rail, you must specify:

• Blockchain: The network (e.g., ETHEREUM, POLYGON, BITCOIN).
• Asset: The specific token or cryptocurrency (e.g., USDC, ETH, BTC).

---

The Transfer Lifecycle

Every transfer in Heron goes through a strictly tracked lifecycle to ensure compliance and reliability.

1. Pending: The transfer has been created but not yet validated against funds or compliance rules.
2. Ready for Execution: All requirements are met, and the transfer is awaiting the next processing window.
3. Executing: The funds are currently being moved across the selected rail.
4. Completed: The recipient has received the funds.
5. Failed: The transfer was rejected (e.g., insufficient funds or invalid instruction details).

---

Validation Rules

To prevent accidental failures, Heron enforces strict validation on transfer instructions:

• Exact Amounts: Amounts must be provided as positive decimal strings (e.g., "150.00"). We reject invalid characters or ambiguous formats.
• Decimal Alignment: Each rail has a specific decimal precision. For example, most Fiat rails use 2 decimals, while some Crypto assets use up to 18.
• Destination Boundary: POST /transfers uses a destination object. Use { "type": "FIAT_ACCOUNT", "fiatAccountId": "..." } for fiat quote destinations and { "type": "CRYPTO_WALLET", "cryptoWalletId": "..." } for crypto quote destinations.
• Crypto Wallets: Crypto wallet destinations are matched to the quote destination by blockchain. The wallet address, and memo when present, are passed to providers that support direct crypto destination details.
• Instruction Details:
  • US Rails: Require a valid 9-digit Routing Number and Account Number.
  • EU Rails: Require a valid IBAN and optionally a BIC/SWIFT code.
  • International USD/GBP Rails: Use a real destination country with SWIFT and require SWIFT/BIC details, the beneficiary account number, and beneficiary address. EUR bank accounts use the SEPA rail instead of SWIFT.
  • CA/AU/GB Rails: Require regional identifiers like Transit Numbers or Sort Codes.

IMPORTANT

Always verify that your instruction details match the requirements of the selected rail to avoid delays or reversals.