API reference

Payments

A payment is money actually seen arriving: one on-chain transfer by a payer. Payments are created by the platform, never by the API.

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

seenIn the mempool or one block; never proof
confirmedThe network's confirmation count reached
settledThe value is in the merchant wallet, proved by the wallet's own chain read or revertedA block reorganisation removed it

On the relay rail the payer's transfer goes to Relay's address and settlement describes Relay's delivery into the merchant wallet. On the direct rail the payment is the settlement. An unmatched payment reached a merchant wallet and matches no order (unmatched_reason: no_instruction, ambiguous_amount when an exchange rounded a unique amount, app_report_mismatch, wrong_asset_on_order_address, after_late_window). You assign it to an order, ignore it (it stays in the wallet as plain balance), or refund it. In the dashboard only Owner, Admin and Finance may assign; a key needs payments:write.

The `payment` object

JSON

{
  "id": "pay_2pe50hae6w2jk4sp1rcq5pae",
  "object": "payment",
  "livemode": true,
  "created": "2026-10-11T14:06:41.117Z",
  "order": "ord_0zymngngvf12b8b2cra7tb8e",
  "instruction": "pin_h73hkjr8dyp4zymaet5e2gbv",
  "status": "settled",
  "rail": "relay",
  "asset": "ethereum:usdc",
  "network": "ethereum",
  "amount": "22.410000",
  "value": {
    "amount": "22.41",
    "currency": "USD"
  },
  "transaction_hash": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
  "from_address": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
  "to_address": "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
  "confirmations": 14,
  "confirmations_required": 12,
  "unmatched": false,
  "unmatched_reason": null,
  "late": false,
  "ignored": false,
  "finalized": true,
  "screening": {
    "id": "scr_268aypc7xxt8g1bkbweajv0m",
    "status": "clear",
    "checked_at": "2026-10-11T14:06:41.117Z"
  },
  "settlement": {
    "id": "stl_wrv1q8enp9g0fr2jqt1gwqrr",
    "asset": "base:usdc",
    "network": "base",
    "amount": "21.990000",
    "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
    "to_address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
    "transaction_hash": "0x27ca64c092a959c7edc525ed45e845b1de6a7590d173fd2fad9133c8a779a1e3",
    "proved_by": "wallet_chain_read",
    "settled_at": "2026-10-11T14:09:55.764Z"
  },
  "seen_at": "2026-10-11T14:06:41.117Z",
  "confirmed_at": "2026-10-11T14:09:12.300Z",
  "settled_at": "2026-10-11T14:09:55.764Z",
  "reverted_at": null
}

Table: The payment object
Field	Meaning
`status`	Seen (mempool or first block), confirmed (the network's confirmation count reached), settled (the value is in the merchant wallet, proved by the wallet's own chain read), or reverted. Values: `seen`, `confirmed`, `settled`, `reverted`.
`unmatched`	`true` when the transfer reached a merchant wallet and matched no order.
`screening`	The sanctions-list check of the sender address. Payers are screened, never identified.
`settlement`	`null` until settled. On the direct rail the payment is the settlement.
`finalized`	`false` while the payment is confirmed at the count but not yet final on its network (high-value orders only).
`rail`	One of `orrerie_app`, `relay`, `direct`.
`unmatched_reason`	One of `no_instruction`, `ambiguous_amount`, `app_report_mismatch`, `wrong_asset_on_order_address`, `after_late_window`.

Every field

Fields of the `payment` object

Fields of the payment object
Field	Type	Meaning
`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 or null	The `ord_` id the payment is credited to; `null` for an unmatched payment.
`instruction`	string or null	The `pin_` id the payment answered; `null` when it answered none.
`status`	string	Seen (mempool or first block), confirmed (the network's confirmation count reached), settled (the value is in the merchant wallet, proved by the wallet's own chain read), or reverted. One of `seen`, `confirmed`, `settled`, `reverted`.
`rail`	string	One of `orrerie_app`, `relay`, `direct`.
`rail_reason`	string or null	Why this rail, as on the instruction the payment answered. `null` for a payment that answered no instruction (an unmatched payment, also once assigned to an order). 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`, `null`.
`asset`	string	The asset that was sent.
`network`	string	The network it was sent on.
`amount`	string	What was sent, in the asset's own units.
`value`	object	What the payment was worth in US dollars when it was first seen.
`value.amount`	string	The value, a decimal string.
`value.currency`	string	Always `USD`.
`transaction_hash`	string	The hash of the payer's transaction.
`from_address`	string	The address the payment came from.
`to_address`	string or null	The address it was sent to; `null` in test mode.
`confirmations`	integer	How many confirmations the transaction has.
`confirmations_required`	integer	How many it needs before it counts.
`unmatched`	boolean	`true` when the transfer reached a merchant wallet and matched no order.
`unmatched_reason`	string or null	One of `no_instruction`, `ambiguous_amount`, `app_report_mismatch`, `wrong_asset_on_order_address`, `after_late_window`, `null`.
`late`	boolean	`true` when it arrived after its instruction expired.
`ignored`	boolean	`true` when the merchant chose to keep an unmatched payment as plain balance.
`finalized`	boolean	`false` while the payment is confirmed at the count but not yet final on its network (high-value orders only).
`screening`	object or null	The sanctions-list check of the sender address. Payers are screened, never identified.
`screening.id`	string	The `scr_` id of the screening.
`screening.status`	string	The screening's result.
`screening.checked_at`	string (date-time)	When the sender's address was checked.
`settlement`	object or null	`null` until settled. On the direct rail the payment is the settlement.
`settlement.id`	string or null	The `stl_` id of the delivery into the merchant wallet; `null` when none is recorded apart from the payment.
`settlement.asset`	string	The asset that reached the merchant wallet.
`settlement.network`	string	The network it reached the wallet on.
`settlement.amount`	string	What reached the wallet, in the asset's own units.
`settlement.wallet`	string	The `wal_` id of the wallet that took it.
`settlement.to_address`	string or null	The wallet address it reached; `null` in test mode.
`settlement.transaction_hash`	string	The hash of the delivering transaction.
`settlement.proved_by`	string	How the delivery was proved: `wallet_chain_read`, the merchant wallet's own read of the chain.
`settlement.settled_at`	string (date-time)	When the delivery was proved.
`seen_at`	string (date-time)	When the payment was first seen.
`confirmed_at`	string (date-time) or null	When it reached its confirmation count; `null` until then.
`settled_at`	string (date-time) or null	When its value was proved in the merchant wallet; `null` until then.
`reverted_at`	string or null	When a block reorganisation removed it; `null` unless it was.

Endpoints

Events

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