API reference

Orders

The order is the single payable object: every invoice, every use of a payment link, every point-of-sale charge and every subscription period creates exactly one order. You can also create orders directly and build your own payment page with the instruction endpoints below (you then show the address and QR code yourself).

The states, in the order an object moves through them. Where a step lists several, the object takes one of them.

openNothing seen
processingA payment has been seen
paid or underpaid or overpaid or expired or cancelled

refunded and partially_refunded are boolean flags on a paid order. An order becomes paid only when the merchant wallet's own chain read shows the delivery with the amount; a provider's word never does it. Credit within 0.5% below the price, or within 0.5% (at least US$0.05) above it, counts as paid. Three transitions surprise integrators: an expired or cancelled order goes back to processing if money arrives for it within the 30-day late window (an address cannot be recalled, so money is never ignored); a paid order can become overpaid by a duplicate payment; and a paid order can fall back if a payment is undone by the chain (order.payment_reverted, order.unpaid).

The `order` object

JSON

{
  "id": "ord_0zymngngvf12b8b2cra7tb8e",
  "object": "order",
  "livemode": true,
  "created": "2026-10-11T14:03:22.418Z",
  "updated": "2026-10-11T14:09:55.764Z",
  "status": "paid",
  "source": "checkout",
  "amount": "21.99",
  "currency": "USD",
  "value": {
    "amount": "21.99",
    "currency": "USD"
  },
  "fx": null,
  "description": "Order #1042",
  "reference": "1042",
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "customer_email": "jane@example.com",
  "line_items": [
    {
      "name": "Ethiopia Yirgacheffe, 1 kg",
      "quantity": 1,
      "unit_amount": "21.99",
      "amount": "21.99",
      "price": "price_mbk5s5r45kwheaq89dbmk2gz"
    }
  ],
  "settlement": {
    "mode": "convert",
    "asset": "base:usdc",
    "amount_expected": "21.990000",
    "amount_received": "21.990000",
    "wallet": "wal_bsfw07hymawmda7gg8jsyy3g"
  },
  "fee_bearer": "payer",
  "amount_paid": "21.99",
  "amount_due": "0.00",
  "amount_refunded": "0.00",
  "paid_late": false,
  "accepted_short": false,
  "refunded": false,
  "partially_refunded": false,
  "finalized": true,
  "has_unconfirmed": false,
  "screening_hold": false,
  "screening": {
    "status": "clear"
  },
  "provider_refund_received": false,
  "overpayment": null,
  "rails_allowed": [
    "orrerie_app",
    "relay",
    "direct"
  ],
  "accept": [],
  "app_pay_allowed": true,
  "active_instruction": null,
  "instructions": [
    "pin_h73hkjr8dyp4zymaet5e2gbv"
  ],
  "payments": [
    "pay_2pe50hae6w2jk4sp1rcq5pae"
  ],
  "checkout_session": "cs_z7ek5wj68fyz80j7bz1eq4e0",
  "payment_link": null,
  "invoice": null,
  "subscription": null,
  "pos_device": null,
  "receipt": "rcpt_ppaxx20nbqv0kqgkwcxcc5xh",
  "expires_at": "2026-10-11T15:03:22.418Z",
  "paid_at": "2026-10-11T14:09:55.764Z",
  "cancelled_at": null,
  "metadata": {
    "cart_id": "c_7781"
  }
}

