openreceive 0.3.2 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +10 -0
- data/lib/openreceive/version.rb +1 -1
- data/skills/debug-openreceive-payment/SKILL.md +88 -0
- data/skills/integrate-openreceive/SKILL.md +116 -0
- data/skills/integrate-openreceive/references/node.md +480 -0
- data/skills/integrate-openreceive/references/rails.md +568 -0
- metadata +5 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 5d743bd46857a5465b940140cf3f0ff72b06e73a5d2d240121f35b7c5bf8c49f
|
|
4
|
+
data.tar.gz: e4ab82d2bf79d9d4bfb3700e33215190ac74785a4969be0fd842ff4bb00a4682
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: dfbcca4381857c00523946ecd5d7a24d8b19b92ec4a55aaf9378e398614aba0b5e7f4ea69ff523fe462090911c06551b4f74edaaf59430c57607745fde7ac967
|
|
7
|
+
data.tar.gz: bf13b03b08e18a7eff87d54827df26b6c674d79630a872024211a816b8c6eddb80b2092f87e60e3ca4b5ef2cc4b25cbec70f3c6fc988c8ece8d9863cdf12d4fa
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.3 - 2026-09-02
|
|
4
|
+
|
|
5
|
+
### The gem carries the agent skills
|
|
6
|
+
|
|
7
|
+
`skills/integrate-openreceive` and `skills/debug-openreceive-payment` (the
|
|
8
|
+
open SKILL.md format) now ship inside the gem, so a coding agent working in an
|
|
9
|
+
app that installed OpenReceive finds the integration and debugging playbooks
|
|
10
|
+
with no network. The copies are kept byte-identical to the repository's
|
|
11
|
+
canonical `skills/` tree by `npm run generate:skills`.
|
|
12
|
+
|
|
3
13
|
## 0.3.2 - 2026-08-29
|
|
4
14
|
|
|
5
15
|
No changes to this gem in 0.3.2. The release is the overpaid-deposit refund
|
data/lib/openreceive/version.rb
CHANGED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: debug-openreceive-payment
|
|
3
|
+
description: >
|
|
4
|
+
Diagnose a failing OpenReceive integration. Use when an OpenReceive-powered
|
|
5
|
+
checkout misbehaves: the server refuses to boot, checkout routes return 403,
|
|
6
|
+
404, 409, or 5xx, a paid invoice never settles, a swap refund seems
|
|
7
|
+
unreachable, or the checkout UI renders nothing.
|
|
8
|
+
license: MIT
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Debug an OpenReceive payment
|
|
12
|
+
|
|
13
|
+
Work top-down: configuration, then the request, then settlement. Every guide
|
|
14
|
+
URL below is raw markdown — fetch it when the step needs it.
|
|
15
|
+
|
|
16
|
+
## 1. Run the doctor first
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npx openreceive doctor # Node version, NWC_URI, swap config, wallet probe
|
|
20
|
+
npx openreceive doctor --db <db> # + are openreceive_payments/openreceive_meta migrated?
|
|
21
|
+
npx openreceive doctor --url http://localhost:3000 # + are the routes actually mounted?
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Each failing line states its own fix. `npx openreceive debug-report` prints the
|
|
25
|
+
same diagnostics redacted, always exit 0 — safe to share.
|
|
26
|
+
|
|
27
|
+
## 2. Boot failures
|
|
28
|
+
|
|
29
|
+
| Symptom | Cause and fix |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `MISSING_NWC` / "needs a receive-only NWC code" | `NWC_URI` is not in the server process env. A `.env` file alone is not enough — something must load it (`dotenv/config`, Next auto-load). Get a code: https://openreceive.org/get_a_nwc_code_to_receive_payments |
|
|
32
|
+
| `INVALID_NWC` / "not a valid NWC code" | The value is malformed (must be `nostr+walletconnect://` with 64-hex pubkey and secret, ≥1 `wss` relay). Re-copy it from the wallet. |
|
|
33
|
+
| "NOT receive-only" / spend methods advertised | The wallet minted a spend-capable code; OpenReceive fails closed because a leak would drain the wallet. Mint a receive-only code. Overriding (`allowSpendCapableWallet` / `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC`) is a last resort. |
|
|
34
|
+
| Wallet preflight failed (methods/encryption) | The wallet must advertise `make_invoice` + `list_transactions` and NIP-04 or NIP-44 v2. Use a compatible wallet. |
|
|
35
|
+
| "The openreceive_meta table does not exist" / raw `no such table: openreceive_payments` | The migration was never applied. Node: `npx openreceive scaffold payments --orm <yours>`, then run the emitted migration through the app's normal workflow. Rails: `bin/rails generate openreceive:install`, then `bin/rails db:migrate`. https://openreceive.org/guides/storage.md |
|
|
36
|
+
| "requires amountFor / onPaid / authorize / host" | The factory is missing a required hook — see the host contract in https://openreceive.org/guides/api-reference.md |
|
|
37
|
+
|
|
38
|
+
## 3. Request-time errors from the routes
|
|
39
|
+
|
|
40
|
+
| Status | Meaning | Where to look |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| 403 FORBIDDEN | Your own `authorize` hook denied it, or the request looked cross-site. Check the session/cookie actually reaches the checkout routes. https://openreceive.org/guides/authorization.md |
|
|
43
|
+
| 404 NOT_FOUND | `amountFor` returned `null` (unknown reference), or the `payment_hash` does not belong to that reference. |
|
|
44
|
+
| 409 CONFLICT | **Normal state, not a bug**: the reference already settled, or an unpaid checkout for that method is already live. Show it as order state; never retry-loop. |
|
|
45
|
+
| 503 retryable | The host hook failed while persisting the attempt (instructions withheld), or the wallet is unavailable. Read the server log for the underlying error. |
|
|
46
|
+
| Framework 404 / HTML error page | The router is not mounted, or mounted at a different prefix than the UI's `prefix` prop. `doctor --url` distinguishes these. |
|
|
47
|
+
|
|
48
|
+
## 4. Paid but never settles
|
|
49
|
+
|
|
50
|
+
- Settlement is opportunistic: any OpenReceive request runs one reconcile pass
|
|
51
|
+
through a durable gate (min 2s between wallet scans, stretched by invoice
|
|
52
|
+
age). A quiet server settles on the next request — or run the optional
|
|
53
|
+
notification worker. No timer is missing; that is the design.
|
|
54
|
+
- An unpaid attempt closes only after a successful wallet scan at/after expiry
|
|
55
|
+
plus a 900s grace constant — a local clock alone never closes one. `expired`
|
|
56
|
+
arriving "late" is correct.
|
|
57
|
+
- `onPaid` runs once per reference, first settled attempt only, inside the
|
|
58
|
+
settlement transaction. If your fulfillment did not run, check whether the
|
|
59
|
+
guarded `UPDATE … WHERE` matched zero rows (already transitioned).
|
|
60
|
+
https://openreceive.org/guides/storage.md
|
|
61
|
+
|
|
62
|
+
## 5. Swaps and refunds
|
|
63
|
+
|
|
64
|
+
- A deposit that arrives short or late becomes `refund_required`; the payer
|
|
65
|
+
claims it on a second visit. That needs a per-order URL you serve
|
|
66
|
+
(`/checkout/:reference`, `syncUrl` on the drop-ins). Keep the
|
|
67
|
+
`payment_hash`: `POST /swaps/status` reopens the attempt with no expiry
|
|
68
|
+
window, while re-picking the coin mints a new deposit after ~30 minutes.
|
|
69
|
+
- Refunds exist only for swap deposits from `refund_required`. There is **no
|
|
70
|
+
Lightning refund** — the wallet cannot spend. Do not chase one.
|
|
71
|
+
https://openreceive.org/guides/swap-refunds.md
|
|
72
|
+
|
|
73
|
+
## 6. Checkout UI shows nothing
|
|
74
|
+
|
|
75
|
+
- The components require `prefix` — the exact base path the routes are mounted
|
|
76
|
+
at (`"/openreceive"` unless you changed it).
|
|
77
|
+
- Import the stylesheet (`@openreceive/react/styles.css` or the elements
|
|
78
|
+
sheet).
|
|
79
|
+
- "invoice must not be an NWC connection string" means a server secret leaked
|
|
80
|
+
into a browser payload — stop and fix the server response; never render it.
|
|
81
|
+
https://openreceive.org/guides/frontend-checkout.md
|
|
82
|
+
|
|
83
|
+
## Still stuck
|
|
84
|
+
|
|
85
|
+
The full route/option/error reference:
|
|
86
|
+
https://openreceive.org/guides/api-reference.md · machine-readable contract:
|
|
87
|
+
https://openreceive.org/openapi.yaml · library bug reports:
|
|
88
|
+
https://openreceive.org/contact
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: integrate-openreceive
|
|
3
|
+
description: >
|
|
4
|
+
Integrate OpenReceive inbound Bitcoin Lightning payments into an application.
|
|
5
|
+
Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
|
|
6
|
+
Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
|
|
7
|
+
application with OpenReceive (the @openreceive/* npm packages or the
|
|
8
|
+
openreceive-rails gem).
|
|
9
|
+
license: MIT
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Integrate OpenReceive
|
|
13
|
+
|
|
14
|
+
OpenReceive is a payment library that runs inside the application you are
|
|
15
|
+
editing. It mounts HTTP routes there, issues Lightning invoices against a
|
|
16
|
+
wallet the merchant already controls, and calls back into your code when one
|
|
17
|
+
settles. There is no OpenReceive account and no API key; funds land directly in
|
|
18
|
+
the merchant's wallet. The one required credential is a **receive-only NWC
|
|
19
|
+
code** (`NWC_URI`).
|
|
20
|
+
|
|
21
|
+
## Pick the stack, then follow its directions
|
|
22
|
+
|
|
23
|
+
1. Identify the server stack of the application you are in.
|
|
24
|
+
2. Open the matching reference — it is complete (quickstart inlined) and needs
|
|
25
|
+
no network access:
|
|
26
|
+
- Node (Express / Fastify / Next.js): [references/node.md](references/node.md)
|
|
27
|
+
- Rails: [references/rails.md](references/rails.md)
|
|
28
|
+
3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
|
|
29
|
+
environment before writing code. Never print the value; never invent a
|
|
30
|
+
placeholder.
|
|
31
|
+
|
|
32
|
+
Install (Node): `npm install @openreceive/express @openreceive/react` — swap
|
|
33
|
+
the adapter (`fastify`, `next`) and UI package (`vue`, `svelte`, `angular`,
|
|
34
|
+
`elements`) for the stack. Install (Rails): `bundle add openreceive-rails`.
|
|
35
|
+
|
|
36
|
+
## The three server objects
|
|
37
|
+
|
|
38
|
+
| Object | Built with | Talks to |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| Wallet client | `createOpenReceive()` | the merchant's wallet — mints invoices, reads settlement, holds the NWC code |
|
|
41
|
+
| Host | `createHost()` | your database — your hooks plus the `openreceive_payments` table |
|
|
42
|
+
| HTTP routes | `openReceiveExpress()` / `openReceiveFastify()` / `openReceiveNext()` / the Rails engine | the browser — mounted at `/openreceive` by default |
|
|
43
|
+
|
|
44
|
+
The quickstart's one-factory form (`openReceiveExpress({ wallet, storage,
|
|
45
|
+
amountFor, authorize })`) builds all three; compose them separately only for a
|
|
46
|
+
shared wallet client or a custom repository. The checkout UI
|
|
47
|
+
(`<Checkout reference={...} prefix="/openreceive" />`) is the optional fourth
|
|
48
|
+
piece.
|
|
49
|
+
|
|
50
|
+
## The host contract: authorize, amountFor, onPaid
|
|
51
|
+
|
|
52
|
+
Your application keeps orders, users, prices, and fulfillment. Three hooks are
|
|
53
|
+
the entire bridge — wire them to the models this app already has, never to
|
|
54
|
+
copied demo models:
|
|
55
|
+
|
|
56
|
+
- `amountFor(reference)` — the authoritative price, read from your own data.
|
|
57
|
+
Return `{ currency, value, description }` with `value` a **decimal string**
|
|
58
|
+
(never a float, never payer input), or `null` when there is nothing to pay
|
|
59
|
+
for. The `reference` is your order id: one per thing you fulfill, created
|
|
60
|
+
before checkout, kept across retries, never reused.
|
|
61
|
+
- `authorize({ action, request, resource })` — your own access check, run on
|
|
62
|
+
every request. `resource.reference` is a claim the payer made, not proof;
|
|
63
|
+
read a real session.
|
|
64
|
+
- `onPaid({ reference, paidAt, query })` — fulfillment, run once per reference
|
|
65
|
+
inside the settlement transaction, only for the first settled attempt. Use
|
|
66
|
+
the provided `query`, not your ORM's other connection, and guard the
|
|
67
|
+
transition (`UPDATE … WHERE state = 'awaiting_payment'`).
|
|
68
|
+
|
|
69
|
+
## 409 is a state, not a failure
|
|
70
|
+
|
|
71
|
+
The library serializes attempts per reference. A create that returns **409
|
|
72
|
+
CONFLICT** is normal checkout flow: the reference already settled, or an unpaid
|
|
73
|
+
checkout for that payment method is already in progress. Surface it as order
|
|
74
|
+
state; do not retry-loop it, and do not build an idempotency store around it —
|
|
75
|
+
that serialization is the library's job. (A hook failure while persisting an
|
|
76
|
+
attempt is a **503 retryable**, deliberately distinct.)
|
|
77
|
+
|
|
78
|
+
## Secrets
|
|
79
|
+
|
|
80
|
+
`NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,
|
|
81
|
+
logs, assets, or tests. Boot fails closed if the NWC code advertises spend
|
|
82
|
+
methods such as `pay_invoice` — mint a receive-only code
|
|
83
|
+
(https://openreceive.org/get_a_nwc_code_to_receive_payments) instead of
|
|
84
|
+
overriding.
|
|
85
|
+
|
|
86
|
+
## Database tables
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
npx openreceive scaffold payments --orm prisma # or drizzle | typeorm | sequelize | knex
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
emits the `openreceive_payments` + `openreceive_meta` migration for THIS app's
|
|
93
|
+
database (Rails: `bin/rails generate openreceive:install`); run it through the
|
|
94
|
+
app's normal migration workflow. The tables sit beside your models — no
|
|
95
|
+
relations to them, no separate database, no Redis.
|
|
96
|
+
|
|
97
|
+
## Verify, and test without a real wallet
|
|
98
|
+
|
|
99
|
+
`npx openreceive doctor` checks the configuration and says what to fix.
|
|
100
|
+
|
|
101
|
+
For tests, inject a fake wallet at the stable seams — `client` on
|
|
102
|
+
`createOpenReceive` (any object with `preflight`, `makeInvoice`,
|
|
103
|
+
`listTransactions`) or `config.nwc_client` in Rails — plus
|
|
104
|
+
`StaticPriceProvider` for fiat pricing without a network. Your routes,
|
|
105
|
+
persistence, reconcile, and `onPaid` then run the production code paths.
|
|
106
|
+
Details: https://openreceive.org/guides/host-testing.md
|
|
107
|
+
|
|
108
|
+
## Deeper documentation
|
|
109
|
+
|
|
110
|
+
Fetch on demand — each URL is raw markdown:
|
|
111
|
+
https://openreceive.org/guides/authorization.md ·
|
|
112
|
+
https://openreceive.org/guides/storage.md ·
|
|
113
|
+
https://openreceive.org/guides/api-reference.md ·
|
|
114
|
+
https://openreceive.org/guides/security.md ·
|
|
115
|
+
https://openreceive.org/openapi.yaml (the normative HTTP contract) ·
|
|
116
|
+
https://openreceive.org/llms.txt (the full index)
|
|
@@ -0,0 +1,480 @@
|
|
|
1
|
+
# OpenReceive agent directions (Node.js)
|
|
2
|
+
|
|
3
|
+
These directions describe OpenReceive 0.3.3.
|
|
4
|
+
|
|
5
|
+
Add OpenReceive to a Node application — the app you are already working in. You
|
|
6
|
+
do not need a copy of the OpenReceive source: the packages are on npm, and the
|
|
7
|
+
quickstart is appended to this file in full, so you can do the whole integration
|
|
8
|
+
without fetching anything. Prefer the published packages and the routes they
|
|
9
|
+
mount — do not reimplement wallet RPC, settlement, or pricing.
|
|
10
|
+
|
|
11
|
+
Do not clone the OpenReceive repository into this app, and do not copy a demo's
|
|
12
|
+
models (`ShopOrder`, a signed-cookie visitor, an in-memory catalog) over tables
|
|
13
|
+
that already exist. Find this application's order, product, and user models —
|
|
14
|
+
whatever they are actually named — and map the three hooks onto those.
|
|
15
|
+
|
|
16
|
+
## What OpenReceive is
|
|
17
|
+
|
|
18
|
+
A payment library that runs inside YOUR server. It mounts HTTP routes in the
|
|
19
|
+
application you are editing, issues Lightning invoices against a wallet the
|
|
20
|
+
merchant already controls, and calls back into your code when one settles. There
|
|
21
|
+
is no OpenReceive account and no API key, and OpenReceive never holds the funds —
|
|
22
|
+
the sats land in the wallet the merchant connected.
|
|
23
|
+
|
|
24
|
+
The one required credential is a receive-only NWC code (Nostr Wallet Connect):
|
|
25
|
+
a string from the merchant's wallet that can create invoices and read their
|
|
26
|
+
status, and cannot spend. A swap provider (an "LSC" code) optionally lets the
|
|
27
|
+
payer send USDT, USDC, ETH or SOL instead, converted into that same
|
|
28
|
+
Lightning payment. You supply those credentials and three hooks — `authorize`, `amountFor`,
|
|
29
|
+
`onPaid`;
|
|
30
|
+
OpenReceive supplies invoices, polling, settlement and the checkout UI. It never
|
|
31
|
+
owns orders, users, prices, or fulfillment.
|
|
32
|
+
|
|
33
|
+
## Step 0 — check the environment before you write code
|
|
34
|
+
|
|
35
|
+
Do this before installing packages or editing files.
|
|
36
|
+
|
|
37
|
+
1. Look for `NWC_URI` in this app's server environment — `.env`, the process
|
|
38
|
+
env, the deploy config, whatever this app already uses. If the app runs in a
|
|
39
|
+
container the value is in none of those: ask the running process
|
|
40
|
+
(`docker exec <container> printenv NWC_URI`), because finding the NAME in a
|
|
41
|
+
compose file proves nothing about the value. Never print or echo the value
|
|
42
|
+
itself; only report whether it is set. Check for `LSC_URI_PRIMARY` in the
|
|
43
|
+
same pass.
|
|
44
|
+
2. If BOTH are already set — the common case in an existing app — say so and go
|
|
45
|
+
straight to the quickstart. Steps 3 and 4 are for an environment that is
|
|
46
|
+
missing one; do not stop to ask about altcoins that are already configured.
|
|
47
|
+
If only `NWC_URI` is set, Bitcoin already works: continue, and raise the
|
|
48
|
+
altcoin question at step 4 rather than blocking on it.
|
|
49
|
+
3. If `NWC_URI` is missing or empty, stop and tell the user exactly what to
|
|
50
|
+
create:
|
|
51
|
+
|
|
52
|
+
> OpenReceive cannot issue an invoice without a receive-only NWC code. Get
|
|
53
|
+
> one at https://openreceive.org/get_a_nwc_code_to_receive_payments, then
|
|
54
|
+
> put `NWC_URI=<the code>` in this app's server environment — for most apps
|
|
55
|
+
> that is a `.env` file in the project root — and tell me when it's set.
|
|
56
|
+
|
|
57
|
+
Wait for the user before wiring OpenReceive; do not invent a placeholder
|
|
58
|
+
value. Waiting is not idleness: you may write `.env.example` with the
|
|
59
|
+
variable NAMES only (`NWC_URI=`, `LSC_URI_PRIMARY=`) so the merchant has a
|
|
60
|
+
file to copy, and keep building the parts of the host that do not touch
|
|
61
|
+
OpenReceive — the order model, the cart, the routes. The stop guards the
|
|
62
|
+
credential, not the rest of the app.
|
|
63
|
+
4. If `LSC_URI_PRIMARY` was not already set, ask the user: "Do you want to
|
|
64
|
+
accept altcoins and stablecoins (USDT, USDC, ETH, SOL) as well as
|
|
65
|
+
Bitcoin?"
|
|
66
|
+
|
|
67
|
+
- Yes → send them to https://openreceive.org/set_up_swap_provider for a
|
|
68
|
+
swap-provider (LSC) code, to set as `LSC_URI_PRIMARY` in the same server
|
|
69
|
+
environment. Do NOT wait for it: no application code reads the value, so
|
|
70
|
+
the integration is identical with or without it — the library picks it up
|
|
71
|
+
from the environment and swaps switch on. What a yes DOES change is the
|
|
72
|
+
refund route back (the swap non-negotiable below): build it as part of
|
|
73
|
+
this integration, not when the code arrives.
|
|
74
|
+
- No → skip it. Bitcoin over Lightning works with `NWC_URI` alone, and you
|
|
75
|
+
can add a swap provider later without changing application code.
|
|
76
|
+
5. Check the environment again and confirm `NWC_URI` is present.
|
|
77
|
+
`LSC_URI_PRIMARY` may land later; swaps stay off until it does, and no code
|
|
78
|
+
changes when it arrives.
|
|
79
|
+
6. If OpenReceive is ALREADY installed here, check the installed versions of
|
|
80
|
+
`@openreceive/node` and `@openreceive/browser` against the release named at
|
|
81
|
+
the top of this file. The headless display models below do not exist in
|
|
82
|
+
older versions, and the first tile click throws with nothing saying why.
|
|
83
|
+
Upgrade first.
|
|
84
|
+
|
|
85
|
+
Only then start the quickstart.
|
|
86
|
+
|
|
87
|
+
## Non-negotiables
|
|
88
|
+
|
|
89
|
+
The quickstart below has the code. These are the rules it cannot state for
|
|
90
|
+
itself, and they hold for every integration.
|
|
91
|
+
|
|
92
|
+
- OpenReceive never owns orders, users, prices, or fulfillment. The section
|
|
93
|
+
below is how those tables sit next to the library — not a second order model,
|
|
94
|
+
and not a Prisma/Drizzle relation to `openreceive_payments`.
|
|
95
|
+
- Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
|
|
96
|
+
logs, or assets.
|
|
97
|
+
- The host owns the price. `amountFor` reads it from your own data; reject
|
|
98
|
+
payer-supplied amounts.
|
|
99
|
+
- `authorize` runs on every request, and the `resource` it receives is a CLAIM
|
|
100
|
+
the payer made, not proof. Read a framework session; never trust a body field.
|
|
101
|
+
- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
|
|
102
|
+
per thing you fulfill, created before checkout, kept across retries, never
|
|
103
|
+
reused. A fresh id per page load lets one order be paid twice.
|
|
104
|
+
- Receive-only NWC is required; a spend-capable code fails closed at boot unless
|
|
105
|
+
explicitly overridden.
|
|
106
|
+
- There is NO merchant-initiated refund of a settled Lightning payment, because
|
|
107
|
+
the wallet cannot spend. Swap refunds — a payer reclaiming a deposit that
|
|
108
|
+
never converted — are the only refund OpenReceive performs, and only from the
|
|
109
|
+
`refund_required` provider state. Do not build, promise, or imply a Lightning
|
|
110
|
+
refund path.
|
|
111
|
+
- IF YOU TURN SWAPS ON, BUILD THE ROUTE BACK. A deposit that arrives short or
|
|
112
|
+
late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
|
|
113
|
+
after leaving your page to fetch an address from another wallet. Three things
|
|
114
|
+
must exist or that money is unreachable through your UI: a per-order URL your
|
|
115
|
+
server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
|
|
116
|
+
order-summary route to restore the order from, and the ATTEMPT.
|
|
117
|
+
`/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
|
|
118
|
+
reference alone opens on the method grid. Re-picking the same coin
|
|
119
|
+
(`POST /swaps`) re-serves the committed attempt — but only while it is live,
|
|
120
|
+
and the shadow invoice behind a swap lasts about half an hour, after which the
|
|
121
|
+
same click mints a NEW deposit address and the refund is off-screen. Keep the
|
|
122
|
+
`payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
|
|
123
|
+
such window. https://openreceive.org/guides/swap-refunds.md
|
|
124
|
+
- Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
|
|
125
|
+
the price from `amountFor` and both drop-ins render it above the amount.
|
|
126
|
+
Without it the checkout is a QR and "$1.00" with no sign of what the dollar
|
|
127
|
+
is for.
|
|
128
|
+
- Show the payer the transaction record: `createTransactionDetails(...)` rows,
|
|
129
|
+
collapsed behind a caret, on the live checkout AND on the receipt. A payment
|
|
130
|
+
hash and a deposit txid are the only evidence a payer has that they paid you.
|
|
131
|
+
`<Checkout>` / `<openreceive-checkout>` already render this panel and the
|
|
132
|
+
`description` — these two rules cost you code only on a custom UI or your own
|
|
133
|
+
receipt page, never a reason to replace the drop-in. (It returns no rows
|
|
134
|
+
while the rail is `checkout_lock` — before the payer has chosen anything
|
|
135
|
+
there is no transaction — so render the caret only when the rows are
|
|
136
|
+
non-empty.)
|
|
137
|
+
- HTTP JSON is snake_case; TypeScript APIs are camelCase.
|
|
138
|
+
- Money is integers or decimal strings — never binary floats.
|
|
139
|
+
|
|
140
|
+
## Your tables, not ours
|
|
141
|
+
|
|
142
|
+
`npx openreceive scaffold payments` emits `openreceive_payments` and
|
|
143
|
+
`openreceive_meta` for THIS application's database. That is the whole
|
|
144
|
+
persistence OpenReceive needs. It does not replace your orders, users, or
|
|
145
|
+
products, and you do not join them.
|
|
146
|
+
|
|
147
|
+
- **Find this app's models first.** They may be named `Order`, `Invoice`,
|
|
148
|
+
`Booking`, `Product`, `Variant`, `User`, `Account` — anything. Wire the hooks
|
|
149
|
+
to those. Do not generate a parallel `ShopOrder` / `ShopProduct` / `ShopUser`
|
|
150
|
+
stack.
|
|
151
|
+
- **The payable row's id is the `reference`.** Create it before checkout, keep
|
|
152
|
+
it across retries, never reuse it. Pass that id to `<Checkout>` /
|
|
153
|
+
`<openreceive-checkout>`. A fresh id per page load lets one order be paid
|
|
154
|
+
twice.
|
|
155
|
+
- **Products (or the catalog) are the price authority.** Order creation reads
|
|
156
|
+
live prices into the order (snapshot line items if this app has them).
|
|
157
|
+
`amountFor` reads only that order — never a payer-supplied amount, never a
|
|
158
|
+
live catalog lookup that could re-price a cart already placed. Return
|
|
159
|
+
`{ currency, value }` as a decimal STRING, plus a `description` of what they
|
|
160
|
+
are buying.
|
|
161
|
+
- **Users own the order; OpenReceive never sees them.** `authorize` uses the
|
|
162
|
+
same ownership check this app already uses on the order show / pay page —
|
|
163
|
+
`sessions.currentUser(request)`, a cookie, whatever it is.
|
|
164
|
+
`resource.reference` is a claim the payer sent, not proof.
|
|
165
|
+
- **The order is unpaid or paid.** Do not copy `pending` / `expired` / `failed`
|
|
166
|
+
/ `attention` onto it. Those are attempt statuses on `openreceive_payments`. An
|
|
167
|
+
expired invoice does not cancel the order; a later checkout may mint another
|
|
168
|
+
attempt. The library refuses a new checkout under a reference that already
|
|
169
|
+
settled (409).
|
|
170
|
+
- **Pass this app's `db` handle.** Do not add a Prisma/Drizzle relation from
|
|
171
|
+
Order to `openreceive_payments`, and do not implement `PaymentRepository`
|
|
172
|
+
unless no supported handle can reach this database. `reference` is not unique
|
|
173
|
+
(many attempts per order). Fulfillment is a guarded transition on YOUR order
|
|
174
|
+
row inside `onPaid` — `UPDATE … WHERE state = 'awaiting_payment'` (or this
|
|
175
|
+
app's equivalent) through the `query` the library hands you, on that same
|
|
176
|
+
settlement transaction, not a second connection from your ORM. Database writes
|
|
177
|
+
only in the hook; emails, jobs, and pushes after commit. Placeholder style is
|
|
178
|
+
the dialect you declared: `?` on sqlite, `$1` on postgres.
|
|
179
|
+
|
|
180
|
+
## If you build your own checkout UI
|
|
181
|
+
|
|
182
|
+
The drop-ins (`<Checkout>`, `<openreceive-checkout>`) already obey all of this.
|
|
183
|
+
This list is the short form of https://openreceive.org/guides/checkout-ux.md, for a
|
|
184
|
+
UI built on `@openreceive/browser/headless`. Read that before writing
|
|
185
|
+
components.
|
|
186
|
+
|
|
187
|
+
- `createCheckoutController` is the engine. Do not hand-roll a poll loop.
|
|
188
|
+
- `createCheckoutStatusModel` for the status line. Do not draw a
|
|
189
|
+
Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
|
|
190
|
+
- `resolveWizardSelection` decides whether to ask "which network?". A
|
|
191
|
+
one-network asset starts the swap from the tile. Key `selectedAssetByGroup`
|
|
192
|
+
by group (`USDT`), valued by `pay_in_asset` (`USDT_TRON`).
|
|
193
|
+
- `createMethodGridDisplay` for tiles, including `limitMessage` so an
|
|
194
|
+
unavailable method says the minimum in the payer's currency.
|
|
195
|
+
- `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
|
|
196
|
+
and the bare amount each get a copy row. Render `swap.networkWarning*` as
|
|
197
|
+
the model gives it.
|
|
198
|
+
- `createCheckoutSession` owns mint and swap start. To start swaps, pass its
|
|
199
|
+
`swap` option (`selection`, `prefix`, `fetch`) together. Without it
|
|
200
|
+
`startSwap` reports through `onError`.
|
|
201
|
+
- `createQrSvg` is async. Use `createQrSvgController` so you do not render
|
|
202
|
+
`[object Promise]`.
|
|
203
|
+
- `checkoutLabels` for every payer-facing string. Only write copy it lacks.
|
|
204
|
+
- `stageSwapRefund` then `confirmSwapRefund` — only the second submits.
|
|
205
|
+
Validate with `getSwapRefundFormError`. Treat `409` as a normal outcome.
|
|
206
|
+
- Pass `{ resumable: true }` to `createSwapDisplayModel` when the payer has
|
|
207
|
+
a URL they can come back to, and render `display.refundReturnLabel`.
|
|
208
|
+
Resume helpers (`createGuestCheckoutResume`, `createGuestOrderFetcher`)
|
|
209
|
+
are on `@openreceive/browser`, not `/headless`.
|
|
210
|
+
- A refund replaces the deposit panel. On `refund_required` also drop
|
|
211
|
+
"switch payment method".
|
|
212
|
+
- No "Open wallet" button on desktop.
|
|
213
|
+
- Wallet suggestions: `getPaymentWizardRoutes()` +
|
|
214
|
+
`createWizardRouteDisplays`. Lightning only. Host the icons with
|
|
215
|
+
`assetBaseUrl` / `asset-base-url`.
|
|
216
|
+
|
|
217
|
+
## More documentation
|
|
218
|
+
|
|
219
|
+
Fetch one when the moment comes. Each is raw markdown, so a plain GET is
|
|
220
|
+
enough; drop the `.md` for the same page a person would read.
|
|
221
|
+
|
|
222
|
+
- https://openreceive.org/guides/authorization.md — before you write `authorize`
|
|
223
|
+
- https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one
|
|
224
|
+
- https://openreceive.org/guides/storage.md — the payment tables and the attempt state machine
|
|
225
|
+
- https://openreceive.org/guides/node-orms.md — recipes for Prisma, Drizzle, Knex, TypeORM, Sequelize
|
|
226
|
+
- https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots
|
|
227
|
+
- https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
|
|
228
|
+
- https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
|
|
229
|
+
- https://openreceive.org/guides/provider-registry.md — where the packaged icons and pay
|
|
230
|
+
tutorials come from, and how to serve them. The asset rule is the one a custom
|
|
231
|
+
UI is most likely to get wrong; this is the page that owns it, not the summary
|
|
232
|
+
in checkout-ux.md
|
|
233
|
+
- https://openreceive.org/guides/automated-swaps.md — only if `LSC_URI_PRIMARY` is set
|
|
234
|
+
- https://openreceive.org/guides/swap-refunds.md — the refund flow, and the route back to it. Read it before you turn swaps on
|
|
235
|
+
- https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is
|
|
236
|
+
- https://openreceive.org/guides/price-feeds.md — where the fiat→sats rate comes from, and how to replace it
|
|
237
|
+
- https://openreceive.org/guides/host-testing.md — testing your three hooks without a live wallet or provider
|
|
238
|
+
- https://openreceive.org/guides/rate-limiting.md — before a public shop goes live
|
|
239
|
+
- https://openreceive.org/guides/security.md and https://openreceive.org/guides/deploying.md — before this goes anywhere real
|
|
240
|
+
- https://openreceive.org/guides/api-reference.md — every route, option and error code
|
|
241
|
+
- https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the shipped adapter's routes with your own
|
|
242
|
+
- https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
|
|
243
|
+
- https://openreceive.org/guides.md — the index, if what you need is not above
|
|
244
|
+
|
|
245
|
+
Questions, or a problem with the library itself:
|
|
246
|
+
https://openreceive.org/contact
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## The quickstart, in full
|
|
251
|
+
|
|
252
|
+
Inlined verbatim so this file needs no network access — follow it once Step 0
|
|
253
|
+
passes. The page it comes from is https://openreceive.org/guides/quickstart-node.
|
|
254
|
+
|
|
255
|
+
## Node quickstart
|
|
256
|
+
|
|
257
|
+
Express + React. Requires Node ≥ 22.
|
|
258
|
+
|
|
259
|
+
### 1. Install
|
|
260
|
+
|
|
261
|
+
```sh
|
|
262
|
+
npm install @openreceive/express @openreceive/react
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Install the adapter for your server and the UI package for your frontend; the
|
|
266
|
+
wallet client, HTTP handler, and contracts come along as dependencies. The
|
|
267
|
+
`openreceive` package is the CLI only — `npx openreceive …` below needs no
|
|
268
|
+
install. Different stack? Swap the two packages; the rest of this guide is
|
|
269
|
+
identical.
|
|
270
|
+
|
|
271
|
+
| | Packages |
|
|
272
|
+
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
273
|
+
| Server | `@openreceive/express`, `@openreceive/fastify`, `@openreceive/next` |
|
|
274
|
+
| Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
|
|
275
|
+
|
|
276
|
+
On a fresh project, also install what this guide assumes is already there: the
|
|
277
|
+
framework and an env loader (`npm install express dotenv`), plus your ORM
|
|
278
|
+
before step 2 (`npm install prisma @prisma/client` on the Prisma path) —
|
|
279
|
+
`openreceive scaffold` emits files for the ORM you name but never installs it.
|
|
280
|
+
|
|
281
|
+
npm environments that run with `ignore-scripts` (some editor sandboxes) skip
|
|
282
|
+
Prisma's engine download and esbuild's binary postinstall, so a typecheck or
|
|
283
|
+
build that fails only there is environmental, not a code problem.
|
|
284
|
+
|
|
285
|
+
### 2. Migrate the payment tables
|
|
286
|
+
|
|
287
|
+
```sh
|
|
288
|
+
npx openreceive scaffold payments --orm prisma # or drizzle | typeorm | sequelize | knex
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
`openreceive scaffold payments` emits one schema/migration file for your ORM
|
|
292
|
+
and a wiring guide. It never touches a database.
|
|
293
|
+
→ [openreceive scaffold payments](https://openreceive.org/guides/api-reference.md#openreceive-scaffold-payments)
|
|
294
|
+
|
|
295
|
+
Then run the emitted migration through your normal workflow (for example
|
|
296
|
+
`npx prisma migrate dev`). OpenReceive owns the tables' logic at runtime; there
|
|
297
|
+
is nothing else to generate. Details:
|
|
298
|
+
[Payment storage](https://openreceive.org/guides/storage.md), [Node ORM recipes](https://openreceive.org/guides/node-orms.md).
|
|
299
|
+
|
|
300
|
+
No ORM? A bare driver handle (`pg`, `node:sqlite`, `better-sqlite3`) is a
|
|
301
|
+
supported `db` in step 4, and there is no scaffold flavor for it — execute the
|
|
302
|
+
same DDL once yourself with `paymentsSchemaSql(dialect)` from
|
|
303
|
+
`@openreceive/http` instead of scaffolding.
|
|
304
|
+
|
|
305
|
+
### 3. Add wallet credentials
|
|
306
|
+
|
|
307
|
+
Create a server-only `.env`:
|
|
308
|
+
|
|
309
|
+
```dotenv
|
|
310
|
+
NWC_URI=
|
|
311
|
+
LSC_URI_PRIMARY=
|
|
312
|
+
LSC_URI_BACKUP=
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
1. Get a receive-only NWC code from a compatible wallet
|
|
316
|
+
([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments))
|
|
317
|
+
→ `NWC_URI`.
|
|
318
|
+
2. Optionally set up a [swap provider](https://openreceive.org/set_up_swap_provider)
|
|
319
|
+
→ `LSC_URI_PRIMARY` (and `LSC_URI_BACKUP` if you have one).
|
|
320
|
+
|
|
321
|
+
Never put these values in browser code. Your application refuses to start if
|
|
322
|
+
the NWC code also advertises spend methods such as `pay_invoice`; mint a
|
|
323
|
+
receive-only code ([Security](https://openreceive.org/guides/security.md)).
|
|
324
|
+
|
|
325
|
+
OpenReceive reads `process.env`; creating a `.env` file is not enough on its
|
|
326
|
+
own. How that file (or production secrets) get into the process —
|
|
327
|
+
`dotenv` on Express/Fastify, Next.js auto-load, secret managers in
|
|
328
|
+
production — is on [Environment variables](https://openreceive.org/guides/environment-variables.md).
|
|
329
|
+
|
|
330
|
+
### 4. Wire OpenReceive
|
|
331
|
+
|
|
332
|
+
One factory: your hooks plus a database handle. The adapter builds the
|
|
333
|
+
wallet client and the host; there is no background reconciler —
|
|
334
|
+
settlement piggybacks on requests through the durable gate.
|
|
335
|
+
|
|
336
|
+
```ts
|
|
337
|
+
import "dotenv/config"; // loads .env into process.env; nothing else does
|
|
338
|
+
import express from "express";
|
|
339
|
+
import { openReceiveExpress } from "@openreceive/express";
|
|
340
|
+
import { db, orders, sessions } from "./app.ts"; // your existing database handle and models
|
|
341
|
+
|
|
342
|
+
const app = express();
|
|
343
|
+
app.use(express.json());
|
|
344
|
+
const openreceive = openReceiveExpress({
|
|
345
|
+
wallet: { nwc: process.env.NWC_URI! }, // receive-only NWC code; your app refuses to start otherwise
|
|
346
|
+
storage: {
|
|
347
|
+
db, // pg Pool/Client, node:sqlite, better-sqlite3, or a custom adapter
|
|
348
|
+
onPaid: async ({ reference, paidAt, query }) => {
|
|
349
|
+
// Settlement transaction; runs only for the first settled attempt for a
|
|
350
|
+
// reference. The WHERE clause is the lock: a second fulfillment path of
|
|
351
|
+
// yours (admin action, replayed job) updates zero rows and does nothing.
|
|
352
|
+
// Use `query` here, not your ORM's other connection. `?` on sqlite, `$1`
|
|
353
|
+
// on postgres.
|
|
354
|
+
const claimed = await query(
|
|
355
|
+
"UPDATE orders SET state = 'paid', paid_at = ? WHERE id = ? AND state = 'awaiting_payment' RETURNING id",
|
|
356
|
+
[paidAt, reference],
|
|
357
|
+
);
|
|
358
|
+
if (claimed.length === 0) return;
|
|
359
|
+
},
|
|
360
|
+
},
|
|
361
|
+
// The price for a reference — here, your order id — from your own data;
|
|
362
|
+
// OpenReceive converts it into the Lightning invoice. Return null when
|
|
363
|
+
// there is nothing to pay for. `value` is a decimal STRING from the order
|
|
364
|
+
// row, never a float and never a request param. `description` is what the
|
|
365
|
+
// payer is buying, in your own words.
|
|
366
|
+
amountFor: async (reference) => {
|
|
367
|
+
const order = await orders.find(reference);
|
|
368
|
+
return order
|
|
369
|
+
? {
|
|
370
|
+
currency: "USD",
|
|
371
|
+
value: order.total.toString(),
|
|
372
|
+
description: `${order.lines.length} items`,
|
|
373
|
+
}
|
|
374
|
+
: null;
|
|
375
|
+
},
|
|
376
|
+
// Your own access check: may this caller do this action to this reference?
|
|
377
|
+
authorize: async ({ action, request, resource }) =>
|
|
378
|
+
orders.viewerMay(
|
|
379
|
+
await sessions.currentUser(request),
|
|
380
|
+
resource.reference,
|
|
381
|
+
action,
|
|
382
|
+
),
|
|
383
|
+
// Recommended for public web shops: caps invoice creation at 60 per client IP
|
|
384
|
+
// per hour. Leave it off (the default) for point-of-sale deployments, where
|
|
385
|
+
// many payers share the terminal's IP.
|
|
386
|
+
rateLimiting: true,
|
|
387
|
+
});
|
|
388
|
+
// Behind a reverse proxy or load balancer, rate limiting needs the real client
|
|
389
|
+
// IP — without this every payer shares the proxy's IP and one abuser can lock
|
|
390
|
+
// checkout for everyone. Delete the line only if the app faces the network
|
|
391
|
+
// directly (see the rate-limiting guide).
|
|
392
|
+
app.set("trust proxy", 1);
|
|
393
|
+
app.use(openreceive);
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
The first request checks the wallet. Later OpenReceive requests also settle
|
|
397
|
+
pending invoices, so a payer who closes the tab is still covered.
|
|
398
|
+
`authorize` runs on every request.
|
|
399
|
+
→ [openReceiveExpress](https://openreceive.org/guides/api-reference.md#openreceiveexpress) ·
|
|
400
|
+
[authorize context](https://openreceive.org/guides/api-reference.md#the-authorize-context)
|
|
401
|
+
|
|
402
|
+
`rateLimiting: true` is for public web shops. Leave it off for point-of-sale,
|
|
403
|
+
where many payers share one IP. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md)
|
|
404
|
+
|
|
405
|
+
An optional worker, `startNotificationWorker({ service, host })`, listens for
|
|
406
|
+
wallet payment notifications so settlement does not wait for the next page
|
|
407
|
+
load. → [startNotificationWorker](https://openreceive.org/guides/api-reference.md#startnotificationworker)
|
|
408
|
+
|
|
409
|
+
Composing the pieces yourself (`createOpenReceive` + `createHost`) is
|
|
410
|
+
supported when you need a shared wallet client or a custom repository.
|
|
411
|
+
→ [createOpenReceive](https://openreceive.org/guides/api-reference.md#createopenreceive) ·
|
|
412
|
+
[createHost](https://openreceive.org/guides/api-reference.md#createhost)
|
|
413
|
+
|
|
414
|
+
Your app also needs an ordinary order-creation route that validates the cart,
|
|
415
|
+
prices with exact decimal math, and returns the order id the page will pass as
|
|
416
|
+
the `reference`. OpenReceive never prices from payer input.
|
|
417
|
+
|
|
418
|
+
The `reference` is a string you choose, and it is the fulfillment identity:
|
|
419
|
+
your order id — one per thing you fulfill, created before checkout, kept
|
|
420
|
+
across retries, never reused. OpenReceive never looks inside it, but `onPaid`
|
|
421
|
+
runs once per reference, a new checkout under a reference that already
|
|
422
|
+
settled is refused with 409, and a fresh id per page load lets one order be
|
|
423
|
+
paid twice.
|
|
424
|
+
|
|
425
|
+
Naming boundary: TypeScript APIs use camelCase fields (`paymentHash`,
|
|
426
|
+
`amountMsats`); everything on the wire — the mounted HTTP routes and the
|
|
427
|
+
browser snapshots — is snake_case (`payment_hash`, `amount_msats`).
|
|
428
|
+
|
|
429
|
+
### 5. Render checkout
|
|
430
|
+
|
|
431
|
+
```tsx
|
|
432
|
+
import { Checkout } from "@openreceive/react";
|
|
433
|
+
import "@openreceive/react/styles.css";
|
|
434
|
+
|
|
435
|
+
<Checkout reference={order.id} prefix="/openreceive" />;
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
The checkout renders, polls, and settles itself. The compiled `styles.css`
|
|
439
|
+
sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained — a
|
|
440
|
+
plain `<link rel="stylesheet">` works with no build step.
|
|
441
|
+
|
|
442
|
+
`<Checkout>` is complete as rendered: it already shows the `description` from
|
|
443
|
+
`amountFor` and the collapsed transaction-details panel. Do not build a custom
|
|
444
|
+
UI to satisfy those rules — they only become your job if you replace the
|
|
445
|
+
drop-in ([Checkout UX](https://openreceive.org/guides/checkout-ux.md)).
|
|
446
|
+
|
|
447
|
+
Match the host page's theme: by default the checkout follows the payer's
|
|
448
|
+
stored choice, then the system scheme. If this page is always one theme, lock
|
|
449
|
+
it — `<Checkout theme="dark" … />` (`theme` attribute on the custom element) —
|
|
450
|
+
so a white card never lands on a dark page. The checkout is styled by CSS
|
|
451
|
+
variables under `data-theme`; [Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) has
|
|
452
|
+
the knobs.
|
|
453
|
+
|
|
454
|
+
Outside Vite/Rollup (esbuild, webpack, a plain script tag) the packaged
|
|
455
|
+
payment-method icons cannot resolve their own URLs — the drop-in needs this
|
|
456
|
+
exactly as a custom UI does. Serve the two packages' `dist/assets` trees and
|
|
457
|
+
pass the base as `assetBaseUrl="/openreceive-assets"`
|
|
458
|
+
([Provider registry](https://openreceive.org/guides/provider-registry.md#assets-are-files-your-host-serves)).
|
|
459
|
+
|
|
460
|
+
That is the whole loop: your server owns the price and the order, the payer gets
|
|
461
|
+
an invoice, and `onPaid` runs once inside the settlement transaction.
|
|
462
|
+
|
|
463
|
+
A runnable illustration of this boundary — not a template to copy models from —
|
|
464
|
+
is Buy a Button
|
|
465
|
+
(`examples/buttons/server/node-express`).
|
|
466
|
+
It has products, visitors, and orders, with the three hooks as the only bridge.
|
|
467
|
+
Map that shape onto the models in THIS app.
|
|
468
|
+
|
|
469
|
+
### 6. Verify
|
|
470
|
+
|
|
471
|
+
```sh
|
|
472
|
+
npx openreceive doctor
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
`openreceive doctor` checks Node, `NWC_URI`, and swap-provider configuration,
|
|
476
|
+
and probes the wallet relay to confirm the code is receive-only. Add
|
|
477
|
+
`--db <file-or-url>` to confirm the migration ran, and
|
|
478
|
+
`--url http://localhost:3000` to confirm the routes are mounted; every failing
|
|
479
|
+
line states its own fix.
|
|
480
|
+
→ [openreceive doctor](https://openreceive.org/guides/api-reference.md#openreceive-doctor)
|
|
@@ -0,0 +1,568 @@
|
|
|
1
|
+
# OpenReceive agent directions (Rails)
|
|
2
|
+
|
|
3
|
+
These directions describe OpenReceive 0.3.3.
|
|
4
|
+
|
|
5
|
+
Add OpenReceive to a Rails application — the app you are already working in. You
|
|
6
|
+
do not need a copy of the OpenReceive source: the gem is on RubyGems, the
|
|
7
|
+
frontend packages are on npm, and the quickstart is appended to this file in
|
|
8
|
+
full, so you can do the whole integration without fetching anything. Prefer the
|
|
9
|
+
published gem and the mounted engine routes — do not reimplement wallet RPC,
|
|
10
|
+
settlement, or pricing.
|
|
11
|
+
|
|
12
|
+
Do not clone the OpenReceive repository into this app, and do not copy a demo's
|
|
13
|
+
models (`ShopOrder`, `ShopUser`, a signed-cookie visitor) over tables that
|
|
14
|
+
already exist. Find this application's order, product, and user models — whatever
|
|
15
|
+
they are actually named — and map the three hooks onto those.
|
|
16
|
+
|
|
17
|
+
## What OpenReceive is
|
|
18
|
+
|
|
19
|
+
A payment library that runs inside YOUR server. It mounts HTTP routes in the
|
|
20
|
+
application you are editing, issues Lightning invoices against a wallet the
|
|
21
|
+
merchant already controls, and calls back into your code when one settles. There
|
|
22
|
+
is no OpenReceive account and no API key, and OpenReceive never holds the funds —
|
|
23
|
+
the sats land in the wallet the merchant connected.
|
|
24
|
+
|
|
25
|
+
The one required credential is a receive-only NWC code (Nostr Wallet Connect):
|
|
26
|
+
a string from the merchant's wallet that can create invoices and read their
|
|
27
|
+
status, and cannot spend. A swap provider (an "LSC" code) optionally lets the
|
|
28
|
+
payer send USDT, USDC, ETH or SOL instead, converted into that same
|
|
29
|
+
Lightning payment. You supply those credentials and three hooks — `config.authorize`,
|
|
30
|
+
`config.amount_for`, `config.on_paid`;
|
|
31
|
+
OpenReceive supplies invoices, polling, settlement and the checkout UI. It never
|
|
32
|
+
owns orders, users, prices, or fulfillment.
|
|
33
|
+
|
|
34
|
+
## Step 0 — check the environment before you write code
|
|
35
|
+
|
|
36
|
+
Do this before installing the gem or editing files.
|
|
37
|
+
|
|
38
|
+
1. Look for `NWC_URI` in this app's server environment — `.env`, Rails
|
|
39
|
+
credentials, the deploy config, whatever this app already uses. If the app
|
|
40
|
+
runs in a container the value is in none of those: ask the running process
|
|
41
|
+
(`docker exec <container> printenv NWC_URI`), because finding the NAME in a
|
|
42
|
+
compose file or `.kamal/secrets` proves nothing about the value. Never print
|
|
43
|
+
or echo the value itself; only report whether it is set. Check for
|
|
44
|
+
`LSC_URI_PRIMARY` in the same pass.
|
|
45
|
+
|
|
46
|
+
If OpenReceive is already installed here, `bin/rails openreceive:doctor`
|
|
47
|
+
answers this whole step in one command — every credential as set/unset, the
|
|
48
|
+
engine mount, the three hooks, and the wallet preflight. It never prints a
|
|
49
|
+
value.
|
|
50
|
+
2. If BOTH are already set — the common case in an existing app — say so and go
|
|
51
|
+
straight to the quickstart. Steps 3 and 4 are for an environment that is
|
|
52
|
+
missing one; do not stop to ask about altcoins that are already configured.
|
|
53
|
+
If only `NWC_URI` is set, Bitcoin already works: continue, and raise the
|
|
54
|
+
altcoin question at step 4 rather than blocking on it.
|
|
55
|
+
3. If `NWC_URI` is missing or empty, stop and tell the user exactly what to
|
|
56
|
+
create:
|
|
57
|
+
|
|
58
|
+
> OpenReceive cannot issue an invoice without a receive-only NWC code. Get
|
|
59
|
+
> one at https://openreceive.org/get_a_nwc_code_to_receive_payments, then
|
|
60
|
+
> put `NWC_URI=<the code>` in this app's server environment — for most apps
|
|
61
|
+
> that is a `.env` file in the project root — and tell me when it's set.
|
|
62
|
+
|
|
63
|
+
Wait for the user before wiring OpenReceive; do not invent a placeholder
|
|
64
|
+
value. Waiting is not idleness: you may write `.env.example` with the
|
|
65
|
+
variable NAMES only (`NWC_URI=`, `LSC_URI_PRIMARY=`) so the merchant has a
|
|
66
|
+
file to copy, and keep building the parts of the host that do not touch
|
|
67
|
+
OpenReceive — the order model, the cart, the routes. The stop guards the
|
|
68
|
+
credential, not the rest of the app.
|
|
69
|
+
4. If `LSC_URI_PRIMARY` was not already set, ask the user: "Do you want to
|
|
70
|
+
accept altcoins and stablecoins (USDT, USDC, ETH, SOL) as well as
|
|
71
|
+
Bitcoin?"
|
|
72
|
+
|
|
73
|
+
- Yes → send them to https://openreceive.org/set_up_swap_provider for a
|
|
74
|
+
swap-provider (LSC) code, to set as `LSC_URI_PRIMARY` in the same server
|
|
75
|
+
environment. Do NOT wait for it: no application code reads the value, so
|
|
76
|
+
the integration is identical with or without it — the engine picks it up
|
|
77
|
+
from the environment and swaps switch on. What a yes DOES change is the
|
|
78
|
+
refund route back (the swap non-negotiable below): build it as part of
|
|
79
|
+
this integration, not when the code arrives.
|
|
80
|
+
- No → skip it. Bitcoin over Lightning works with `NWC_URI` alone, and you
|
|
81
|
+
can add a swap provider later without changing application code.
|
|
82
|
+
5. Check the environment again and confirm `NWC_URI` is present.
|
|
83
|
+
`LSC_URI_PRIMARY` may land later; swaps stay off until it does, and no code
|
|
84
|
+
changes when it arrives.
|
|
85
|
+
6. If OpenReceive is ALREADY installed here, check the installed versions of
|
|
86
|
+
`openreceive-rails` and `@openreceive/browser` against the release named at
|
|
87
|
+
the top of this file. The headless display models below do not exist in
|
|
88
|
+
older versions, and the first tile click throws with nothing saying why.
|
|
89
|
+
Upgrade first — and if this app runs in containers, rebuild the images: the
|
|
90
|
+
gems are baked into the image, so an in-place `bundle update` is undone by
|
|
91
|
+
the next `compose up`.
|
|
92
|
+
|
|
93
|
+
Only then start the quickstart.
|
|
94
|
+
|
|
95
|
+
## Non-negotiables
|
|
96
|
+
|
|
97
|
+
The quickstart below has the code. These are the rules it cannot state for
|
|
98
|
+
itself, and they hold for every integration.
|
|
99
|
+
|
|
100
|
+
- OpenReceive never owns orders, users, prices, or fulfillment. The section
|
|
101
|
+
below is how those tables sit next to the engine — not a second order model,
|
|
102
|
+
and not an association to `OpenReceivePayment`.
|
|
103
|
+
- Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
|
|
104
|
+
logs, or assets.
|
|
105
|
+
- The host owns the price. `config.amount_for` reads it from your own data;
|
|
106
|
+
reject payer-supplied amounts.
|
|
107
|
+
- `config.authorize` runs on every request, and the `resource` it receives is a
|
|
108
|
+
CLAIM the payer made, not proof. Read the framework session; never trust a
|
|
109
|
+
body field.
|
|
110
|
+
- `config.on_paid` must be idempotent. It runs once per `reference` — your order
|
|
111
|
+
id, one per thing you fulfill, created before checkout, kept across retries,
|
|
112
|
+
never reused. A fresh id per page load lets one order be paid twice.
|
|
113
|
+
- Receive-only NWC is required; a spend-capable code fails closed at boot unless
|
|
114
|
+
explicitly overridden.
|
|
115
|
+
- There is NO merchant-initiated refund of a settled Lightning payment, because
|
|
116
|
+
the wallet cannot spend. Swap refunds — a payer reclaiming a deposit that
|
|
117
|
+
never converted — are the only refund OpenReceive performs, and only from the
|
|
118
|
+
`refund_required` provider state. Do not build, promise, or imply a Lightning
|
|
119
|
+
refund path.
|
|
120
|
+
- IF YOU TURN SWAPS ON, BUILD THE ROUTE BACK. A deposit that arrives short or
|
|
121
|
+
late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
|
|
122
|
+
after leaving your page to fetch an address from another wallet. Three things
|
|
123
|
+
must exist or that money is unreachable through your UI: a per-order URL your
|
|
124
|
+
server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
|
|
125
|
+
order-summary route to restore the order from, and the ATTEMPT.
|
|
126
|
+
`/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
|
|
127
|
+
reference alone opens on the method grid. Re-picking the same coin
|
|
128
|
+
(`POST /swaps`) re-serves the committed attempt — but only while it is live,
|
|
129
|
+
and the shadow invoice behind a swap lasts about half an hour, after which the
|
|
130
|
+
same click mints a NEW deposit address and the refund is off-screen. Keep the
|
|
131
|
+
`payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
|
|
132
|
+
such window. https://openreceive.org/guides/swap-refunds.md
|
|
133
|
+
- Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
|
|
134
|
+
the price from `config.amount_for` and both drop-ins render it above the
|
|
135
|
+
amount. Without it the checkout is a QR and "$1.00" with no sign of what the
|
|
136
|
+
dollar is for.
|
|
137
|
+
- Show the payer the transaction record: `createTransactionDetails(...)` rows,
|
|
138
|
+
collapsed behind a caret, on the live checkout AND on the receipt. A payment
|
|
139
|
+
hash and a deposit txid are the only evidence a payer has that they paid you.
|
|
140
|
+
`<openreceive-checkout>` / React's `<Checkout>` already render this panel and
|
|
141
|
+
the `description` — these two rules cost you code only on a custom UI or your
|
|
142
|
+
own receipt page, never a reason to replace the drop-in. (It returns no rows
|
|
143
|
+
while the rail is `checkout_lock` — before the payer has chosen anything
|
|
144
|
+
there is no transaction — so render the caret only when the rows are
|
|
145
|
+
non-empty.)
|
|
146
|
+
- HTTP JSON is snake_case; the browser packages' TypeScript APIs are camelCase.
|
|
147
|
+
- Money is integers or decimal strings — never binary floats.
|
|
148
|
+
|
|
149
|
+
## Your tables, not ours
|
|
150
|
+
|
|
151
|
+
The install migration adds `openreceive_payments` and `openreceive_meta` to THIS
|
|
152
|
+
application's database. That is the whole persistence OpenReceive needs. It does
|
|
153
|
+
not replace your orders, users, or products, and you do not join them.
|
|
154
|
+
|
|
155
|
+
- **Find this app's models first.** They may be named `Order`, `Invoice`,
|
|
156
|
+
`Booking`, `Product`, `Variant`, `User`, `Account` — anything. Wire the hooks
|
|
157
|
+
to those. Do not generate a parallel `ShopOrder` / `ShopProduct` / `ShopUser`
|
|
158
|
+
stack.
|
|
159
|
+
- **The payable row's id is the `reference`.** Create it before checkout, keep
|
|
160
|
+
it across retries, never reuse it. Pass that id to `<openreceive-checkout>`. A
|
|
161
|
+
fresh id per page load lets one order be paid twice.
|
|
162
|
+
- **Products (or the catalog) are the price authority.** Order creation reads
|
|
163
|
+
live prices into the order (snapshot line items if this app has them).
|
|
164
|
+
`config.amount_for` reads only that order — never a payer-supplied amount,
|
|
165
|
+
never a live catalog lookup that could re-price a cart already placed. Return
|
|
166
|
+
`{ currency:, value: }` as a decimal STRING, plus a `description` of what they
|
|
167
|
+
are buying.
|
|
168
|
+
- **Users own the order; OpenReceive never sees them.** `config.authorize` uses
|
|
169
|
+
the same ownership check this app already uses on the order show / pay page —
|
|
170
|
+
`session[:user_id]`, Devise's `current_user`, a signed cookie, whatever it is.
|
|
171
|
+
`context[:resource][:reference]` is a claim the payer sent, not proof.
|
|
172
|
+
- **The order is unpaid or paid.** Do not copy `pending` / `expired` / `failed`
|
|
173
|
+
/ `attention` onto it. Those are attempt statuses on `openreceive_payments`. An
|
|
174
|
+
expired invoice does not cancel the order; a later checkout may mint another
|
|
175
|
+
attempt. The engine refuses a new checkout under a reference that already
|
|
176
|
+
settled (409).
|
|
177
|
+
- **Do not associate `OpenReceivePayment`.** No `has_many`, no `belongs_to`, no
|
|
178
|
+
foreign key either direction. `reference` is not unique (many attempts per
|
|
179
|
+
order). Fulfillment is a guarded transition on YOUR order row inside
|
|
180
|
+
`config.on_paid` — `UPDATE … WHERE state = awaiting_payment` (or this app's
|
|
181
|
+
equivalent). Database writes only in the hook; emails, jobs, and broadcasts
|
|
182
|
+
after commit.
|
|
183
|
+
|
|
184
|
+
## If you build your own checkout UI
|
|
185
|
+
|
|
186
|
+
The engine serves JSON only, so the view is yours — but the drop-ins
|
|
187
|
+
(`<openreceive-checkout>`, React's `<Checkout>`) already obey all of this. This
|
|
188
|
+
list is the short form of https://openreceive.org/guides/checkout-ux.md, for a UI
|
|
189
|
+
built on `@openreceive/browser/headless`. Read that before writing components.
|
|
190
|
+
|
|
191
|
+
- `createCheckoutController` is the engine. Do not hand-roll a poll loop.
|
|
192
|
+
- `createCheckoutStatusModel` for the status line. Do not draw a
|
|
193
|
+
Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
|
|
194
|
+
- `resolveWizardSelection` decides whether to ask "which network?". A
|
|
195
|
+
one-network asset starts the swap from the tile. Key `selectedAssetByGroup`
|
|
196
|
+
by group (`USDT`), valued by `pay_in_asset` (`USDT_TRON`).
|
|
197
|
+
- `createMethodGridDisplay` for tiles, including `limitMessage` so an
|
|
198
|
+
unavailable method says the minimum in the payer's currency.
|
|
199
|
+
- `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
|
|
200
|
+
and the bare amount each get a copy row. Render `swap.networkWarning*` as
|
|
201
|
+
the model gives it.
|
|
202
|
+
- `createCheckoutSession` owns mint and swap start. To start swaps, pass its
|
|
203
|
+
`swap` option (`selection`, `prefix`, `fetch`) together. Without it
|
|
204
|
+
`startSwap` reports through `onError`.
|
|
205
|
+
- `createQrSvg` is async. Use `createQrSvgController` so you do not render
|
|
206
|
+
`[object Promise]`.
|
|
207
|
+
- `checkoutLabels` for every payer-facing string. Only write copy it lacks.
|
|
208
|
+
- `stageSwapRefund` then `confirmSwapRefund` — only the second submits.
|
|
209
|
+
Validate with `getSwapRefundFormError`. Treat `409` as a normal outcome.
|
|
210
|
+
- Pass `{ resumable: true }` to `createSwapDisplayModel` when the payer has
|
|
211
|
+
a URL they can come back to, and render `display.refundReturnLabel`.
|
|
212
|
+
Resume helpers (`createGuestCheckoutResume`, `createGuestOrderFetcher`)
|
|
213
|
+
are on `@openreceive/browser`, not `/headless`.
|
|
214
|
+
- A refund replaces the deposit panel. On `refund_required` also drop
|
|
215
|
+
"switch payment method".
|
|
216
|
+
- No "Open wallet" button on desktop.
|
|
217
|
+
- Wallet suggestions: `getPaymentWizardRoutes()` +
|
|
218
|
+
`createWizardRouteDisplays`. Lightning only. Host the icons with
|
|
219
|
+
`asset-base-url`. The registry answers ~37 wallets: pass
|
|
220
|
+
`providerPreviewLimit` and build "show all" from `display.providerCount`,
|
|
221
|
+
or they push the QR off the screen.
|
|
222
|
+
|
|
223
|
+
## More documentation
|
|
224
|
+
|
|
225
|
+
Fetch one when the moment comes. Each is raw markdown, so a plain GET is
|
|
226
|
+
enough; drop the `.md` for the same page a person would read.
|
|
227
|
+
|
|
228
|
+
- https://openreceive.org/guides/authorization.md — before you write `config.authorize`
|
|
229
|
+
- https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one
|
|
230
|
+
- https://openreceive.org/guides/storage.md — the engine tables and the attempt state machine
|
|
231
|
+
- https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots
|
|
232
|
+
- https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
|
|
233
|
+
- https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
|
|
234
|
+
- https://openreceive.org/guides/provider-registry.md — where the packaged icons and pay
|
|
235
|
+
tutorials come from, and how to serve them. The asset rule is the one a custom
|
|
236
|
+
UI is most likely to get wrong; this is the page that owns it, not the summary
|
|
237
|
+
in checkout-ux.md
|
|
238
|
+
- https://openreceive.org/guides/automated-swaps.md — only if `LSC_URI_PRIMARY` is set
|
|
239
|
+
- https://openreceive.org/guides/swap-refunds.md — the refund flow, and the route back to it. Read it before you turn swaps on
|
|
240
|
+
- https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is
|
|
241
|
+
- https://openreceive.org/guides/price-feeds.md — where the fiat→sats rate comes from, and how to replace it
|
|
242
|
+
- https://openreceive.org/guides/host-testing.md — testing your three hooks without a live wallet or provider
|
|
243
|
+
- https://openreceive.org/guides/rate-limiting.md — before a public shop goes live
|
|
244
|
+
- https://openreceive.org/guides/security.md and https://openreceive.org/guides/deploying.md — before this goes anywhere real
|
|
245
|
+
- https://openreceive.org/guides/api-reference.md — every route, option and error code
|
|
246
|
+
- https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the mounted engine's routes with your own
|
|
247
|
+
- https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
|
|
248
|
+
- https://openreceive.org/guides.md — the index, if what you need is not above
|
|
249
|
+
|
|
250
|
+
Questions, or a problem with the library itself:
|
|
251
|
+
https://openreceive.org/contact
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## The quickstart, in full
|
|
256
|
+
|
|
257
|
+
Inlined verbatim so this file needs no network access — follow it once Step 0
|
|
258
|
+
passes. The page it comes from is https://openreceive.org/guides/quickstart-rails.
|
|
259
|
+
|
|
260
|
+
## Rails quickstart
|
|
261
|
+
|
|
262
|
+
Requires Ruby ≥ 3.2.
|
|
263
|
+
|
|
264
|
+
Add the Rails engine gem to your `Gemfile`:
|
|
265
|
+
|
|
266
|
+
```ruby
|
|
267
|
+
gem "openreceive-rails"
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
That is the whole install: `openreceive-rails` depends on `openreceive`,
|
|
271
|
+
`openreceive-server` and `nwc-ruby`, so the default wallet client — built from
|
|
272
|
+
`NWC_URI` — works with nothing else added. Hosts that bring their own NWC
|
|
273
|
+
client set `config.nwc_client` instead.
|
|
274
|
+
|
|
275
|
+
One native prerequisite: `nwc-ruby`'s `rbsecp256k1` builds libsecp256k1 from
|
|
276
|
+
source, so minimal images (`ruby:3.3-slim`, fresh Docker builds) need the
|
|
277
|
+
autotools or `bundle install` dies at `autoreconf: not found`. Before
|
|
278
|
+
bundling:
|
|
279
|
+
|
|
280
|
+
```sh
|
|
281
|
+
apt-get install -y autoconf automake libtool build-essential pkg-config
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Full Ruby images and typical developer machines already have these.
|
|
285
|
+
|
|
286
|
+
Then run:
|
|
287
|
+
|
|
288
|
+
```sh
|
|
289
|
+
bin/rails generate openreceive:install
|
|
290
|
+
bin/rails db:migrate
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
`openreceive:install` emits one migration for both engine tables, the
|
|
294
|
+
initializer, and the engine mount. The migration adapts to the app's configured
|
|
295
|
+
database adapter — PostgreSQL, SQLite, and MySQL (`mysql2`/`trilogy`) are
|
|
296
|
+
supported.
|
|
297
|
+
→ [openreceive:install](https://openreceive.org/guides/api-reference.md#openreceiveinstall)
|
|
298
|
+
|
|
299
|
+
The generator emits three things:
|
|
300
|
+
|
|
301
|
+
- `db/migrate/*_create_openreceive_tables.rb` — one migration creating both
|
|
302
|
+
engine tables (`openreceive_payments` and `openreceive_meta`);
|
|
303
|
+
- a simplified `config/initializers/openreceive.rb`;
|
|
304
|
+
- the `OpenReceive::Engine` route mount at `/openreceive`.
|
|
305
|
+
|
|
306
|
+
The `OpenReceivePayment` model is engine-owned — no model file is generated.
|
|
307
|
+
The engine owns the table's commit locking, write-once settlement, and
|
|
308
|
+
reconciliation state machine. `reference` is indexed but not unique (a
|
|
309
|
+
reference may have many historical attempts); `payment_hash` is globally unique.
|
|
310
|
+
|
|
311
|
+
#### Fulfill exactly once
|
|
312
|
+
|
|
313
|
+
Within OpenReceive's own settlement paths, `on_paid` runs at most once per
|
|
314
|
+
reference: a second payment to a second invoice is recorded with
|
|
315
|
+
`status_reason = "duplicate_settlement"` and never fulfills again.
|
|
316
|
+
|
|
317
|
+
The one thing you own: **if anything other than OpenReceive can also fulfill
|
|
318
|
+
an order** — an admin action, a second payment processor, a replayed job —
|
|
319
|
+
those paths race each other, and `on_paid` must be idempotent. The generated
|
|
320
|
+
initializer spells this out and shows the guarded transition:
|
|
321
|
+
|
|
322
|
+
```ruby
|
|
323
|
+
config.on_paid = lambda do |settlement|
|
|
324
|
+
claimed = Order
|
|
325
|
+
.where(id: settlement.reference, state: "awaiting_payment")
|
|
326
|
+
.update_all(state: "paid", paid_at: Time.at(settlement.paid_at).utc)
|
|
327
|
+
next if claimed.zero? # someone else already fulfilled it
|
|
328
|
+
|
|
329
|
+
# FulfillOrder — like Order — is your own application code: ship the goods,
|
|
330
|
+
# enqueue the confirmation email. OpenReceive provides neither.
|
|
331
|
+
FulfillOrder.call(Order.find(settlement.reference), payment_hash: settlement.payment_hash)
|
|
332
|
+
end
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Delivery is at-least-once: `on_paid` runs inside the settlement transaction,
|
|
336
|
+
and a raise rolls it back for the next pass to retry. Keep it to database
|
|
337
|
+
writes on the order — an email or webhook sent from here would survive the
|
|
338
|
+
rollback and go out again. The `state: "paid"` transition above is the flag;
|
|
339
|
+
let your own job drain it after commit.
|
|
340
|
+
|
|
341
|
+
**`update_all` fires no Active Record callbacks.** That is the point — it is one
|
|
342
|
+
conditional `UPDATE`, so the claim is atomic and there is no model code between
|
|
343
|
+
the check and the write. It also means there is no `after_commit` to hang a
|
|
344
|
+
post-commit side effect on, which is fine for a background job draining the flag
|
|
345
|
+
and useless for a page that wants to know *now*. If you push settlement over
|
|
346
|
+
Action Cable, or your model owns the transition through callbacks, take a row
|
|
347
|
+
lock for the duration instead:
|
|
348
|
+
|
|
349
|
+
```ruby
|
|
350
|
+
config.on_paid = lambda do |settlement|
|
|
351
|
+
order = Order.lock.find_by(id: settlement.reference) # SELECT … FOR UPDATE
|
|
352
|
+
next unless order && order.state == "awaiting_payment"
|
|
353
|
+
order.update!(state: "paid", paid_at: Time.at(settlement.paid_at).utc) # callbacks fire
|
|
354
|
+
end
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Both shapes are idempotent, and both are correct. They differ only in whether
|
|
358
|
+
your model layer gets to run: `update_all` skips it and is the right default;
|
|
359
|
+
the row lock holds the row for the duration of the block and is what you want
|
|
360
|
+
when the transition has to go through your model. The generated fulfillment note
|
|
361
|
+
says the same thing — if your fulfillment is a read-modify-write that cannot be
|
|
362
|
+
expressed as one conditional `UPDATE`, take the lock.
|
|
363
|
+
|
|
364
|
+
Either way the rule above still holds: whatever the callback does must be
|
|
365
|
+
database writes on the order. `after_commit` on the settlement transaction runs
|
|
366
|
+
after OpenReceive's own commit, so an email enqueued there is as safe as one
|
|
367
|
+
enqueued from a job draining the flag — and an email sent *inline* from
|
|
368
|
+
`on_paid` is not, in either shape.
|
|
369
|
+
|
|
370
|
+
A runnable illustration of this boundary — not a template to copy models from —
|
|
371
|
+
is Buy a Button
|
|
372
|
+
(`examples/buttons/server/rails`).
|
|
373
|
+
It has products, visitors, and orders, with the three hooks as the only bridge.
|
|
374
|
+
Map that shape onto the models in THIS app.
|
|
375
|
+
|
|
376
|
+
Supply the receive-only wallet connection as `ENV["NWC_URI"]`. Never put it in
|
|
377
|
+
browser code, logs, or assets. Your application refuses to start when the code
|
|
378
|
+
advertises spend methods such as `pay_invoice`; the explicit override is
|
|
379
|
+
`config.allow_spend_capable_wallet = true` or
|
|
380
|
+
`OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true` ([Security](https://openreceive.org/guides/security.md)).
|
|
381
|
+
|
|
382
|
+
OpenReceive reads `ENV`; Rails does not load a `.env` file on its own.
|
|
383
|
+
`dotenv-rails`, an exported shell environment, or your production secret
|
|
384
|
+
manager has to put the values there first.
|
|
385
|
+
→ [Environment variables](https://openreceive.org/guides/environment-variables.md).
|
|
386
|
+
|
|
387
|
+
### Configure the host hooks
|
|
388
|
+
|
|
389
|
+
The initializer needs three things: authorization, the trusted price, and
|
|
390
|
+
fulfillment. All three receive the `reference` — a string you choose, and the
|
|
391
|
+
fulfillment identity: your order id, one per thing you fulfill, created before
|
|
392
|
+
checkout, kept across retries, never reused. OpenReceive never looks inside
|
|
393
|
+
it, but `on_paid` runs once per reference, a new checkout under a reference
|
|
394
|
+
that already settled is refused with 409, and a fresh id per page load lets
|
|
395
|
+
one order be paid twice.
|
|
396
|
+
|
|
397
|
+
```ruby
|
|
398
|
+
OpenReceive.configure do |config|
|
|
399
|
+
# `Order` throughout is YOUR model — it could be named anything. OpenReceive
|
|
400
|
+
# never sees it or touches its table; these hooks are the only bridge
|
|
401
|
+
# between the engine and your data.
|
|
402
|
+
#
|
|
403
|
+
# Your policy, called before every checkout/payment/swap request. `context`
|
|
404
|
+
# is a Hash with three symbol keys:
|
|
405
|
+
# context[:action] — which route: "checkout.prepare", "checkout.create",
|
|
406
|
+
# "payment.check", "swap.quote", "swap.create",
|
|
407
|
+
# "swap.read", or "swap.refund"
|
|
408
|
+
# context[:request] — the ActionDispatch::Request; read your session,
|
|
409
|
+
# cookies, or headers from it, as in a controller
|
|
410
|
+
# context[:resource] — { reference:, payment_hash: } copied from the
|
|
411
|
+
# payer's JSON body. It names an order; it does not
|
|
412
|
+
# prove this caller owns it.
|
|
413
|
+
# Return true to allow, false for a 403. Here: only the signed-in customer
|
|
414
|
+
# who placed the order may act on it.
|
|
415
|
+
config.authorize = lambda do |context|
|
|
416
|
+
order = Order.find_by(id: context[:resource][:reference])
|
|
417
|
+
order && order.user_id == context[:request].session[:user_id]
|
|
418
|
+
end
|
|
419
|
+
|
|
420
|
+
# The price for a reference — here, your order id — from your own data;
|
|
421
|
+
# nil when there is nothing to pay for (a 404). `value` is a decimal STRING
|
|
422
|
+
# from the order row, never a float and never a request param. `description`
|
|
423
|
+
# is what the payer is buying, in your own words.
|
|
424
|
+
config.amount_for = lambda do |reference|
|
|
425
|
+
order = Order.find_by(id: reference)
|
|
426
|
+
order && { currency: "USD", value: order.total.to_s,
|
|
427
|
+
description: "#{order.line_items.size} items" }
|
|
428
|
+
end
|
|
429
|
+
|
|
430
|
+
# Runs inside the settlement transaction, only for the order's first settled
|
|
431
|
+
# attempt. The WHERE clause is the lock: a second fulfillment path of yours
|
|
432
|
+
# (admin action, replayed job) updates zero rows and does nothing. Plain
|
|
433
|
+
# ActiveRecord, because the engine WRAPS this block in the transaction.
|
|
434
|
+
# (The JS engine instead hands onPaid a `query` handle, since nothing wraps
|
|
435
|
+
# it there; that is the one shape difference between the two stacks.)
|
|
436
|
+
config.on_paid = lambda do |settlement|
|
|
437
|
+
claimed = Order
|
|
438
|
+
.where(id: settlement.reference, state: "awaiting_payment")
|
|
439
|
+
.update_all(state: "paid", paid_at: Time.at(settlement.paid_at).utc)
|
|
440
|
+
next if claimed.zero?
|
|
441
|
+
end
|
|
442
|
+
end
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
`OpenReceive.configure` sets the three host hooks; `on_paid` runs inside the
|
|
446
|
+
settlement transaction, only for the first settled attempt for a reference.
|
|
447
|
+
→ [OpenReceive.configure](https://openreceive.org/guides/api-reference.md#openreceiveconfigure)
|
|
448
|
+
|
|
449
|
+
The engine inherits your application's `protect_from_forgery`. Keep
|
|
450
|
+
`csrf_meta_tags` in the layout that renders the checkout; the checkout client
|
|
451
|
+
sends `X-CSRF-Token` from it automatically.
|
|
452
|
+
|
|
453
|
+
The generated initializer ships
|
|
454
|
+
`config.on_paid = OpenReceive::LOGGING_ON_PAID` — a placeholder that only logs
|
|
455
|
+
the settlement and fulfills nothing. Replace it with your real fulfillment (as
|
|
456
|
+
above); the engine warns every time your application boots while the
|
|
457
|
+
placeholder is still configured, because orders would otherwise be recorded as settled without ever
|
|
458
|
+
being fulfilled.
|
|
459
|
+
|
|
460
|
+
The amount always comes from your own order record; payer-supplied amounts are
|
|
461
|
+
rejected. Advanced hooks (`resolve_checkout`, `on_checkout_created`) remain as
|
|
462
|
+
overrides for custom-repository applications and are not part of the quickstart.
|
|
463
|
+
|
|
464
|
+
For public web shops, opt into the per-IP invoice cap with
|
|
465
|
+
`config.rate_limiting = true`; leave it off (the default) when many payers
|
|
466
|
+
share one IP. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md#rails)
|
|
467
|
+
|
|
468
|
+
In production the engine builds the wallet client — and runs its receive-only
|
|
469
|
+
preflight — eagerly when your application boots, so a missing `NWC_URI`, a
|
|
470
|
+
dead relay, or a spend-capable wallet stops the deploy instead of surfacing as
|
|
471
|
+
customer-facing 500s on the first checkout. Outside production (tests,
|
|
472
|
+
consoles) the client is built lazily so no live wallet is needed.
|
|
473
|
+
|
|
474
|
+
### Render the checkout
|
|
475
|
+
|
|
476
|
+
The engine serves JSON checkout routes only — rendering is your view. Any
|
|
477
|
+
OpenReceive frontend package works against the `/openreceive` mount; the
|
|
478
|
+
smallest is the custom element (its default `prefix` is already
|
|
479
|
+
`/openreceive`, and the package ships a self-contained `styles.css` a plain
|
|
480
|
+
stylesheet link can serve):
|
|
481
|
+
|
|
482
|
+
```erb
|
|
483
|
+
<%# app/views/orders/pay.html.erb %>
|
|
484
|
+
<openreceive-checkout reference="<%= @order.id %>"></openreceive-checkout>
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
```js
|
|
488
|
+
// In your JS bundle (importmap/esbuild/webpacker):
|
|
489
|
+
import { defineElements } from "@openreceive/elements";
|
|
490
|
+
import "@openreceive/elements/styles.css"; // or link the compiled styles.css
|
|
491
|
+
|
|
492
|
+
// Registers the <openreceive-checkout> tag with the browser. Without this,
|
|
493
|
+
// the tag in the ERB above is unknown markup and renders as nothing; with it,
|
|
494
|
+
// the element wakes up wherever the tag appears. Call once per page — order
|
|
495
|
+
// relative to the markup does not matter.
|
|
496
|
+
defineElements();
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
Bundling with esbuild (jsbundling-rails)? Two things:
|
|
500
|
+
|
|
501
|
+
1. Build ESM and load it as a module. esbuild's default IIFE output evaluates
|
|
502
|
+
a dependency's Node fallback in the browser and throws
|
|
503
|
+
`ReferenceError: __filename is not defined`:
|
|
504
|
+
|
|
505
|
+
```sh
|
|
506
|
+
esbuild app/javascript/application.js --bundle --format=esm --outdir=app/assets/builds
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
```erb
|
|
510
|
+
<%= javascript_include_tag "application", type: "module" %>
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
2. Serve the payment-method icons. They are files shipped in
|
|
514
|
+
`@openreceive/browser` and `@openreceive/provider-data` — not in
|
|
515
|
+
`@openreceive/elements` — and only Vite-style bundlers resolve them from
|
|
516
|
+
the import. Merge both packages' `dist/assets` trees into
|
|
517
|
+
`public/openreceive-assets/assets/` and set
|
|
518
|
+
`asset-base-url="/openreceive-assets"` on the element
|
|
519
|
+
([Provider registry](https://openreceive.org/guides/provider-registry.md#assets-are-files-your-host-serves)).
|
|
520
|
+
|
|
521
|
+
The element creates the checkout for `reference`, then renders and polls
|
|
522
|
+
itself. React/Vue/Svelte/Angular apps use the matching wrapper package
|
|
523
|
+
instead — same props and defaults ([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)).
|
|
524
|
+
Build a custom checkout only if this app cannot use a drop-in; then
|
|
525
|
+
`@openreceive/browser/headless` is the API
|
|
526
|
+
([Headless checkout](https://openreceive.org/guides/headless-checkout.md)).
|
|
527
|
+
|
|
528
|
+
### Reconciliation
|
|
529
|
+
|
|
530
|
+
Settlement runs on the request path. You do not need a cron job. Disable or
|
|
531
|
+
tune it with `config.opportunistic_reconcile` (`false`, or
|
|
532
|
+
`{ min_interval_seconds: … }`).
|
|
533
|
+
|
|
534
|
+
Optionally, run one worker so settlement does not wait for the next page
|
|
535
|
+
load:
|
|
536
|
+
|
|
537
|
+
```sh
|
|
538
|
+
bin/rails openreceive:notifications
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
→ [rake openreceive:notifications](https://openreceive.org/guides/api-reference.md#rake-openreceivenotifications)
|
|
542
|
+
|
|
543
|
+
`OpenReceive.reconcile!` and `bin/rails openreceive:reconcile` are one-shot
|
|
544
|
+
primitives if you want to drive a pass yourself.
|
|
545
|
+
→ [OpenReceive.reconcile!](https://openreceive.org/guides/api-reference.md#openreceivereconcile)
|
|
546
|
+
|
|
547
|
+
### Swap secrets
|
|
548
|
+
|
|
549
|
+
The Ruby server recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP` using the
|
|
550
|
+
shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors: setting either one
|
|
551
|
+
auto-builds the matching provider, so an app that wants swaps only supplies the
|
|
552
|
+
connection strings ([Environment variables](https://openreceive.org/guides/environment-variables.md)).
|
|
553
|
+
`config.swap_providers` is the override knob — pass your own adapters to
|
|
554
|
+
replace the auto-built set, or an empty array to disable swaps.
|
|
555
|
+
|
|
556
|
+
One `openreceive_payments` row holds at most one provider order in its
|
|
557
|
+
server-only `swap_data`. The engine filters `swap_data` from Active Record
|
|
558
|
+
inspection and ordinary serialization. Do not explicitly serialize it, log it,
|
|
559
|
+
or return it from your own API; it may contain a provider credential.
|
|
560
|
+
|
|
561
|
+
**Setting either connection string commits you to refunds.** A swap deposit can
|
|
562
|
+
arrive short or late, which leaves it `refund_required` at the provider with
|
|
563
|
+
only your UI able to claim it — and the payer claims it on a second visit,
|
|
564
|
+
after leaving your page for an address in another wallet. That needs a
|
|
565
|
+
per-order URL your app serves, a route that restores the order behind it, and
|
|
566
|
+
something that restores the ATTEMPT, since `/checkouts/prepare` returns none.
|
|
567
|
+
[Swap refunds](https://openreceive.org/guides/swap-refunds.md) is the whole of it; read it before you set
|
|
568
|
+
`LSC_URI_PRIMARY`.
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: openreceive
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.3.
|
|
4
|
+
version: 0.3.3
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- OpenReceive
|
|
@@ -40,6 +40,10 @@ files:
|
|
|
40
40
|
- lib/openreceive/rates.rb
|
|
41
41
|
- lib/openreceive/swap_address.rb
|
|
42
42
|
- lib/openreceive/version.rb
|
|
43
|
+
- skills/debug-openreceive-payment/SKILL.md
|
|
44
|
+
- skills/integrate-openreceive/SKILL.md
|
|
45
|
+
- skills/integrate-openreceive/references/node.md
|
|
46
|
+
- skills/integrate-openreceive/references/rails.md
|
|
43
47
|
homepage: https://openreceive.org
|
|
44
48
|
licenses:
|
|
45
49
|
- MIT
|