Payins

Money arrives four ways: a quoted deposit you priced, a quoted on-chain transfer you priced, an unsolicited wire to account details that are already live, or crypto sent straight to the wallet. All four end as one income row on the client’s ledger.

Shape	What you call	What the payer needs
Quoted deposit	`POST /dapi/v1/payins` with `rail`, then `POST /dapi/v1/payins/{payinId}/instructions`	The instructions that quote returns, payment reference included
Quoted on-chain transfer	`POST /dapi/v1/payins` with `originChainId`, then the same instructions call	The `address`, `chainId` and `memo` the instructions return
Unsolicited wire	Nothing — the account details stay live	The `requisites` on the client’s active rail from `GET /dapi/v1/banks`
Crypto	Nothing	The client’s `baseSmartWallet` address

Quote a payin when you need the rate and the fee pinned before the payer pays, and when you want their transfer attributed to one order. Take an unquoted path when the client publishes its own details and reconciles afterwards. Send X-Hevn-Account: cl_… with your own access token to act for one client. On a resource route like GET /banks the header is optional: omit it and the call acts on your integrator account instead. The singular /client* routes require it — the header is the only thing that names the account — and /clients and /escrow* refuse it.

curl "$HEVN_API/banks" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID"

northwind = hevn.acting_as(CLIENT_ID)
rails = northwind.get("/banks")

const northwind = hevn.actingAs(clientId);
const rails = await northwind.get("/banks");

northwind := api.ActingAs(clientID)
rails, err := northwind.Get("/banks")

The whole table — where the header is optional, where it is required and where it is refused — is in Sessions.

Quote a deposit

The client needs an active rail in the currency the payer sends — see Virtual accounts.

Price the deposit

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 = northwind.post("/payins", {
    "amount": "2000.00",
    "currency": "EUR",
    "rail": "sepa",
    "destinationAccount": "EURC",
})

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

payin, err := northwind.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": { "amount": "2000.00", "currency": "EUR",
             "settlementAmount": "1989.50", "destinationAccount": "EURC",
             "feeAmount": "10.50", "feeCurrency": "EUR", "rate": "1.0000" },
  "expiresAt": "2026-09-17T10:06:11Z", "createdAt": "2026-09-17T10:04:11Z" }

Four decisions:

amount or amountTo, exactly one. amount is what the payer sends in currency; amountTo is what should land on the wallet, and HEVN grosses the payer’s side up to reach it.
rail or originChainId, exactly one. rail prices money arriving over a payment method; originChainId prices money arriving on a chain. Sending both, or neither, is refused.
rail here is a payment method — sepa, ach, swift, fedwire, pix, … — not the rail id you opened with POST /dapi/v1/banks. The two are different vocabularies; Rails lists both.
destinationAccount is the stablecoin the payin is delivered in, USDC (the default) or EURC. It has to be a token one of the client’s matching rails settles into; when it is not, the call refuses with the pairs that work (see below).

The price holds until expiresAt. Read it; do not cache a quote.

Open it and read the 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 = northwind.post(f"/payins/{payin['id']}/instructions", {})

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

instructions, err := northwind.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": "MT84…", "bic": "BANKMTMT" },
                  "holder": { "type": "business", "businessName": "Northwind Trading Ltd" },
                  "bankName": "Bank A", "state": "active" } }

Hand requisites to the payer verbatim, paymentReference included — on a pooled account it is the only thing that attributes the money to this payin.kind says where the payer acts: bank_transfer (use requisites), qr_code (qrPayload), hosted_page (url), manual, or onchain (address, chainId and memo). singleUse: true means these instructions belong to this payin alone.Opening the same payin again returns the same instructions — that is the safe retry, not a way to create a second payin. Once the price stops holding it answers 410 payin_expired; quote again.

Watch it settle

GET /dapi/v1/payins/{payinId} carries the payin through its whole life. Settlement is driven by the partner’s own reports, so poll it rather than waiting on a response.

import random, time


def poll_until(read, done, *, deadline=120.0, first=1.0, cap=8.0):
    """Call read() until done(value) is true. Returns the last value or raises TimeoutError."""
    started, delay = time.monotonic(), first
    while True:
        value = read()
        if done(value):
            return value
        if time.monotonic() - started > deadline:
            raise TimeoutError(f"still {value.get('status')} after {deadline:.0f}s")
        time.sleep(delay + random.uniform(0, delay / 2))
        delay = min(delay * 2, cap)

export async function pollUntil(read, done, { deadline = 120_000, first = 1_000, cap = 8_000 } = {}) {
  const until = Date.now() + deadline;
  let delay = first;
  for (;;) {
    const value = await read();
    if (done(value)) return value;
    if (Date.now() > until) throw new Error(`still ${value.status} after ${deadline}ms`);
    await new Promise((wake) => setTimeout(wake, delay + Math.random() * (delay / 2)));
    delay = Math.min(delay * 2, cap);
  }
}

func PollUntil[T any](read func() (T, error), done func(T) bool, deadline time.Duration) (T, error) {
	until, delay := time.Now().Add(deadline), time.Second
	for {
		value, err := read()
		if err != nil {
			return value, err
		}
		if done(value) {
			return value, nil
		}
		if time.Now().After(until) {
			return value, fmt.Errorf("hevn: still pending after %s", deadline)
		}
		time.Sleep(delay + time.Duration(rand.Int63n(int64(delay/2))))
		if delay < 8*time.Second {
			delay *= 2
		}
	}
}

