Request a rail for this client

Answers 201 with the rail record the first time, 200 with Idempotency-Replayed: true when the rail was already requested or is already active. A rail is a singleton per client, so the server key is the client and the rail.

POST /banks

Request a rail for this client

cURL

curl --request POST \
  --url https://api.example.com/banks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rail": "<string>"
}
'

201

{
  "rail": "<string>",
  "currency": "<string>",
  "method": "sepa",
  "opened": true,
  "feeBps": 123,
  "supportedAccounts": [
    "USDC"
  ],
  "status": "preparing",
  "destinationAccount": "USDC",
  "minimumDeposit": "500.00",
  "id": "bnk_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "requisites": {
    "fields": {
      "iban": "<string>",
      "bic": "<string>",
      "accountNumber": "<string>",
      "routingNumber": "<string>",
      "pixKey": "<string>",
      "pixKeyType": "phone",
      "paymentKey": "<string>",
      "financialInstitutionId": "<string>",
      "branchNumber": "<string>",
      "accountKind": "checking",
      "phoneNumber": "<string>"
    },
    "holder": {
      "type": "individual",
      "firstName": "<string>",
      "lastName": "<string>",
      "businessName": "<string>",
      "address": {
        "streetAddress": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "AF",
        "zip": "<string>"
      },
      "idType": "passport",
      "idNumber": "<string>",
      "taxId": "<string>",
      "nationality": "<string>"
    },
    "state": "active",
    "bankName": "<string>",
    "paymentReference": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

X-Hevn-Account · string | null

The client account to act for, as a cl_… id. Omit it to act as yourself.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

x-api-key · string | null

Body

application/json

rail · string · required

Stable rail identifier returned by the virtual-account list operation.

Response

201

application/json

Successful Response

rail · string · required

Stable HEVN identifier for this receiving payment method.

currency · string · required

ISO 4217 fiat currency code received through this payment method.

method · enum<string> · required

Payment network or method represented by this rail.

Available options: sepa, swift, ach, uaefts, fedwire, rtp, fednow, pix, spei, pse, breb, transfers_3_0, ukfps, npp, nip, bdt_local, bdt_ewallet, bob_local, brl_local, cad_eft, clp_local, cny_alipay, cny_wechatpay, cop_local, crc_local, dkk_local, dop_local, dop_ewallet, egp_local, gtq_local, gtq_ewallet, hkd_fps, hnl_local, idr_local, idr_ewallet, ils_local, inr_local, inr_upi, jmd_local, jpy_local, krw_local, myr_local, nok_local, php_local, php_ewallet, pkr_raast, pkr_ewallet, pln_local, sar_local, sle_local, thb_local, try_fast, tzs_local, ugx_local, vnd_local, xof_local, zmw_local

opened · boolean · required

Whether receiving details have been provisioned for this payment method.

feeBps · integer · required

Variable fee in basis points; 100 basis points equals 1 percent.

supportedAccounts · enum<string>[] · required

Settlement tokens accepted by this payment method.

Available options: USDC, EURC

status · enum<string> | null

Current virtual-account lifecycle status.

Available options: preparing, active, suspended, closed

destinationAccount · enum<string> | null

Digital asset used for settlement.

Available options: USDC, EURC

minimumDeposit · string | null

Minimum amount accepted through this method.

Example:

"500.00"

id · string | null

Opened virtual-account identifier.

Pattern: ^(?:bnk_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"bnk_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

requisites · RailRequisitesView · object | null

Receiving details, present after the virtual account becomes active.

Show child attributes