Rails and fees

A payment method is the bank network a payin or payout uses, named by a value such as sepa or ach. Read what one client can use with GET /dapi/v1/banks, and what one contact can receive with GET /dapi/v1/contacts/{contactId}/capabilities. Virtual accounts defines product, rail, virtual account and account details.

Products

Request a virtual account with POST /dapi/v1/banks and one of these products. The payer sends the listed currency over one of the listed methods.

`product`	Methods	Currency
`us`	`ach`, `fedwire`	USD
`swift`	`swift`	USD
`eu`	`sepa`	EUR
`uk`	`ukfps`	GBP
`uae`	`uaefts`	AED
`br`	`pix`	BRL
`mx`	`spei`	MXN
`co`	`breb`	COP
`au`	`npp`	AUD
`ng`	`nip`	NGN

GET /dapi/v1/banks returns the products one client can request, with currency and method for each. Use the response in code, not this table. The product enum in the API reference has more codes than this table. A code the client cannot request is absent from its GET /dapi/v1/banks response, and POST /dapi/v1/banks with it returns 403 rail_not_available.

What each method needs

The identifiers are the requisites.fields of an active virtual account and the fields you send to save a contact. + means each group is required. or means one of the alternatives in that group. A contact can use any method in the table. A virtual account can use the methods from ach to transfers_3_0.

Method	Currency	Market	Identifiers
`ach`, `fedwire`	USD	United States	`accountNumber` + `routingNumber`
`swift`	USD	International	`accountNumber` or `iban` + `bic`
`sepa`	EUR	Euro area	`iban`
`ukfps`	GBP	United Kingdom	`accountNumber` + `routingNumber`
`uaefts`	AED	United Arab Emirates	`iban`
`pix`	BRL	Brazil	`pixKey` or `accountNumber`
`spei`	MXN	Mexico	`accountNumber` or `iban`
`npp`	AUD	Australia	`accountNumber` + `routingNumber`
`nip`	NGN	Nigeria	`accountNumber`
`breb`	COP	Colombia	`paymentKey` or `accountNumber`
`pse`	COP	Colombia	`accountNumber` or `iban`
`transfers_3_0`	ARS	Argentina	`accountNumber` or `iban`
`bdt_ewallet`	BDT	Bangladesh	`financialInstitutionId` + `phoneNumber`
`bdt_local`	BDT	Bangladesh	`financialInstitutionId` + `branchNumber` + `accountNumber`
`bob_local`	BOB	Bolivia	`financialInstitutionId` + `accountNumber` + `accountKind`
`brl_local`	BRL	Brazil	`financialInstitutionId` + `branchNumber` + `accountNumber` + `accountKind`
`cad_eft`	CAD	Canada	`financialInstitutionId` + `accountNumber` + `routingNumber`
`clp_local`	CLP	Chile	`financialInstitutionId` + `accountNumber` + `accountKind`
`cny_alipay`, `cny_wechatpay`	CNY	China	`phoneNumber`
`cop_local`	COP	Colombia	`financialInstitutionId` + `accountNumber` + `accountKind`
`crc_local`	CRC	Costa Rica	`financialInstitutionId` + `iban` + `phoneNumber`
`dkk_local`	DKK	Denmark	`iban`
`dop_ewallet`	DOP	Dominican Republic	`financialInstitutionId` + `phoneNumber`
`dop_local`	DOP	Dominican Republic	`financialInstitutionId` + `accountNumber` + `accountKind`
`egp_local`	EGP	Egypt	`financialInstitutionId` + `iban`
`fednow`, `rtp`	USD	United States	`accountNumber` + `routingNumber`
`gtq_ewallet`	GTQ	Guatemala	`financialInstitutionId` + `phoneNumber`
`gtq_local`	GTQ	Guatemala	`financialInstitutionId` + `accountNumber` + `accountKind` + `phoneNumber`
`hkd_fps`	HKD	Hong Kong	`financialInstitutionId` + `accountNumber`
`hnl_local`	HNL	Honduras	`financialInstitutionId` + `accountNumber` + `accountKind` + `phoneNumber`
`idr_ewallet`	IDR	Indonesia	`financialInstitutionId` + `phoneNumber`
`idr_local`	IDR	Indonesia	`financialInstitutionId` + `accountNumber`
`ils_local`	ILS	Israel	`financialInstitutionId` + `iban`
`inr_local`	INR	India	`accountNumber` + `routingNumber`
`inr_upi`	INR	India	`accountNumber`
`jmd_local`	JMD	Jamaica	`financialInstitutionId` + `branchNumber` + `accountNumber` + `accountKind` + `phoneNumber`
`jpy_local`	JPY	Japan	`financialInstitutionId` + `branchNumber` + `accountNumber` + `phoneNumber`
`krw_local`	KRW	South Korea	`financialInstitutionId` + `accountNumber`
`myr_local`	MYR	Malaysia	`financialInstitutionId` + `accountNumber`
`nok_local`	NOK	Norway	`iban`
`php_ewallet`	PHP	Philippines	`financialInstitutionId` + `phoneNumber`
`php_local`	PHP	Philippines	`financialInstitutionId` + `accountNumber`
`pkr_ewallet`	PKR	Pakistan	`financialInstitutionId` + `phoneNumber`
`pkr_raast`	PKR	Pakistan	`financialInstitutionId` + `accountNumber` or `iban`
`pln_local`	PLN	Poland	`iban`
`sar_local`	SAR	Saudi Arabia	`financialInstitutionId` + `iban`
`sle_local`	SLE	Sierra Leone	`financialInstitutionId` + `phoneNumber`
`thb_local`	THB	Thailand	`financialInstitutionId` + `accountNumber`
`try_fast`	TRY	Türkiye	`financialInstitutionId` + `iban`
`tzs_local`	TZS	Tanzania	`financialInstitutionId` + `phoneNumber`
`ugx_local`	UGX	Uganda	`financialInstitutionId` + `phoneNumber`
`vnd_local`	VND	Vietnam	`financialInstitutionId` + `accountNumber`
`xof_local`	XOF	West African CFA franc zone	`financialInstitutionId` + `phoneNumber`
`zmw_local`	ZMW	Zambia	`financialInstitutionId` + `phoneNumber`

