Open the incoming transfer and retrieve funding instructions

Idempotent: an already-open transfer returns the same payment-account details or on-chain deposit address. A quote that stopped holding answers 410 payin_expired.

POST /payins/{payinId}/instructions

Open the incoming transfer and retrieve funding instructions

cURL

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

200

{
  "payinId": "pi_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "kind": "bank_transfer",
  "amount": "500.00",
  "currency": "<string>",
  "singleUse": true,
  "paymentReference": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "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>"
  },
  "qrPayload": "<string>",
  "url": "<string>",
  "address": "<string>",
  "memo": "<string>",
  "chainId": "<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"

Path Parameters

payinId · string · required

Prefixed pay-in id

Body

application/json

payer · PlatformPayinPayerAccount · object | null

Originator information required by payment methods that validate the sending account.

Show child attributes

Response

200

application/json

Successful Response

payinId · string · required

Incoming-transfer identifier these instructions fund.

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

Example:

"pi_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

kind · enum<string> string · required

Kind of funding instruction returned.

Available options: bank_transfer, qr_code, hosted_page, manual

amount · string · required

Exact amount to send.

Example:

"500.00"

currency · string · required

Currency or digital asset to send.

singleUse · boolean · required

Whether these instructions may fund only this incoming transfer once.

paymentReference · string | null

Reference that must accompany the account transfer.

expiresAt · string<date-time> | null

UTC timestamp after which these instructions expire.

requisites · RailRequisitesView · object | null

Receiving payment-account details.

Show child attributes

qrPayload · string | null

Raw payload suitable for rendering as a payment QR code.

url · string | null

Hosted URL where the incoming transfer can be funded.

address · string | null

On-chain destination address.

memo · string | null

Memo or destination tag required by the on-chain transfer.

chainId · string | null

Network on which the destination address exists.