Table: The order object
Field	Meaning
`status`	The order state. paid and overpaid mean the full amount arrived with the confirmations its network needs, which is when you fulfil; a payment undone on its chain can still take the order back (`order.unpaid`), and `finalized` says when the network can no longer undo it; underpaid can still become paid by a top-up; refunds are flags, not states. Values: `open`, `processing`, `paid`, `underpaid`, `overpaid`, `expired`, `cancelled`.
`source`	What created the order. Values: `api`, `checkout`, `payment_link`, `invoice`, `pos`, `subscription`.
`amount`	The price, a decimal string in the pricing currency.
`currency`	The pricing currency: an upper-case ISO 4217 code (USD) or an asset id (bitcoin:btc).
`value`	The order's US-dollar value when it was created. Tier limits are measured on this figure.
`fx`	`null` for USD and crypto pricing. For another fiat currency: {rate, as_of}, the daily reference rate frozen on the order at creation.
`reference`	Your own order number. Up to 200 characters. Shown on the receipt.
`settlement`	What the merchant wallet is expected to receive and what it did receive, proved by the wallet's own chain read.
`fee_bearer`	Who pays the route fee on the relay rail. payer: the payer's amount includes it and the merchant receives the price to the unit. merchant: the payer pays the list price and the order is paid when at least 98% arrives. Values: `payer`, `merchant`.
`amount_paid`	Value credited to the order so far, in the pricing currency.
`amount_due`	What is still missing, in the pricing currency. 0.00 when paid.
`paid_late`	`true` when the payment that completed the order arrived after its instruction expired.
`accepted_short`	`true` when the merchant accepted a short payment as full.
`finalized`	`false` while a high-value order is paid at the confirmation count but its payments are not yet final on the network (Ethereum and the rollups above US$10,000); order.finalized follows. `true` otherwise.
`has_unconfirmed`	The engine's flag behind finalized: a credited payment is confirmed but below the higher bar.
`screening_hold`	A payer address was flagged by screening.
`provider_refund_received`	Relay returned a deposit for this order to the merchant's own wallet on the payer's network; the payer is usually owed a refund.
`accept`	Asset ids (and orrerie_app) this order accepts. Empty: everything the merchant has switched on.
`overpayment`	`null`, or {amount, asset, resolution} where resolution is `null`, refunded or kept_as_credit.
`rails_allowed`	Rails the payer may use for this order.
`app_pay_allowed`	Whether the checkout shows the Pay with Orrerie button. Set by a merchant-level rule only Orrerie can change.
`active_instruction`	The one live payment instruction, or `null`.
`expires_at`	When an unpaid order stops accepting new instructions.

The `payment_option` object

JSON

{
  "object": "payment_option",
  "asset": "ethereum:usdc",
  "network": "ethereum",
  "symbol": "USDC",
  "rail": "relay",
  "amount_mode": "exact",
  "available": true,
  "unavailable_reason": null,
  "estimated_pay_amount": "22.410000",
  "estimated_route_fee": {
    "amount": "0.42",
    "currency": "USD",
    "bearer": "payer"
  },
  "confirmations_required": 12,
  "estimated_seconds": 180
}

The `payment_instruction` object

JSON

{
  "id": "pin_h73hkjr8dyp4zymaet5e2gbv",
  "object": "payment_instruction",
  "livemode": true,
  "created": "2026-10-11T14:04:10.902Z",
  "order": "ord_0zymngngvf12b8b2cra7tb8e",
  "status": "waiting",
  "rail": "relay",
  "rail_reason": "default",
  "provider": "relay",
  "provider_request_id": "0x6b1f3c0e9a2d47f58c1b0e7d2a9f4c3b5e8d1a0f7c6b9e2d4a3f1c0b8e7d6a5f",
  "recipient_kind": "wallet",
  "recipient": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "refund_to": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  "refund_wallet_protected": true,
  "pay_asset": "ethereum:usdc",
  "pay_amount": "22.410000",
  "amount_mode": "exact",
  "address": {
    "id": "addr_x76q8chyjk6j34he4jrcbb7v",
    "address": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
    "network": "ethereum",
    "owner": "provider",
    "solana_pay_reference": null,
    "derivation": null
  },
  "payment_uri": "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48@1/transfer?address=0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359&uint256=22410000",
  "quote": {
    "id": "qt_0fymhdf3w7nem8m9f6rfjtgw",
    "price_amount": "21.99",
    "price_currency": "USD",
    "rate": "1.000200",
    "route_fee": {
      "amount": "0.42",
      "currency": "USD",
      "bearer": "payer"
    },
    "created": "2026-10-11T14:04:10.902Z",
    "expires_at": "2026-10-11T14:19:10.902Z"
  },
  "settle_asset": "base:usdc",
  "settle_amount_expected": "21.990000",
  "confirmations_required": 12,
  "in_transit_notice": "While a payment is being routed it is held by Relay, a separate company. Orrerie never holds it.",
  "wrong_asset_warning": "Send only USDC on Ethereum to this address. Anything else may be lost.",
  "expires_at": "2026-10-11T14:19:10.902Z",
  "late_until": "2026-11-10T14:19:10.902Z",
  "failure_code": null,
  "test_simulation_url": null
}

