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.

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.

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.