Payins

A payin is an arrival of money on a Base smart wallet, a sub account or an external account, recorded as an income row on the ledger. To fix the rate and fee before the payer pays, quote it with POST /dapi/v1/payins.

Shape	Call	Payer needs
Quoted bank payin	`POST /dapi/v1/payins` with `rail`	The instructions, with `paymentReference`
Quoted on-chain transfer	`POST /dapi/v1/payins` with `originChainId`	`address`, `chainId` and `memo`
Unsolicited wire	None	`requisites` of an active virtual account
Direct crypto	None	`baseSmartWallet`

Send X-Hevn-Account to act for a client (Acting as a client).

Quote a bank payin

The client needs an active virtual account in the payer’s currency.

Create the quote

Call POST /dapi/v1/payins.

curl -s -X POST "$HEVN_API/payins" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"amount":"2000.00","currency":"EUR","rail":"sepa","destinationAccount":"EURC"}'

payin = client.post("/payins", {
    "amount": "2000.00",
    "currency": "EUR",
    "rail": "sepa",
    "destinationAccount": "EURC",
})

const payin = await client.post("/payins", {
  amount: "2000.00",
  currency: "EUR",
  rail: "sepa",
  destinationAccount: "EURC",
});

payin, err := client.Post("/payins", hevn.Body{
	"amount":          "2000.00",
	"currency":        "EUR",
	"rail":            "sepa",
	"destinationAccount": "EURC",
})

Response: 201, Location: /dapi/v1/payins/pi_2b7…

{ "id": "pi_2b7…", "status": "pending", "rail": "sepa",
  "quote": { "settlementAmount": "1989.50", "feeAmount": "10.50",
             "feeCurrency": "EUR", "rate": "1.0000", … },
  "expiresAt": "2026-09-17T10:06:11Z", … }

Field rules are in Create an incoming transfer quote. Payment methods are listed in Rails.

Request the instructions

Call POST /dapi/v1/payins/{payinId}/instructions.

curl -s -X POST "$HEVN_API/payins/pi_2b7…/instructions" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" -d '{}'

instructions = client.post(f"/payins/{payin['id']}/instructions", {})

const instructions = await client.post(`/payins/${payin.id}/instructions`, {});

instructions, err := client.Post("/payins/"+payin.Str("id")+"/instructions", hevn.Body{})

Response: 200

{ "payinId": "pi_2b7…", "kind": "bank_transfer",
  "amount": "2000.00", "currency": "EUR",
  "paymentReference": "HEVN-7QF3K2", "singleUse": true,
  "requisites": { "fields": { "iban": "DE89…", "bic": "BANKDEFFXXX" }, … } }

Do not reuse the instructions for a second payment. Fields are in Open the incoming transfer.

Statuses

Poll GET /dapi/v1/payins/{payinId} until the status is final (Status codes).

`status`	Meaning	Next
`pending`	Quoted. No money has arrived. A `rail` quote holds for 2 minutes at most.	Request the instructions before `expiresAt`. After it, the call returns `410 payin_expired`.
`awaitingFunds`	Instructions issued. The partner bank sets `expiresAt`.	Wait for the payer. Money that arrives after `expiresAt` can be returned to the payer.
`processing`	The partner bank has the money and is converting it.	Keep polling.
`inReview`	Held for an information request about the payment.	Keep polling.
`completed`	The tokens are on the destination.	n/a
`failed`, `canceled`	The money will not arrive.	Quote again.
`refunded`	Returned to the payer.	n/a

An unpaid payin expires without a charge and has no ledger row. No route lists payins, so store payinId when you quote. Once money arrives, a pending income row appears on the ledger. It shows rfi while the partner bank asks about the payment and ends as success or refunded.

Payer mistakes

Mistake	Result
Bank transfer, different amount, right currency and reference	The amount sent is usually credited. The partner bank may return it instead.
Bank transfer, wrong currency or missing reference	The money may not be attributable. Recovery goes through HEVN support and is slow.
On-chain, different amount	Returned to the sender.
On-chain, wrong chain or token	The money does not arrive. Recovery is handled case by case with HEVN and is slow.

For a payer who types the details by hand, use unsolicited wires.

Quote an on-chain transfer

Send originChainId in place of rail.

{ "amount": "2000.00", "currency": "USDC", "originChainId": "arb", "destinationAccount": "USDC" }

The instructions call returns:

Response: 200

{ "kind": "onchain", "address": "0x9b41…", "chainId": "arb", "memo": null, … }

Give the payer memo when it is set. Chain values are in Chain codes.

Deliver to an account

destinationAccount also takes the acc_… id of an external account or a sub account. The payin is then an on-chain transfer, so send originChainId.

{ "amount": "2000.00", "currency": "USDC", "originChainId": "arb",
  "destinationAccount": "acc_5Jd8Qw2LmX", "refundAddress": "0x51a7…" }

Rule	External account	Sub account
`rail`	`409 account_destination_unsupported`	`409 account_destination_unsupported`
`refundAddress`	Required. The address on the origin chain that receives the funds back when the transfer cannot be completed. Without it the call returns `422 refund_address_required`.	Ignored. A sub account is refunded as the main wallet is.
Delivered	USDC on the account’s network, to its address	The token the account holds, on Base, to its address
Response	`accountId` names the account	`accountId` names the account

refundAddress with an account key as destinationAccount returns 422 validation_failed. See External wallets and Sub accounts.

Payer details

Some rails require the payer’s account. Send it as payer on the instructions call.

{ "payer": { "method": "sepa",
             "requisites": { "method": "sepa", "currency": "EUR",
                             "fields": { "iban": "DE89370400440532013000", "bic": "BANKDEFFXXX" },
                             "holder": { "type": "business", "businessName": "Payer GmbH" } } } }

details.options[].payerRequired on a refused quote shows which pairs need a payer.

Refusals

Error	Next
`422 payin_not_available`	Quote again with a pair from `details.options[]`. Each option has `rail`, `currency`, `available`, `minAmount`, `maxAmount`, `feeBps`, `fixedFee`, `payerRequired` and `destinationAccounts`.
`400 invalid_request`	Send `payer` with the identifiers in `details.fields`.
`410 payin_expired`	Quote again.

Other codes are in Errors. Indicative rates are in Fees.

Unsolicited wires to the client’s account details

A payer can send to an active virtual account at any time. Give the payer its account details from GET /dapi/v1/banks, with paymentReference when one is set. The income row from GET /dapi/v1/transactions has paymentReference, the receiving account details and remitter.

remitter is set when the partner bank reports the sender. When it is absent on a settled row, the API cannot return the sender.

Direct crypto

Read baseSmartWallet from GET /dapi/v1/client/balance and give the address to the payer. A sub account takes a transfer of its token at its address in the same way (Sub accounts).

HEVN tracks USDC and EURC on Base. Other tokens, and these tokens on other chains, do not become a balance or a transaction.

Sandbox

A quoted payin does not settle until you call the route in Settle a payin. For the unquoted shapes, see Mint money.

Start here

Core concepts

Clients

Move money

Ship it

Reference

Changelog

Quote a bank payin

Statuses

Payer mistakes

Quote an on-chain transfer

Deliver to an account

Payer details

Refusals

Unsolicited wires to the client’s account details

Direct crypto

Sandbox

Next: Payouts