API reference

Refunds

A refund is money the merchant sends back to a payer for an order. It is a transaction out of the merchant's own wallet, so the API can only request it. An Owner or Finance member opens approval_url, reviews the address and amount, and approves with their passkey, which unlocks the browser key that signs; Orrerie's co-signer then rebuilds the transaction, checks policy and adds the second signature. Money out has the full sequence.

A refund is distinct from a provider refund (Relay returning a deposit it could not route, to the merchant's own wallet on the payer's network): that is money coming in, shown on the instruction as refunded_by_provider and on the order as provider_refund_received, and it usually means the payer is owed a refund through this endpoint.

Where it is sent. The address comes from the payer through a channel tied to the order, never "back to the sending address": a payer paying from an exchange does not own that address.

Default: the refund claim link. The refund is created awaiting_address and the payer is given a single-use link on pay.orrerie.com where they choose network and asset and give an address (Orrerie sends payers no email yet: the dashboard shows the link, and you give it to the payer); it is screened and shown back to them before they confirm. Then the refund moves to awaiting_approval and refund.created is sent. If the payer does nothing for 14 days it lapses to draft (pending_reason: "address_lapsed"). The link carries a secret and is never returned by the API; an order with no email (a till sale) gets its link as a QR code in the dashboard.
A payer who paid with the Orrerie app: the refund defaults to that payer's own Orrerie wallet and skips the claim.
An address you supply (destination): accepted only with address_confirmed_with_customer: true, logged, and then the saved-address rule applies: the refund cannot be approved until approvable_at, 24 hours after it was requested. Use an existing active saved address (destination.saved_address) to avoid the wait.

Amounts. amount is in the order's pricing currency and is converted at the order's own locked rate (rate_basis: "order_rate"), so the merchant returns what it received for that part of the order; rate_basis: "today" uses the current price instead. Refunds on an order may total what the order was credited plus any provider refund received for it. A refund in an asset or network other than the one the merchant holds travels through Relay, whose fee is deducted from the refund by default (fee_bearer: "recipient", shown to the payer on the claim page) or added on top ("merchant"). Minimum: US$1.00 through Relay, the dust limit direct.

The `refund` object

JSON

{
  "id": "rf_z20ve49yz5hve8f0xsdchj2v",
  "object": "refund",
  "livemode": true,
  "created": "2026-10-12T10:00:00.000Z",
  "updated": "2026-10-12T10:00:00.000Z",
  "status": "awaiting_approval",
  "pending_reason": null,
  "order": "ord_0zymngngvf12b8b2cra7tb8e",
  "payment": "pay_2pe50hae6w2jk4sp1rcq5pae",
  "amount": "5.00",
  "currency": "USD",
  "reason": "requested_by_customer",
  "note": "One bag arrived damaged",
  "rate_basis": "order_rate",
  "deduct_network_fee": false,
  "source": {
    "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
    "asset": "base:usdc",
    "amount": "5.000000"
  },
  "destination": {
    "address": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
    "asset": "ethereum:usdc",
    "network": "ethereum",
    "supplied_by": "payer_claim",
    "saved_address": null
  },
  "address_claim": {
    "sent_to": "jane@example.com",
    "sent_at": "2026-10-12T09:40:00.000Z",
    "claimed_at": "2026-10-12T10:00:00.000Z",
    "expires_at": "2026-10-26T09:40:00.000Z"
  },
  "approvable_at": null,
  "delivery": {
    "rail": "relay",
    "amount_estimated": "4.930000",
    "route_fee": {
      "amount": "0.07",
      "currency": "USD"
    },
    "fee_bearer": "recipient"
  },
  "network_fee": null,
  "requested_by": {
    "type": "api_key",
    "id": "key_6e3gg2c6ea176xxdek2nar6v"
  },
  "approved_by": null,
  "approval_url": "https://merchant.orrerie.com/approve/rf_z20ve49yz5hve8f0xsdchj2v",
  "approval_expires_at": "2026-10-19T10:00:00.000Z",
  "transaction_hash": null,
  "failure_code": null,
  "cancellation_reason": null,
  "approved_at": null,
  "sent_at": null,
  "confirmed_at": null,
  "metadata": {}
}

Table: The refund object
Field	Meaning
`status`	awaiting_address (waiting for the payer to give an address), draft, awaiting_approval, signed, sent, confirmed, failed, unknown, or cancelled. Values: `awaiting_address`, `draft`, `awaiting_approval`, `signed`, `sent`, `confirmed`, `failed`, `unknown`, `cancelled`.
`pending_reason`	For a draft: approval_lapsed (nobody approved within 7 days) or address_lapsed (the payer gave no address within 14 days). Otherwise `null`.
`rate_basis`	order_rate: the amount is converted at the order's own locked rate, so the merchant returns what it received. today: converted at the current price.
`address_claim`	The refund claim link for the payer, which you give them from the dashboard in this release. The link itself (it carries a secret) is never returned by the API.
`approvable_at`	Set only when the merchant typed the address instead of the payer claiming it: the saved-address wait applies and the refund cannot be approved before this time. `null` otherwise.
`approval_url`	Dashboard page where an Owner or Finance member approves with a passkey. The API can never approve.
`reason`	One of `requested_by_customer`, `duplicate`, `overpayment`, `order_cancelled`, `other`.

