Payment Rails

A rail describes how value enters, moves through, or exits Heron. Use the rail directory to discover the routes available in the current environment rather than maintaining a static coverage table in your integration.

Discover supported rails

Call GET /v1/rails before presenting route choices or constructing a quote request. The response contains the current fiat and crypto rails and their provider availability.

Provider activation is environment-specific. Recheck the directory when moving from sandbox to production and refresh cached results periodically.

Fiat rails

A fiat rail is identified by:

• Country: an ISO country code, such as US, GB, or AU
• Currency: the fiat asset, such as USD, GBP, or AUD
• Method: the payment method, such as ACH, SEPA, SWIFT, WIRE, PIX, SPEI, or LOCAL

Do not substitute a catch-all domestic label for the method returned by the rail directory. Country, currency, and method together define the route used for quoting and destination validation.

Crypto rails

A crypto rail is identified by:

• Blockchain: the network, such as ETHEREUM, POLYGON, or BITCOIN
• Asset: the token or cryptocurrency, such as USDC, ETH, or BTC

An asset name is not enough to select a crypto rail. Include the blockchain in quote requests and when creating a saved wallet.

Saved destinations

Transfers execute against saved fiat accounts or crypto wallets:

• use GET /v1/fiat-accounts/schemas to discover the detail fields for a fiat rail
• use GET /v1/crypto-wallets/schemas to discover supported wallet blockchains
• create the destination before requesting a transfer-ready quote

Destination schemas are the source of truth for account identifiers, beneficiary fields, wallet addresses, and memo or tag requirements. Validate against the selected schema instead of using one generic account form for every rail.

For US USD bank rails, routing numbers are normalized and must contain exactly nine digits with a valid ABA checksum. Account numbers must be numeric (leading zeroes are preserved), subdivisions must use a supported two-letter US code, and postal codes must be a five-digit ZIP or ZIP+4. These US rules do not apply to addresses for other countries; retain each selected country's postal format.

US and SEPA account details also accept an optional bankAddress, separate from the beneficiary address. Its fields are street_line_1, optional street_line_2, city, state, and postal_code; the account country identifies the bank country. State requirements depend on that country. Providers may require this address even when the shared account schema permits omitting it.

Mexican SPEI accounts require an 18-digit CLABE with a valid check digit. Spaces and hyphens are normalized; leading zeroes are preserved. Correct invalid saved values before registering them.

First-party fiat accounts can specify ownerEntityId on create or update. Select the entity that owns the bank account; it must belong to the same organization. Third-party accounts cannot use this field. Existing accounts remain unassigned until explicitly updated. Set ownerEntityId to null to clear an assignment. Changes apply to future transfers; existing transfers retain their confirmed destination.

Saved destinations are versioned. Editing bank instructions, a wallet address, blockchain, memo, or tag creates a new destination version. Existing transfers continue to use the snapshot confirmed when they were created.

Funding instructions

When a transfer is waiting for funds, Heron returns instructions for the selected inbound rail. A fiat instruction can contain rail-specific account details, exactAmount, beneficiary information, and a payment reference. A crypto instruction contains the blockchain, asset, deposit address, and any required memo or tag. An EVM-compatible crypto instruction may also contain a walletTransactionPlan, while provider-contract flows can return EVM_TRANSACTION_PLAN instructions directly. These plans contain ordered, unsigned calls for the payer's wallet; Heron never returns or accepts a wallet private key. For ordinary CRYPTO_DEPOSIT instructions, the deposit address remains available as the manual-payment option.

Show a connect-wallet action only when instructions include walletTransactionPlan or EVM_TRANSACTION_PLAN. A blockchain name alone does not establish wallet-payment support; otherwise use the supplied manual deposit instructions.

Always use the funding instructions on the transfer or its active funding session. Do not reuse instructions from another transfer, even when the rail is the same.

Continue with Quotes to compare execution options and Transfers to create and track a payment.