Start here

Take crypto payments with the Orrerie Merchant API

For developers adding crypto payments to a shop, an app or an invoice. One API, a hosted checkout, and the money lands in your own wallet. Orrerie never holds your money.

Quick startAPI reference

From nothing to a paid test order in ten minutes.

How a payment works

1. Your server creates a checkout sessionPOST /v1/checkout_sessions answers with a url.
2. The payer pays on the hosted pageSend the payer's browser to that address on pay.orrerie.com. The payer taps Pay with Orrerie, or picks an asset and pays the address shown.
3. The money arrives in your own walletEach of your wallets needs two of three keys. Orrerie holds one and cannot move the money alone.
4. Orrerie tells your serverThe webhook order.paid arrives, and you fulfil the order.

What to know before you write code

• One base address. https://api.orrerie.com/v1. The key goes in the Authorization header. JSON in, JSON out. No cookies.
• One payable object, the order. Checkout sessions, payment links, invoices, point-of-sale charges and subscription periods each create exactly one order.
• The money never passes through Orrerie. It lands in your own wallet. On the default rail it is with Relay, a separate company, for the seconds to minutes it is being routed; the API says so on every payment instruction in in_transit_notice.
• What a payment costs. Orrerie's own fee is 0% at launch. On the relay rail, Relay, a separate company, charges a routing fee that includes the network cost; by default it is added to the payer's amount and shown before they pay, and you receive the price in full. You can choose to absorb it instead (fee_bearer: merchant), in which case an order is paid when at least 98% of the price arrives. A route whose fee is above your cap (3% or US$25 unless you change it) is refused with rail_unavailable, whose reason is route_fee_over_cap, and the payer is asked to choose another asset. On the direct rail the payer pays only their own network fee. Sending money out costs the network's fee: see Money out.
• An order is paid only when your wallet's own chain read shows the money. Fulfil on the order.paid webhook or on GET /v1/orders/{id}, never on the payer's browser coming back.
• The API cannot move funds by itself. It can request a refund, a payout, a conversion or a new saved address. A person at your business approves each one in the dashboard with their passkey, and only then is anything signed. Money out has the whole sequence.
• No client library to install. There are no official client libraries at launch. Every example in these docs is plain HTTP, in curl, JavaScript, Python and PHP, and the OpenAPI file describes every call. The JavaScript examples use only fetch, which Node.js 18 and later has built in, and the Python examples only the requests package.
• Test mode uses sk_test_ keys and simulated payments. There are no test-network wallets. See test mode.