Create an incoming transfer quote

Price money arriving for this account. Set originChainId for an on-chain transfer or rail for a local payment method; exactly one is required. An unsupported route answers payin_not_available.

POST /payins

Create an incoming transfer quote

cURL

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

201

{
  "id": "pi_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "status": "pending",
  "quote": {
    "amount": "500.00",
    "currency": "<string>",
    "settlementAmount": "500.00",
    "destinationAccount": "<string>",
    "feeAmount": "500.00",
    "feeCurrency": "<string>",
    "rate": "500.00"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "rail": "sepa",
  "paymentReference": "<string>",
  "originChainId": "<string>",
  "destinationChainId": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

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

currency · string · required

ISO 4217 fiat code or supported digital-asset symbol for amount.

amount · string | null

Exact amount funded in the source currency.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

amountTo · string | null

Exact amount to settle to the account.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

rail · enum<string> | null

Local payment method; provide exactly one of rail or originChainId.

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

originChainId · enum<string> | null

Network from which an on-chain incoming transfer is funded.

Available options: 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

destinationAccount · enum<string> · default: USDC

Digital asset delivered to the account after settlement.

Available options: USDC, EURC

Response

201

application/json

Successful Response

id · string · required

Stable public identifier for this incoming transfer.

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

Example:

"pi_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

status · enum<string> · required

Current public lifecycle status of the incoming transfer.

Available options: pending, awaitingFunds, processing, inReview, completed, failed, refunded, canceled

quote · PayinQuoteView · object · required

Price, fee and conversion terms fixed for this incoming transfer.

Show child attributes

createdAt · string<date-time> · required

UTC timestamp when the incoming transfer was created.

rail · enum<string> | null

Local payment method, when account-funded.

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

paymentReference · string | null

Reference that must accompany the account transfer.

originChainId · string | null

Network from which an on-chain transfer is funded.

destinationChainId · string | null

Network on which the transfer settles.

expiresAt · string<date-time> | null

UTC timestamp after which the quote is no longer valid.