An _ewallet method pays a mobile wallet identified by a phone number. A _local method is the domestic clearing system of that market. For both, save a contact and then book a payout. Each requisites object and each contact has a holder. Its type is individual with firstName and lastName, or business with businessName. The holder does not replace the identifiers.

Availability

Narrowed by	Effect	Returned as
Your integrator agreement (Going live)	Which products HEVN enables for you	`403 rail_not_available` on `POST /dapi/v1/banks`
The client’s residency and legal form	Which of those products the client can request	The product is absent from `GET /dapi/v1/banks`
The account named in `accountId`	Which products can deliver to an external account or a sub account (Virtual accounts)	`409 account_destination_unsupported` on `POST /dapi/v1/banks`, `403 rail_not_available` on `GET /dapi/v1/banks/{product}`
The client’s verification state	Whether a requested virtual account can become `active`	`blockers[]` on the record: `kyb_required`, `verification_required`, `terms_required`
Rail status	Whether the rail accepts payments now	`503 provider_unavailable`, or `channel_unavailable` in a contact’s `blockers[]`

Chain codes

A chain code names the chain in crypto.chain of a wallet contact and in originChainId of a quoted on-chain payin. A transfer to baseSmartWallet and a quoted on-chain payin need no virtual account and no verification. The client must be ready. Read GET /dapi/v1/chains at startup and do not hardcode the codes below. Chain codes: eth, bsc, avax, op, arb, pol, sol, base, gnosis, tron, xrp, zec, doge, ltc, btc, cardano, bera, sui, near, near_intents, xlayer, plasma, ton, stellar, monad, starknet, aptos, adi, bch. A payout to a chain other than Base is routed.

Fees

A fee or rate in this API is either declared before a payment exists or quoted on one payment. Rates are set per integrator. Ask HEVN for yours.

Declared and quoted

	Declared	Quoted
Meaning	A rate for a product or a contact	The terms of one payment
Returned by	`GET /dapi/v1/banks`, `GET /dapi/v1/banks/{product}/rate`, `GET /dapi/v1/contacts/{contactId}/capabilities`, `POST /dapi/v1/payouts/preview`, `GET /dapi/v1/rates`	`quote` on `POST /dapi/v1/payins` and `POST /dapi/v1/payouts`
Use	Display before the customer commits	Charge and reconcile
Binding	No. It can change	Yes, until `expiresAt`

Do not bill from a stored declared rate.

Fee fields

Field	Returned by	Meaning
`feeBps`, `minimumDeposit`	`GET /dapi/v1/banks`	The payin fee is taken from the converted amount. A payment below `minimumDeposit` is returned to the payer.
`feeBps`, `fixedFee`, `minAmount`, `maxAmount`	`options[]` on `GET /dapi/v1/contacts/{contactId}/capabilities`	Indicative price and amount range for one contact. See Payouts.
`feeAmount`, `feeCurrency`, `rate`	`quote` on a payin or a payout	The binding terms. See Payins and Payouts.
`expiresAt`	`quote` on a payout, top level of a payin	When the quoted terms stop applying.

POST /dapi/v1/payouts/preview prices a rail without a contact. A price from capabilities or preview is indicative. POST /dapi/v1/payouts repeats the checks and returns the binding quote. To choose which side of a payment absorbs the fee, send amount or amountTo (Conventions).

Product rate

GET /dapi/v1/banks/{product}/rate returns the indicative price of a payin on one product.

{ "currency": "EUR", "rate": "…", "fixedFee": "…", "fixedFeeCurrency": "EUR" }

Market rate

GET /dapi/v1/rates?from=EUR&to=USDC returns the current market rate between two currencies or tokens.

{ "fromCurrency": "EUR", "toCurrency": "USDC", "rate": "1.14776038", "indicative": true }

A currency HEVN does not price returns 404 not_found.

Not a fee

Item	Why
Gas	Gas on Base is paid by an ERC-4337 paymaster. A quote has no network fee line, and the client’s wallet needs no ETH. A transfer an external account sends is paid for by the customer’s wallet.
A move with a sub account	One for one, with no fee (Swaps).
Escrow `feeBps`	Your take rate on `capture` and `charge`, deducted from the captured amount before the seller is paid. The ceiling is fixed when the deal is created. See Escrow.

Start here

Core concepts

Clients

Move money

Ship it

Reference

Changelog