Every field

Fields of the `refund` object

Fields of the refund 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.
`updated`	string (date-time)	When the object last changed.
`status`	string	awaiting_address (waiting for the payer to give an address), draft, awaiting_approval, signed, sent, confirmed, failed, unknown, or cancelled. One of `awaiting_address`, `draft`, `awaiting_approval`, `signed`, `sent`, `confirmed`, `failed`, `unknown`, `cancelled`.
`pending_reason`	string or null	For a draft: approval_lapsed (nobody approved within 7 days) or address_lapsed (the payer gave no address within 14 days). Otherwise `null`.
`order`	object	The `ord_` id of the refunded order, or the order object when expanded; `null` for an unmatched payment's refund.
`payment`	object	The `pay_` id of the payment refunded, or the object when expanded; `null` when the refund is of the order.
`amount`	string	The refund, in the order's pricing currency (in the asset itself for an unmatched payment).
`currency`	string	The currency of `amount`.
`reason`	string	One of `requested_by_customer`, `duplicate`, `overpayment`, `order_cancelled`, `other`.
`note`	string or null	The merchant's note about the refund; `null` for none.
`rate_basis`	string	order_rate: the amount is converted at the order's own locked rate, so the merchant returns what it received. today: converted at the current price.
`deduct_network_fee`	boolean	`true` when the network fee is taken from the refund instead of paid on top.
`source`	object	The merchant wallet the refund leaves from.
`source.wallet`	string	The `wal_` id of that wallet.
`source.asset`	string	The asset that leaves it.
`source.amount`	string	What leaves it, in the asset's own units; `null` while not yet known.
`destination`	object or null	Where the refund goes; `null` while it waits for the payer's address.
`destination.address`	string	The address the refund is sent to; `null` in test mode.
`destination.asset`	string	The asset the destination receives.
`destination.network`	string	The network of the destination.
`destination.supplied_by`	string	Who gave the address, for example `payer_claim` (the payer, through the claim link) or `saved_address`.
`destination.saved_address`	string or null	The `dst_` id when the destination is a saved address; `null` otherwise.
`destination_kind`	string or null	claim_link (the payer gave the address through the refund claim link), payer_orrerie_wallet (no wait) or saved_address (24-hour wait; approvable_at is set). `null` while the refund waits for the payer's address (awaiting_address). One of `claim_link`, `payer_orrerie_wallet`, `saved_address`, `null`.
`address_claim`	object or null	The refund claim link for the payer, which you give them from the dashboard in this release. The link itself (it carries a secret) is never returned by the API.
`address_claim.sent_to`	string or null	The email the claim link went to; `null` when it was handed over in person, as every claim link is while Orrerie emails no payer.
`address_claim.sent_at`	string (date-time)	When the claim link was given to the payer.
`address_claim.claimed_at`	string (date-time) or null	When the payer gave an address; `null` until then.
`address_claim.expires_at`	string (date-time)	When the claim link stops working.
`approvable_at`	string or null	Set only when the merchant typed the address instead of the payer claiming it: the saved-address wait applies and the refund cannot be approved before this time. `null` otherwise.
`delivery`	object or null	How the money reaches the destination; `null` until a destination is known.
`delivery.rail`	string	`direct`: one send to the address. `relay`: through Relay, into another asset or network.
`delivery.amount_estimated`	string	About what the destination receives, in the destination asset.
`delivery.route_fee`	object or null	Relay's fee for the delivery, in US dollars; `null` on the direct rail.
`delivery.fee_bearer`	string or null	Who pays the routing fee: `recipient` (taken from the amount) or `merchant`; `null` on the direct rail.
`network_fee`	object or null	The network fee of the send and who pays it; `null` until it is known.
`requested_by`	object	Who asked for it: an API key or a dashboard member.
`requested_by.type`	string	`api_key` or `member`.
`requested_by.id`	string	The id of the key (`key_…`) or the member (`mem_…`) that asked.
`approved_by`	string or null	The member who approved it with a passkey; `null` until approved.
`approval_url`	string or null	Dashboard page where an Owner or Finance member approves with a passkey. The API can never approve.
`approval_expires_at`	string (date-time) or null	When an unapproved request lapses to `draft`; `null` while it is not waiting for approval.
`transaction_hash`	string or null	The hash of the transaction that sent it; `null` until it is sent.
`failure_code`	string or null	Why it failed (Money out lists the codes); `null` unless `status` is `failed` or `unknown`.
`cancellation_reason`	string or null	Why it was cancelled (for example `cancelled_by_api` or `rejected_by_approver`); `null` unless cancelled.
`approved_at`	string or null	When it was approved; `null` until then.
`sent_at`	string or null	When the transaction was broadcast; `null` until then.
`confirmed_at`	string or null	When the network's confirmation count was reached; `null` until then.
`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.

Endpoints

Events

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