`status`	Meaning
`pending`	Priced. Nothing has arrived.
`awaitingFunds`	Open, instructions issued, waiting for the payer.
`processing`	The partner has the money and is converting it.
`inReview`	Held pending an information request about the payment.
`completed`	Settled. The tokens are on the client’s wallet.
`failed`, `canceled`	It will not arrive. Quote again.
`refunded`	Returned to the payer.

Quote an on-chain transfer

originChainId in place of rail prices money arriving on a chain instead of through a bank. The body is otherwise the same call:

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

PayinView then carries originChainId — the network the payer funds from — and destinationChainId, the network the payin settles on. Open it with the same POST /dapi/v1/payins/{payinId}/instructions, and the instructions answer kind: "onchain" with the three fields a sender needs:

Response — 200

{ "payinId": "pi_5d3…", "kind": "onchain",
  "amount": "2000.00", "currency": "USDC", "singleUse": true,
  "address": "0x9b41…", "chainId": "arb", "memo": null }

memo is the destination tag some networks route on. When it is present it is as load-bearing as a paymentReference — a transfer that omits it cannot be attributed. ChainCode is the same vocabulary a wallet contact uses; base, arb, sol and the rest are listed on the rail reference. This is the quoted arm of crypto-in. The unquoted arm — send straight to the wallet, no call at all — is further down.

What a rail converts at

GET /dapi/v1/banks/{rail}/rate answers {currency, rate, fixedFee, fixedFeeCurrency} — the indicative price of a deposit over that rail. On a rail the client has not opened, only currency comes back. Use it to show a rate in your own UI before the payer commits to an amount. It is indicative: POST /dapi/v1/payins returns the number you are held to.

When the payer has to be named

Some rails require the payer’s own account so the receiving bank can check the sender. POST /dapi/v1/payins/{payinId}/instructions takes it:

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

payer.requisites.method has to equal payer.method. When a rail needs the payer and you omit it, the call answers 400 invalid_request and names the fields it wants in message — that refusal carries no details. details.options[].payerRequired on a refused quote is the part you can branch on, and it tells you in advance which pairs demand a payer.

When a pair cannot be paid

A currency and method the client cannot be paid in answers 422 payin_not_available, and details.options carries every pair that can — each with rail, currency, available, minAmount, maxAmount, feeBps, fixedFee, payerRequired and destinationAccounts. Read the options rather than pre-flighting: the refusal is the capability catalogue. 410 payin_expired and 404 payin_not_found are the other two you will meet; both carry details.payinId. Errors has the rest.

Unsolicited wires to the client’s account details

An active rail’s account details stay live between payments. Anyone can wire to them with no quote and no API call from you.

Read requisites for the active rail from GET /dapi/v1/banks.
Give the payer the fields it carries, plus paymentReference when one is set.
The deposit lands as an income row on GET /dapi/v1/transactions, carrying remitter where the partner reports the sender, paymentReference, and the receiving account details.

Some partners report no sender at all. When remitter is absent on a settled deposit, the sender cannot be recovered from the API — treat it as unknown rather than retrying.

Crypto straight to the wallet

The client’s smart wallet is an ordinary address on Base. Read it from GET /dapi/v1/client/balance — with the client id in X-Hevn-Account — as baseSmartWallet and publish it; anything sent there is the client’s. Nothing is quoted on this path, and there is no payin record: use the quoted on-chain arm above when you need a price or an attributed transfer.

Only USDC and EURC on Base are tracked. Other tokens, and the same tokens on other chains, sit at the address without ever becoming a balance or a transaction.

In the sandbox

The partner is emulated, so a quoted payin waits forever until you complete it yourself. One call does what the payer would have done:

curl -s -X POST "$HEVN_API/sandbox/payins/pi_2b7f14c0a9/complete" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"remitter":"Payer GmbH"}'

settled = northwind.post(f"/sandbox/payins/{payin['id']}/complete", {"remitter": "Payer GmbH"})

const settled = await northwind.post(`/sandbox/payins/${payin.id}/complete`,
  { remitter: "Payer GmbH" });

settled, err := northwind.Post("/sandbox/payins/"+payin.Str("id")+"/complete",
	hevn.Body{"remitter": "Payer GmbH"})

POST /dapi/v1/sandbox/deposits covers the other two unquoted shapes: with bankId it emulates an unsolicited wire to that rail, without one it credits the smart wallet with tokens. Both are in Sandbox.

The sandbox is the same API against one emulated partner on Base Sepolia. Its money comes from a shared faucet account: at most 100 tokens per credit, at least 0.10, and 60 money calls per account per hour. GET /dapi/v1/sandbox/treasury reports the live ceiling. Full table in Limits.

Next: Payouts

Money out: price and book a bank payout in one call, sign it in the next.

Start here

Core concepts

Onboard a client

Move money

Escrow

Ship it

Reference

Quote a deposit

Quote an on-chain transfer

What a rail converts at

When the payer has to be named

When a pair cannot be paid

Unsolicited wires to the client’s account details

Crypto straight to the wallet

In the sandbox

Next: Payouts

​Quote a deposit

​Quote an on-chain transfer

​What a rail converts at

​When the payer has to be named

​When a pair cannot be paid

​Unsolicited wires to the client’s account details

​Crypto straight to the wallet

​In the sandbox

Next: Payouts

Quote a deposit

Quote an on-chain transfer

What a rail converts at

When the payer has to be named

When a pair cannot be paid

Unsolicited wires to the client’s account details

Crypto straight to the wallet

In the sandbox