Table: The payment_instruction object
Field	Meaning
`status`	waiting: nothing seen. detected: the payer's transfer was seen. delivered: the value reached the merchant wallet. refunded_by_provider: the provider returned the deposit. failed. expired: the 15-minute window passed with nothing seen. Values: `waiting`, `detected`, `delivered`, `refunded_by_provider`, `failed`, `expired`.
`rail`	The way this order's money travels. Never changes after creation. Values: `orrerie_app`, `relay`, `direct`.
`rail_reason`	Why that rail (the states every object uses).
`recipient`, `refund_to`, `recipient_kind`, `provider_request_id`, `refund_wallet_protected`	Where the routing provider was told to deliver and to refund, signed by the merchant's own worker before the provider was called (the states every object uses). A merchant's server should compare `recipient` with its wallet address from `GET /v1/wallets`.
`amount_mode`	exact: the address accepts exactly pay_amount. open: any amount is re-priced on arrival. Values: `exact`, `open`.
`address`	The deposit address. owner is provider (a Relay address unique to this order) or merchant (the merchant wallet's own address or script). `null` on the orrerie_app rail and in test mode.
`payment_uri`	The string encoded in the QR code.
`late_until`	A payment arriving before this time is still credited to the order as a late payment.
`test_simulation_url`	Test mode only: the page that simulates a payment. Test mode never shows a real address.

Every field

Fields of the `order` object

Fields of the order object
Field	Type	Meaning
`screening`	object	The sanctions screening of the paying address or addresses.
`screening.status`	string	One of `pending`, `clear`, `review`, `blocked`, `unchecked`, `reviewed`.
`tip`	string	Point-of-sale tip inside amount, as a decimal string. 0.00 otherwise.
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`updated`	string (date-time)	When the object last changed.
`status`	string	The order state. paid and overpaid mean the full amount arrived with the confirmations its network needs, which is when you fulfil; a payment undone on its chain can still take the order back (`order.unpaid`), and `finalized` says when the network can no longer undo it; underpaid can still become paid by a top-up; refunds are flags, not states. One of `open`, `processing`, `paid`, `underpaid`, `overpaid`, `expired`, `cancelled`.
`source`	string	What created the order. One of `api`, `checkout`, `payment_link`, `invoice`, `pos`, `subscription`.
`amount`	string	The price, a decimal string in the pricing currency.
`currency`	string	The pricing currency: an upper-case ISO 4217 code (USD) or an asset id (bitcoin:btc).
`value`	object	The order's US-dollar value when it was created. Tier limits are measured on this figure.
`value.amount`	string	The order's value in US dollars when it was created, a decimal string.
`value.currency`	string	Always `USD`.
`fx`	object or null	`null` for USD and crypto pricing. For another fiat currency: {rate, as_of}, the daily reference rate frozen on the order at creation.
`description`	string or null	Shown to the payer above the amount; `null` for none.
`reference`	string or null	Your own order number. Up to 200 characters. Shown on the receipt.
`customer`	object	The `cus_` id of the order's customer, or the customer object when expanded; `null` for none.
`customer_email`	string or null	The email given for the order, kept encrypted; `null` when none was given. No receipt is emailed in this release.
`line_items`	array of objects	What the order is for, when it was priced from items; empty when it was priced from an amount.
`line_items[].name`	string	The item's name, as shown to the payer.
`line_items[].quantity`	integer	How many of the item.
`line_items[].unit_amount`	string	The price of one, a decimal string in the order's currency.
`line_items[].amount`	string	The line's total: quantity times the unit amount.
`line_items[].price`	string or null	The `price_` id the line was made from; `null` for a line given by name and amount.
`settlement`	object	What the merchant wallet is expected to receive and what it did receive, proved by the wallet's own chain read.
`settlement.mode`	string	`convert`: the payment is delivered in the settlement asset. `keep`: it stays in the asset it was paid in.
`settlement.asset`	string or null	The asset the merchant wallet receives; `null` while `mode` is `keep` and nothing was paid.
`settlement.amount_expected`	string or null	What the merchant wallet should receive, in the settlement asset; `null` while not yet known.
`settlement.amount_received`	string or null	What the merchant wallet received, proved by its own chain read; `null` until something arrives.
`settlement.wallet`	string or null	The `wal_` id of the merchant wallet that receives the money; `null` while not yet known.
`settlement.recipient_kind`	string	`wallet`: the merchant's wallet. `fee_account`: a fee-account top-up. One of `wallet`, `fee_account`.
`fee_bearer`	string	Who pays the route fee on the relay rail. `payer`: the payer's amount includes it and the merchant receives the price to the unit. `merchant`: the payer pays the list price and the order is paid when at least 98% arrives. One of `payer`, `merchant`.
`amount_paid`	string	Value credited to the order so far, in the pricing currency.
`amount_due`	string	What is still missing, in the pricing currency. 0.00 when paid.
`amount_refunded`	string	What was refunded so far, in the pricing currency.
`paid_late`	boolean	`true` when the payment that completed the order arrived after its instruction expired.
`accepted_short`	boolean	`true` when the merchant accepted a short payment as full.
`refunded`	boolean	`true` when everything paid has been refunded.
`partially_refunded`	boolean	`true` when some, not all, of what was paid has been refunded.
`finalized`	boolean	`false` while a high-value order is paid at the confirmation count but its payments are not yet final on the network (Ethereum and the rollups above US$10,000); order.finalized follows. `true` otherwise.
`has_unconfirmed`	boolean	The engine's flag behind finalized: a credited payment is confirmed but below the higher bar.
`screening_hold`	boolean	A payer address was flagged by screening.
`provider_refund_received`	boolean	Relay returned a deposit for this order to the merchant's own wallet on the payer's network; the payer is usually owed a refund.
`overpayment`	object or null	`null`, or {amount, asset, resolution} where resolution is `null`, refunded or kept_as_credit.
`rails_allowed`	array of strings	Rails the payer may use for this order.
`accept`	array of strings	Asset ids (and orrerie_app) this order accepts. Empty: everything the merchant has switched on.
`app_pay_allowed`	boolean	Whether the checkout shows the Pay with Orrerie button. Set by a merchant-level rule only Orrerie can change.
`active_instruction`	string or null	The one live payment instruction, or `null`.
`instructions`	array of objects	The order's payment instructions, oldest first: their ids, or the objects when expanded.
`payments`	array of objects	The payments credited to the order, oldest first: their ids, or the objects when expanded.
`checkout_session`	object	The checkout session the order was made with, or the object when expanded; `null` for none.
`payment_link`	object	The payment link that made the order, or the object when expanded; `null` for none.
`invoice`	object	The invoice the order pays, or the object when expanded; `null` for none.
`subscription`	object	The subscription whose period the order is, or the object when expanded; `null` for none.
`pos_device`	string or null	The `pos_` id of the till that took the order; `null` for any other order.
`receipt`	object	The order's receipt, or the object when expanded; `null` until the order is paid.
`expires_at`	string (date-time)	When an unpaid order stops accepting new instructions.
`paid_at`	string (date-time) or null	When the order became paid; `null` until then.
`cancelled_at`	string or null	When the order was cancelled; `null` unless it was.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Fields of the `payment_option` object

Fields of the payment_option object
Field	Type	Meaning
`object`	string	The type of this object.
`asset`	string	The asset id the payer may pay with.
`network`	string	The network the asset is on.
`symbol`	string	The asset's symbol, as payers know it.
`rail`	string	How this asset would be paid: `orrerie_app`, `relay` or `direct`.
`amount_mode`	string	`exact`: the address takes exactly the amount shown. `open`: any amount is priced on arrival.
`available`	boolean	`true` when the payer can pick this asset now.
`unavailable_reason`	string or null	Why the asset cannot be picked now; `null` while it is available.
`estimated_pay_amount`	string or null	About what the payer would send, in the asset; `null` when no figure can be given.
`estimated_route_fee`	object or null	About what routing would cost, in US dollars; `null` on the direct rail or when not known.
`estimated_route_fee.amount`	string	The fee, a decimal string.
`estimated_route_fee.currency`	string	Always `USD`.
`estimated_route_fee.bearer`	string	Who pays it: `payer` or `merchant`.
`confirmations_required`	integer	How many confirmations a payment in this asset needs before it counts.
`estimated_seconds`	integer or null	About how long the payment takes to arrive, in seconds; `null` when not known.

Fields of the `payment_instruction` object

Fields of the payment_instruction object
Field	Type	Meaning
`rail_reason`	string	Why this rail was used. One of `payer_chose_app`, `merchant_direct_only`, `relay_no_route`, `below_relay_minimum`, `same_asset_utxo`, `default`, `payer_chose_after_relay_refusal`, `provider_refund_counted`.
`recipient_kind`	string	`wallet`: the merchant's wallet. `fee_account`: a fee-account top-up. One of `wallet`, `fee_account`.
`recipient`	string or null	The address the routing provider was told to deliver to, signed by the merchant's own worker before the provider was called. `null` on the direct rail.
`refund_to`	string or null	The address the routing provider was told to refund to: the merchant's wallet on the payer's network.
`refund_wallet_protected`	boolean	`false` when refund_to is an un-activated Solana or TRON wallet.
`provider_request_id`	string or null	The routing provider's request id, so the request can be looked up there.
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`order`	string	The `ord_` id of the order the instruction pays.
`status`	string	`waiting`: nothing seen. `detected`: the payer's transfer was seen. `delivered`: the value reached the merchant wallet. `refunded_by_provider`: the provider returned the deposit. failed. `expired`: the 15-minute window passed with nothing seen. One of `waiting`, `detected`, `delivered`, `refunded_by_provider`, `failed`, `expired`.
`rail`	string	The way this order's money travels. Never changes after creation. One of `orrerie_app`, `relay`, `direct`.
`provider`	string or null	Who routes the payment: `relay` on the relay rail; `null` on the others.
`pay_asset`	string	The asset the payer sends.
`pay_amount`	string	Exactly what the payer sends, in the asset's own units.
`amount_mode`	string	`exact`: the address accepts exactly pay_amount. `open`: any amount is re-priced on arrival. One of `exact`, `open`.
`address`	object or null	The deposit address. owner is provider (a Relay address unique to this order) or merchant (the merchant wallet's own address or script). `null` on the orrerie_app rail and in test mode.
`address.id`	string	The `addr_` id of the deposit address.
`address.address`	string	The address the payer sends to.
`address.network`	string	The network of the address.
`address.owner`	string	`provider`: a Relay address unique to this order. `merchant`: the merchant wallet's own address or script.
`address.solana_pay_reference`	string or null	The Solana Pay reference key that ties a payment to this order; `null` on other networks.
`address.derivation`	object or null	A fresh per-order two-of-three script on Bitcoin, Litecoin or Dogecoin (direct rail): the child index of the three account keys and the script form, so your own server can derive the address again from the three xpubs of your recovery kit and check it. `null` on every other address.
`payment_uri`	string or null	The string encoded in the QR code.
`quote`	object	The price the instruction was made at.
`quote.id`	string	The `qt_` id of the quote.
`quote.price_amount`	string	The order's amount the quote covers, in the pricing currency.
`quote.price_currency`	string	The order's pricing currency.
`quote.rate`	string	The asset's price in the pricing currency the quote used.
`quote.route_fee`	object	The routing fee inside the quote, in US dollars, and who pays it.
`quote.created`	string (date-time)	When the quote was made.
`quote.expires_at`	string (date-time)	When the quote stops being honoured.
`settle_asset`	string	The asset the merchant wallet receives.
`settle_amount_expected`	string	What the merchant wallet should receive, in the settlement asset.
`confirmations_required`	integer	How many confirmations the payment needs before it counts.
`in_transit_notice`	string or null	The sentence the payer is shown while a routed payment is on its way; `null` on the direct rail.
`wrong_asset_warning`	string or null	The warning shown beside the address; `null` when there is none.
`expires_at`	string (date-time)	When the address stops being shown for new payments.
`late_until`	string (date-time)	A payment arriving before this time is still credited to the order as a late payment.
`failure_code`	string or null	Why the instruction failed; `null` unless `status` is `failed`.
`test_simulation_url`	string or null	Test mode only: the page that simulates a payment. Test mode never shows a real address.

Endpoints

Events

Webhook events whose data.object is an object of this page.

Orders

The order object

The payment_option object

The payment_instruction object

Every field

Fields of the order object

Fields of the payment_option object

Fields of the payment_instruction object

Endpoints

Events

The `order` object

The `payment_option` object

The `payment_instruction` object

Fields of the `order` object

Fields of the `payment_option` object

Fields of the `payment_instruction` object