How any store can connect to PayAssist through one standard protocol

The labels

Payment systems attract confident claims. This book marks every important statement with one of these labels so you always know how much weight it can carry. Press Legend at any time to see them again.

The colors

Seven actors appear again and again, and each keeps one color in every diagram and in the text: the buyer in a browser, the store and its server, PayAssist's API and core, an account node that holds one provider account's credentials, the central Connect service for Stripe Connect, the payment provider such as Stripe or Square, and the buyer's card issuer, which is the bank that issued the card. Green, amber and red only ever mean good, uncertain and bad outcomes.

The moving diagrams

Sequence diagrams show messages moving between actors over time, top to bottom. Each one has the same controls: Play, Pause, Next, Back and Reset, plus Show all to see every step at once. Click a diagram and use the arrow keys if you prefer the keyboard. Every diagram also has a plain list of its steps under "Read every step as text". Try this small one now. It is the most important idea in the whole book.

The fix for that double charge is one header and one database table. Chapter 3 explains it, and most of the book is about doing that kind of thing everywhere money or orders change.

The route through the book

What this book promises and what it does not

It explains the major ways a payment connection succeeds and fails, with the rule that handles each one. It does not claim to list every possible failure. Payment systems sit on banks, card networks, browsers, hosting companies and people, and each of those can surprise you. Appendix G lists the areas this book deliberately leaves out, such as tax, subscriptions, payouts and fraud scoring.

What the owner asked for

On 18 October 2026 the owner asked for a fixed standard, mostly inspired by Stripe, that lets WordPress, Next.js and Node with React stores connect through standard protocols and flows. Their focus was the core logic of a system that stays flexible, maintainable and scalable Owner-confirmed. A few minutes later they added that they wanted the best design even if it meant replacing parts of the current setup. Those two messages, paraphrased here, are the whole brief. They contain no traffic numbers, no compliance level and no deadline, which matters later when this book separates real requirements from numbers that agents invented.

What "like Stripe" means, and what it does not

Stripe is famous among developers for its integration contract, not for any single technology. You can describe that contract in six parts, and Figure 1.2 stacks them in the order a request meets them.

"Like Stripe" therefore does not mean copying Stripe's internal systems, and it cannot mean offering everything Stripe offers. PayAssist differs from Stripe in two ways that shape every chapter:

• PayAssist routes; it does not process cards itself. Each checkout is sent to one of many provider accounts, such as a Stripe, Square or PayPal account. Each standard provider account has its own account node, a small server with its own IP address and that account's credentials; Stripe Connect calls come from a central Connect service instead. Card numbers go from the buyer's browser straight to the provider.
• Providers differ. A Stripe account can do things a Square account cannot, and the reverse. Any feature that depends on the provider, such as styling the card fields or saving a card for next time, works only as far as each provider allows.

What stays and what changes

Who the protocol is for

The protocol's users are developers: a store owner who writes code, an agency that builds shops, or PayAssist's own plugin team. Treat the protocol as a product with its own documentation, test mode, error messages and change log. A developer should be able to build a correct integration from the documentation alone, without asking PayAssist how a field behaves. That standard is higher than "the plugin works", and it is the reason Part II spends so long on edge cases.

The approval conversation

When a buyer clicks Pay, the provider sends an authorization request through the card network to the card issuer, which is the buyer's bank. The issuer checks the balance and its fraud signals and answers yes or no. That round trip usually takes a second or two. A yes reserves the money on the buyer's card. A capture then turns the reservation into a real charge, either immediately or later, for example when a shop ships a backordered item.

A no is called a decline. Some declines are final, such as a stolen card. Others invite a retry, such as insufficient funds after payday. Either way, a decline is a definite answer. Chapter 3 shows why "no answer at all" is a different case, one that must never be treated like a decline.

The bank's identity check: 3-D Secure

Sometimes the issuer wants proof that the real cardholder is paying. 3-D Secure, usually shortened to 3DS, pauses the payment and shows the buyer a check from their bank, such as approving in a banking app. In the European Economic Area the law requires this for most online card payments; the rule is called strong customer authentication, from Article 97 of the EU's second Payment Services Directive. The issuer decides whether to ask; neither the store nor PayAssist can force a payment through without it S53 S56. Passing 3DS usually shifts fraud liability to the issuer, but Stripe's own documentation says that shift is not guaranteed.

For a payment system, 3DS matters because it creates a long pause in the middle of a payment. The buyer can close the tab, lose signal on a train, or take ten minutes to find their phone. During that pause the payment is neither paid nor failed.

The money's journey, and how it comes back

A refund sends money back at the merchant's request. A dispute is the buyer asking their bank to take it back, which the card network then decides with deadlines for evidence. Neither one changes the fact that the original payment succeeded. Good systems record them as separate objects with their own lifecycle, which is exactly what Chapter 6 does.

Where PayAssist fits

PayAssist's job is to pick which provider account takes each payment and to keep the official record of what happened. Today that works like this Today:

• Backend, the PayAssist server that acts as referee, chooses an account for each checkout based on availability, currency, limits and current volume.
• Each standard provider account has its own account node with a dedicated IP address. The node talks to that provider using that account's keys.
• Stripe Connect is a separate path. A central Connect service holds the platform key and makes the Stripe calls; the existing node proxy only relays the checkout. The owner requires the two Stripe paths to stay separate, with no automatic fallback from one to the other Owner-confirmed.
• The buyer types the card into the provider's own fields. PayAssist and the store never see the card number. That is a locked principle of the system Owner-confirmed.

This book's proposal keeps all of that. What changes is how a store talks to PayAssist: how it asks for a checkout, proves who it is, and learns what happened.

Chapter 0's first moving diagram showed what happens when a program treats silence as failure: it sends the charge again and the buyer pays twice. The opposite mistake is just as bad. A program that treats silence as success ships goods that were never paid for. The only honest answer to silence is "I don't know yet, and I will find out."

Tool 1: name the intention, not the attempt to send it

An idempotency key is a unique name for one intended action, such as "create the checkout for order 1042, revision 1". The caller makes it once, stores it, and sends it with every retry of that action. The server remembers each key with its result. When the same key arrives again, the server returns the saved result instead of doing the work twice. Think of a numbered ticket at a deli counter: if you hand over ticket 47 twice, the kitchen does not make two sandwiches.

Rules are numbered across the whole book, so this chapter jumps between them; Appendix E lists all eighteen.

Notice "in the same database transaction". If the server saved the charge but crashed before saving the key, the retry would find no key and charge again. Storing them together makes "did it happen" and "what did we answer" a single fact. Chapter 7 turns this into a full protocol with status codes, and its lab lets you try to break it.

Tool 2: assume a crash between any two lines

Tool 3: write the news in the same breath as the change

Once a payment succeeds, several parties need to hear about it: the store, the dashboard, accounting. The tempting code updates the database and then sends a message. That is two writes to two systems, and a crash between them leaves them disagreeing forever.

This pair is the honest version of "exactly once". Networks cannot promise that a message arrives exactly once; a system can promise that each message's effect happens once, by delivering at least once and deduplicating on arrival. When someone claims exactly-once delivery, ask where the deduplication happens.

Tool 4: when nobody answers, go and ask

Some unknowns never resolve themselves. The provider's webhook may be lost, a node may restart, a browser may close. A reconciler is a scheduled job that lists everything still unresolved and asks the source of truth, usually the provider, what really happened. It runs often at first and less often later, and it raises an alarm when something stays unresolved too long.

One more trap: clocks

It is tempting to sort events by their timestamps. Different machines' clocks drift by milliseconds or seconds, and some systems record time to the second only. Stripe's documentation warns that its event timestamps have one-second resolution and must not be used to order events S19. The fix is a version number on each object that goes up by one with every change. Chapter 10 uses it.

Names are public, secrets are not

A website login has a username, which other people may know, and a password, which only you know. API keys follow the same split. A publishable key is like a username: it identifies the store and is safe inside a web page. A secret key is like a password: whoever holds it can act as the store, so it lives only on the store's server. A restricted key is a secret key with a list of allowed actions, such as "create checkout sessions and read events, nothing else". Stripe now recommends restricted keys over all-powerful secret keys for new integrations S29.

A key travels in the Authorization header of an HTTPS request. HTTPS encrypts the connection and proves the server's identity, so the key cannot be read on the way. The server looks up which store the key belongs to and in which mode, test or live. That lookup, and nothing in the request body, decides whose data the request may touch.

A signature proves who wrote a message and that nobody changed it

An HMAC signature guarantees two things: the message came from someone who holds the secret, and the bytes are exactly what that party signed. It guarantees nothing about secrecy. PayAssist's current checkout token is a good example Today: it is signed, so nobody can change the amount, but it is not encrypted, and its claims include a snapshot of the customer's shipping details that anyone holding the URL can decode. The code comments acknowledge this. A design that treats "signed" as "private" will leak data.

Two details decide whether signature checking works:

• Check the exact bytes that arrived. If a program parses the JSON and turns it back into text before checking, the spacing or key order can change, and a genuine message fails. Worse, a program that checks the parsed version can be fooled by two messages that parse the same way. Chapter 10's lab shows the first problem live.
• Compare in constant time. A normal string comparison stops at the first different character, so an attacker can measure response times to guess a valid signature one character at a time. Signature libraries compare every byte regardless.

Replays: a genuine message sent again

An attacker who records a genuine signed message can send it again later. The signature still matches, because the message is unchanged. Two defenses work together. A timestamp inside the signed content lets the receiver reject anything older than a few minutes; Stripe's libraries default to five S20. Within those minutes, the receiver's record of event ids already applied (rule R8) turns a replay into a harmless duplicate. Neither defense works alone.

Short-lived capabilities for the browser

The buyer's browser needs to start a payment for one checkout, but it must never hold a key that can act for the whole store. The answer is a capability token: an unguessable string that grants a few actions on one object for a short time, such as "show and pay checkout cs_test_8Lk until 15:30". Stripe calls its version a client_secret. If it leaks, the damage is limited to finishing that one checkout, which the buyer was allowed to do anyway.

Tenants: one store must never see another

PayAssist serves many stores from one system. Each store is a tenant, and the most important security property is that no request ever reads or changes another tenant's data. The simple, strict way: the key decides the tenant and the mode, and every database query includes both, so an id copied from another store's data finds nothing. The scenario "Cross-store access attempt" in Chapter 20 steps through it, including why the answer should be 404 rather than 403: a 403 would confirm that the other store's object exists.

How today's link compares

The current design is not broken. It is a reasonable private link between one plugin and one backend. It stops scaling when there are many kinds of clients, many endpoints per store and keys that need different permissions. Chapter 8 designs the full key lifecycle: creation, scopes, storage, rotation and what to do when a key leaks.

Origins are the walls

Browsers group pages by origin: the scheme, host and port together, such as https://larkspur-tea.example. The same-origin policy lets a page read and change everything from its own origin and almost nothing from another. An iframe places a page from another origin inside your page like a window in a wall: you can see it, but your scripts cannot reach through to read what is typed there.

How the walls let messages through

Frames on different origins talk with postMessage: one window posts a message to another, and the receiver gets an event saying which origin sent it. Two rules from the browser makers make this safe S38. The sender names the exact origin it expects to receive the message instead of "*", which means anyone. The receiver checks event.origin and event.source before trusting anything in the message.

Today PayAssist's node pages post their status messages with the target "*", and the WooCommerce modal on the receiving side checks the frame's window, its exact origin and a source marker before acting Today. The messages carry only display hints such as "ready", "resize" and "payment status", and the order is never marked paid from them. An earlier version of the plugin's receipt page skipped the origin check; the staging source fixed it and has tests for forged messages.

A MessageChannel improves on this. After one checked handshake the page hands the frame a private port, and later messages travel only through that port, where other pages cannot listen or inject S39. MDN's own example sends the port with "*", which the handshake in Chapter 9 deliberately does not copy.

Who may put your page in a frame

A page decides who may embed it with the frame-ancestors rule of its Content Security Policy, sent as an HTTP header S41. A payment page should list only the stores allowed to show it, so a hostile site cannot wrap it in a deceptive layout. Today the node's /pay page sends frame-ancestors *, a deliberate choice in the code because one node serves many stores Today. A per-session list of allowed store origins is one of the proposal's browser changes. The referrer header cannot replace it: the embedding page can suppress or change what the frame sees there, so identity must come from a signed capability S42 S43.

What the card-data rules say

The card industry's security standard, PCI DSS, applies to anyone who stores, processes or transmits card numbers, and also to service providers who could affect their security without touching them S10. Merchants prove compliance with forms called self-assessment questionnaires. The lightest one for online shops, SAQ A, applies when every element of the payment form comes from a compliant third-party provider.

The danger in Figure 5.1's last button is the reason the 2025 rule exists. The scenario below plays it out. The defenses all live on the store page or in the choice of display mode, which is why Chapter 9 keeps a full-page hosted redirect as the safest option for stores that cannot control their own scripts.

Cookies, Safari and the third-party question

A payment frame served from a node's domain is cross-origin to the store page and, because the two have different registrable domains, cross-site as well. Cookie rules care about the second: a frame's cookies are third-party when its site differs from the site in the address bar S98. Two subdomains of one store would be cross-origin but same-site. Safari has blocked third-party cookies by default since version 13.1 in March 2020, and it gives third-party frames separate, temporary storage S48 S49. A frame can ask for its cookies with the Storage Access API, but only after the buyer clicks inside it S51. Chrome, by contrast, announced in 2025 that it will keep letting users choose and will not remove third-party cookies by default S52.

The practical rule is simple: a payment frame must work with no cookies and no stored state of its own. It can receive everything it needs in a short-lived capability and talk to its servers directly. That does not make the whole checkout immune to tracking prevention. Provider fraud and device checks inside nested provider frames can still lose signals, wallets have their own rules, and return URLs can lose link decorations, so each provider needs real tests on Safari.

Wallets need permission at every level

Apple Pay and Google Pay inside frames need the allow="payment" attribute on every iframe in the chain, from the store page down to the provider's frame S47. Safari has allowed Apple Pay in third-party iframes this way since version 17.0 S46; older Safari versions cannot be assumed. A nested design has one more link to forget than a single provider frame, and testing must cover it.

Why a session sits on top of the payment

Stripe offers two styles: a low-level PaymentIntent that the developer drives step by step, and a higher-level Checkout Session that wraps one. The arena proposals from Claude Opus 5.5 and Codex GPT-6.1-Sol both made the session the default for PayAssist, with good reason Proposed. The store owns the cart and the return URL. PayAssist owns the decision about which account processes the money. A session gives the store one stable object while PayAssist manages the provider objects underneath it, including a second attempt on another account once the first can no longer take money. Today's code already has the pieces: a durable payment_requests table and a separate payment_attempts table whose id travels inside the signed checkout token Today. The proposal turns them into documented public objects instead of renaming them in a diagram.

The payment's states

A payment moves through five states. Stripe's PaymentIntent has a similar set S24, and the arena proposals kept the same shape. The important design choices are which moves are allowed and which are refused. Drive it yourself below: press the events in any order and watch which ones the rules reject.

Three more rules finish the picture. The explorer enforces R2, R3 and R6; R5 lives in provider calls the explorer does not show.

A decline is an answer; silence is not

The arena's summaries described a "smart" feature: when account A declines or fails, retry automatically on account B under the same session. The underlying designs did not agree with that summary Corrected. Codex's design required an unresolved attempt to block any reroute and allowed a new attempt only after a definite decline; Astra's froze uncertain requests. That difference decides whether a buyer can be charged twice. A decline is a definite "no" for one card, but it does not always retire the provider object. A declined Stripe PaymentIntent goes back to requires_payment_method, and anyone holding its client secret, such as a forgotten second tab, can still confirm it with another card S24. A new object created beside it would leave two that can charge. So after a decline the next card goes to the same object, or the old one is canceled and the provider confirms it before a new one exists (rule R3). A timeout is worse: silence might hide a successful charge on account A.

Even after a definite decline, sending the buyer's card to a different account is a policy question, not a technical shortcut. Card networks publish rules and fees for re-attempting declined transactions, fraud systems may treat rapid retries across merchants as card testing, and some declines mean "do not try again". This book recommends This book: a new attempt after a decline happens only when the buyer acts again, such as entering another card; which account it may use is decided by the routing policy with those rules in view; and an unknown outcome blocks every new attempt until reconciliation settles it.

Saved cards wait

Saving a card for next time sounds simple, but a saved card belongs to the provider account that saved it. A card saved on Stripe account A cannot be charged through Square account B. Inside one Stripe Connect platform, a card saved on the platform can be cloned to connected accounts for direct charges S32. Network tokens are tied to one card and one merchant S34. Moving stored cards between processors is a gated processor-to-processor migration S35, and Square and PayPal scope saved cards their own ways S36 S37. Saved cards therefore pin a buyer to an account, which fights the router. Claude Opus 5.5's arena design left them out of version 1 and this book agrees This book; Codex's design included a setup resource but not in its first slice. If a paying merchant needs saved cards, design them per provider, starting with Stripe Connect's cloning model.

Anatomy of one request

Create a checkout sessionProposedIllustrative

POST /v1/checkout_sessions HTTP/1.1                         ① method and path: create one session
Host: api.payassist.example
Authorization: Bearer pa_rk_test_51Ex…AMPLE                  ② restricted key: store + mode + scopes
Idempotency-Key: wc-1042-r1-s1                               ③ names this intention (rule R1)
PayAssist-Version: 2026-11-01                               ④ the contract version the caller expects
Content-Type: application/json

{
  "amount": 3850,                       ⑤ integer minor units: 3850 cents = $38.50
  "currency": "usd",
  "order_reference": "1042",            ⑥ the store's own order id
  "order_revision": 1,                        bumps when the cart changes (rule R2)
  "ui_mode": "modal",                     ⑦ hosted, modal or embedded
  "return_url": "https://larkspur-tea.example/checkout/order-received/1042",
  "metadata": { "woo_order_key": "wc_order_EXAMPLE" }
}

HTTP/1.1 201 Created                                             ⑧ created; a replay says so in a header
Request-Id: req_7Hc…
{
  "id": "cs_test_8Lk…", "object": "checkout_session", "status": "open",
  "payment": "pay_3Qd…", "client_secret": "cs_test_8Lk…_secret_…",
  "expires_at": 1792302600, "livemode": false, "version": 1
}

Every proposed request has the same parts. The key (②) decides whose data this is and what it may do. The idempotency key (③) makes the request safe to repeat. The version header (④) pins the meaning of every field, so PayAssist can change the contract later without breaking old integrations. Amounts are whole numbers of the currency's smallest unit (⑤), never decimals, which avoids rounding errors. The store's own order id and revision (⑥) bind the session to exactly one version of the cart. Every response carries a request id, which support can look up.

Why plain HTTPS and JSON

Both arena designs that addressed it, Codex GPT-6.1-Sol's and Claude Opus 5.5's, recommended REST over HTTPS with JSON for the public contract, described in one OpenAPI 3.1 document, and kept gRPC for internal paths that measure a need Proposed. The reasons are practical: browsers cannot speak gRPC without a translating proxy, PHP's gRPC extension is awkward on shared WordPress hosting, and every developer already has curl and Postman. The arena summaries described this as a unanimous vote; it was two independent recommendations that happened to agree Corrected.

The OpenAPI document becomes the single source of truth. SDKs for PHP and Node are generated from it, with hand-written helpers for webhooks on top, and a check in continuous integration fails the build whenever the server's routes and the document disagree. Dated versions follow Stripe's model, where a header selects the version per request and each webhook endpoint has its own pinned version S28.

Errors that tell the client what to do

An error body should answer one question: what should the caller do now? The proposal uses the standard problem-details format from RFC 9457 S62 with a few extra fields: a stable code, the offending param, the request_id, and retryable. The status code family tells the SDK how to behave.

The idempotency protocol, step by step

The status codes follow the IETF's draft Idempotency-Key specification: 400 for a missing key, 409 while the first request is still running, 422 for a key reused with a different payload S59. That draft expired in April 2026 without becoming a standard S58, so the book cites it as a widely copied convention, not a rule. The arena proposals disagreed on details here: Claude Opus 5.5 kept rows for 24 hours, Codex GPT-6.1-Sol and Codex Astra kept replays for 7 days, and Codex used 409 where the others used 422 Proposed. This book picks the draft's codes, a 7-day replay window and permanent business uniqueness This book, because a store's retry queue can run longer than a day after an outage, and the cost of a longer window is only storage.

The fingerprint should hash the validated request, meaning the fields after parsing and defaulting, together with the store, mode and route. Hashing the raw bytes would reject harmless differences such as key order; Codex Astra proposed the JSON Canonicalization Scheme of RFC 8785 for this, which is one reasonable choice S61.

Lists, limits and the shape of time

• Lists use cursors. GET /v1/events?after={cursor}&limit=100 returns the next page after a saved position, with a next_cursor to save once the page is applied. A cursor is only safe if nothing can appear behind it later, and a database can break that. Transaction A takes event number 100 and pauses; transaction B takes 101 and commits; a store reads 101 and saves its cursor; then A commits 100, behind the cursor, where the store will never look. So the feed does not use those numbers. One publisher hands out feed positions only to events that have already committed, in order, and every page stops at a fixed high-water mark This book. A cursor belongs to one store and mode.
• Rate limits answer 429 with Retry-After. SDKs wait, then retry with jitter, keeping the same idempotency key.
• Timestamps are Unix seconds in UTC. They describe when things happened; object versions, not timestamps, decide what is newer.

The full list of proposed endpoints and events is in Appendix D, organized by resource the way Stripe's reference is.

What a key looks like

Key formatsThis bookIllustrative

pa_pk_test_4f8KQ2…            publishable: identifies a store in the browser
pa_rk_live_9Zt1Lm…c7Qd         restricted: listed scopes only (the plugin's key)
pa_sk_live_2Hx8Vb…k3Pw         secret: everything for one store and mode
whsec_RXhhbXBsZU9ubHk…         webhook signing secret, one per endpoint
 └┬─┘└┬┘└┬─┘└───┬────┘└┬┘
  │   │  │      │      └ 32-bit checksum, so scanners can skip look-alikes
  │   │  │      └ at least 128 bits of randomness
  │   │  └ mode: test or live
  │   └ type: pk, rk or sk
  └ PayAssist's own prefix

The arena proposals used Stripe's exact prefixes, pk_, sk_ and rk_ Proposed. This book recommends a PayAssist prefix in front of them This book. Many PayAssist merchants will already have Stripe keys in the same configuration files, and identical prefixes invite pasting the wrong one. Secret scanners also match on prefixes, and GitHub's partner program asks token issuers for distinctive patterns, high-entropy random parts and a checksum so leaks can be found with few false alarms S86. A key that looks exactly like Stripe's would be reported to the wrong company. Webhook secrets keep the whsec_ form because the Standard Webhooks libraries expect it (Chapter 10).

How PayAssist stores them

The two kinds of secret need opposite treatment. PayAssist only ever needs to compare an API key with what a store sends, so it stores a keyed hash of the key, like a password, and shows the key once at creation. PayAssist must use a webhook signing secret to sign every event, so it cannot store just a hash; it stores the secret encrypted, with the encryption key kept outside the database. Codex GPT-6.1-Sol's arena design spelled this out: a keyed hash for API keys, and envelope encryption for any secret an outbound call needs Proposed. Claude Opus 5.5's design stored API keys as SHA-256 hashes and gave each webhook endpoint its own secret, but never said how those secrets are stored. This book adopts Codex's explicit split This book.

Scopes: give each part the smallest key that works

Scope checks run on the server for every request, including when an authorization result is cached. A key can also carry an expiry date and an optional list of allowed IP addresses.

Connecting a plugin without pasting secrets

Today a merchant pairs the WooCommerce plugin by entering settings that include a shared secret Today. Pasted secrets end up in chat messages, screenshots and support tickets. Claude Opus 5.5's arena design proposed a "Connect to PayAssist" button that mints the plugin's key and registers its webhook endpoint automatically; Codex GPT-6.1-Sol's proposed the OAuth authorization-code flow with PKCE for third-party apps Proposed. The flow below combines them.

The day a key leaks

Three properties limited that leak. The key had a recognizable format, so it was found quickly. Its scopes were the most it could do: it could create sessions, read events and issue refunds for one store in one mode, and nothing else. And revoking it took effect at once while the plugin received a new key. The overlap in Figure 8.1 is for planned rotation of a key nobody else has seen, never for an exposed one S88. Today a single per-store secret signs traffic in both directions, so rotating it means changing Backend and the plugin at the same moment Today.

Test mode is a separate world

Every key belongs to test or live mode, and so does every object. A test key can never read or change a live row; "livemode" is part of every unique index and every query. Test mode routes to provider sandboxes or to PayAssist's existing mock node, which boots the real node code with a fake provider Today. That separation is what lets merchants rehearse every scenario in Chapter 20 without moving real money.

Three ways to show the payment form

Codex GPT-6.1-Sol's arena design made hosted checkout the default and the first slice; Claude Opus 5.5's listed all three modes from the start Proposed. This book recommends shipping hosted and modal first, because both already exist in the current plugin and node pages, and adding the embedded element after the protocol underneath is proven This book.

Where should the payment page live? The frame-origin decision

Today each account node serves its own payment page from its own domain, so a store's checkout frame comes from a different host depending on which account the router picked Today. Claude Opus 5.5 and Claude Sonnet 5.5 proposed moving every buyer-facing page to one stable PayAssist origin, with nodes still making provider calls from their dedicated IPs behind it Proposed.

The handshake

Whichever origin serves the frame, page and frame should greet each other in a checked way before anything else happens. Today they exchange plain window messages, which the WooCommerce modal checks for origin and window Today. The proposal adds a nonce from the server and a private MessageChannel port, drawing on Claude Opus 5.5's and Codex GPT-6.1-Sol's designs. Claude Sonnet 5.5's code sketch had the origin checks and the port but no nonce, and its listener would stop after the first message even if that message was invalid. This book's review found both gaps by reading the sketch; nobody has written or tested a fix This book.

Two details decide whether the handshake can work at all. First, frame-ancestors is a header on the frame's own response, and a meta tag cannot set it S41, so the node must choose it before sending the page. The frame's path carries the session id, which is not a secret, and the node looks up that session's store origins and sends them with Cache-Control: no-store; the capability stays in the fragment. Second, the nonce must reach both sides by different roads. The store's server receives frame_nonce when it creates the session and puts it in the page; the frame learns the same nonce from the node when it verifies the capability. The page sends init with the protocol version, session id and nonce when the iframe's load event fires, and repeats it until the frame answers hello with the same three values and one private port, so the frame never has to announce itself to an unknown parent. The frame starts listening before it verifies the capability and holds an early init until verification finishes This book.

Reserving space so the page does not jump

When a frame loads late and pushes the page down, buyers mis-tap and Google's layout-shift score (CLS) suffers. Claude Sonnet 5.5's design has the server suggest the form's likely height when it creates the session, so the store page can reserve that space before the frame arrives, and the frame then reports its real height. That is a sound technique. Its "CLS below 0.02" figure was labeled a target and never measured; summaries later presented it as a result Corrected. Wallet buttons that appear only on some devices will still shift a first visit.

Styling as data, not code

Merchants want the form to match their store. Letting them inject CSS into the payment frame would let them, or an attacker on their page, read keystrokes through clever selectors. Claude Sonnet 5.5's design accepts only a closed set of named settings, such as primary color and corner radius, which code inside the frame turns into CSS, and it reports which settings a provider ignored. Its compiler is real code. Rerun under Bun 1.4.0 on 18 October 2026, the shared compiler-and-reducer test file passed 10 tests with 41,509 assertions in 3.37 seconds; one appearance test generated 20,000 random style objects and checked them for forbidden characters Synthetic test. That shows the compiler rejects the tested strings under Bun. It does not test a browser, a provider's fields or font loading, and summaries that called it proof of a secure SDK overstated it Corrected.

The browser never decides the outcome

Popups, 3DS and wallets

• 3DS needs the full screen. The frame asks the page for an overlay; the page makes the frame full-screen with a focus trap, and the reserved space keeps the page from jumping underneath. Stripe forbids sandboxing its 3DS iframe S53.
• Popups must open inside the click. Safari blocks a window opened after an asynchronous wait, so PayPal-style flows open a blank window synchronously and fill it afterwards.
• Wallets need permission at every frame. allow="payment" on each iframe in the chain, Safari 17 or later for Apple Pay in a cross-origin frame S46 S47.
• In-app browsers get the hosted page. Wallets often fail inside app webviews, so PayAssist.js falls back to the hosted redirect there.

The same protocol from a Next.js store

Next.js App Router sketchIllustrativeProposed SDK names

// app/checkout/actions.ts runs on the server only
'use server';
import { payassist } from '@/lib/payassist';        // new PayAssist(process.env.PAYASSIST_RK)
export async function startCheckout() {
  const cart = await loadCartForCurrentShopper();  // authenticate and price on the server:
                                                   // server actions are public POST endpoints
  const s = await payassist.checkoutSessions.create(
    { amount: cart.totalMinor, currency: cart.currency, order_reference: cart.orderId,
      order_revision: cart.revision, ui_mode: 'embedded', return_url: cart.returnUrl },
    { idempotencyKey: `order-${cart.orderId}-r${cart.revision}` });
  return { clientSecret: s.client_secret };               // the only thing the browser gets
}

// app/api/payassist/webhook/route.ts
export async function POST(req: Request) {
  const raw = await req.text();                          // exact bytes, before any JSON.parse
  const event = payassist.webhooks.verify(raw, req.headers, process.env.PAYASSIST_WHSEC);
  await db.transaction(async (tx) => {                  // inbox + order + jobs, one transaction
    if (!(await tx.inbox.insertIfNew(event.id))) return;  // duplicate: already applied
    await applyPaymentEvent(tx, event);                     // version check, mark paid, enqueue fulfillment
  });
  return new Response(null, { status: 200 });             // only after the commit
}

Three Next.js facts shape this sketch. Server Actions are reachable by any POST request, so each must authenticate and price the cart itself S82. Route handlers read the raw body with request.text() S83. And after(), which runs code after the response, is not durable: work scheduled there is lost if the process dies S84. Claude Sonnet 5.5's sketch answered the webhook first and fulfilled inside after(), which can lose a paid order Corrected. In Next.js 16 the request-interception file is called proxy.ts instead of middleware.ts and runs on Node.js only S85.

What an event contains

payment.succeededProposedIllustrative

{
  "id": "evt_1QxL…",                  stable across every retry: the receiver's dedup key
  "type": "payment.succeeded",
  "created": 1792301845,
  "livemode": false,
  "api_version": "2026-11-01",         the version this copy is rendered in
  "data": {
    "object": {                          a snapshot of the object at this moment
      "id": "pay_3Qd…", "object": "payment", "status": "succeeded",
      "amount": 3850, "amount_received": 3850, "amount_refunded": 0, "currency": "usd",
      "checkout_session": "cs_test_8Lk…", "session_status": "complete",   expired if money moved after the session ended (R6)
      "order_reference": "1042", "order_revision": 1,
      "version": 4                         goes up by one with every change (rule R9)
    }
  }
}

The event carries a snapshot of the whole object, so a store can usually act without a follow-up call, and a version number, so it can tell old news from new. It carries no card data, no client secret and only the customer details a store needs. The proposed version 1 event list is short: checkout.session.completed, checkout.session.expired, payment.processing, payment.requires_action, payment.succeeded, payment.canceled, payment.declined, refund.created, refund.succeeded, refund.failed, dispute.created, dispute.updated and dispute.closed. Today the plugin receives six callback kinds: succeeded, refunded, partially refunded, and dispute opened, won and lost Today.

PayAssist stores each event once, as a snapshot of the object at one version. Each webhook endpoint pins an API version, and each delivery row freezes the body rendered for that version when the delivery is created, so every retry and every manual replay sends the same bytes with a fresh signature. Changing an endpoint's version affects only deliveries created afterwards. The feed renders an event in the reading key's pinned version and says which one it used. A store that receives one event through both a webhook and the feed deduplicates by event id, never by comparing bytes This book.

How long to keep trying

A small WordPress site can be down for a weekend. The retry window decides whether its paid orders arrive late or never. Today Backend's WooCommerce callback queue makes 24 attempts and then marks the row dead; the waits between them add up to about 18 hours Today. Claude Opus 5.5's arena document claimed these attempts ended after 2 to 4 hours; that figure matches a different queue, the old Connect service's, not the WooCommerce queue Corrected. All three infrastructure designs in the arena proposed retrying for 72 hours, the same window Stripe uses for live webhooks S18, with different formulas Proposed. This book picks full jitter, the formula from AWS's backoff study: each wait is a random time between zero and min(6 hours, 30 seconds × 2^attempt), with a hard deadline at 72 hours S66 This book. If every wait came out at its average, that gives 32 attempts before the deadline; real counts vary with the random draws. The randomness stops thousands of failed deliveries from retrying at the same instant when a popular host comes back.

Signing: use the published standard

Every arena design signed webhooks the way Stripe does: a header with a timestamp and an HMAC of the timestamp plus the body Proposed. That works. This book recommends adopting the published Standard Webhooks specification instead This book. It uses three headers, webhook-id, webhook-timestamp and webhook-signature, signs id.timestamp.body, and lists several signatures separated by spaces during a key rotation S63 S64. Including the event id in the signed content stops anyone from changing the id to slip past deduplication, and existing open-source libraries already verify it in many languages. Today's plugin link uses its own payassist-signature: t=…,v1=… header with one shared secret Today.

No promise about order

Retries, parallel senders and network paths reorder messages. Stripe documents that it does not guarantee event order S19, and none of the arena designs could promise arrival order over HTTP either; Codex Astra's design came closest, with per-order delivery lanes that wait for each delivery before sending the next, at the cost of one slow delivery blocking that order's later events Proposed. Summaries that promised strict per-order or per-merchant ordering went beyond all four designs Corrected.

Protecting PayAssist from the endpoints it calls

A webhook URL is an address a merchant typed. A careless or malicious one could point at PayAssist's own internal network, a classic server-side request forgery. The proposal resolves the hostname once, checks every resulting address against private and reserved ranges, connects only to the checked address, refuses redirects, and repeats the checks in an egress proxy at the network layer S87. It also protects other stores from a slow one: each endpoint gets a small number of concurrent requests and a 10-second timeout, so a store on a struggling host fills its own queue, not everyone's. Codex Astra proposed deficit round-robin scheduling for fairness at very high volume; Chapter 14 explains when that becomes worth building.

The shortcut that loses shipments

Claude Opus 5.5's arena design proposed a compact version: insert a fulfillment row with ON CONFLICT DO NOTHING, and ship only if the insert created a row. It does stop two simultaneous webhooks from both shipping. It fails on a crash, because the row commits before the shipping call happens, and every retry then sees "already exists" and skips the work Corrected. Step through it, then through the fix.

Some outside systems have no idempotency key, such as an old email gateway. The worker must then record "about to send" before sending and "sent" after, and on restart decide from those records and the outside system's own logs whether to send again. Some duplicates may remain possible; the job design makes them rare and visible instead of silent.

The race between the buyer and the webhook

A fast browser often reaches the thank-you page before the webhook arrives. If the page only reads the local order, the buyer sees "pending" for a payment that already succeeded. The fix is for the page's server code to ask PayAssist directly and feed the answer through the same apply-payment function. Stripe's fulfillment guide recommends the same thing: fulfill from both the webhook and the landing page, with a function that is safe to call repeatedly and concurrently S27.

Stock, holds and payments that arrive late

Stock lives in the store; money moves at the provider. If a buyer is stuck in a bank check while the store's stock hold runs out, another buyer can take the last item, and the first payment then succeeds for an item that is gone. WooCommerce's "Hold stock" setting cancels unpaid pending orders after its number of minutes and releases their stock S78. Today that clock and PayAssist's 12-minute checkout window are unrelated Today.

The proposal gives the store two controls and names a third for later. First, each session ends before the order's stock reservation does, with a margin; Chapter 18 shows how the plugin reads WooCommerce's two clocks and renews the reservation when a buyer comes back. Second, every store needs a written late-payment policy: fulfill if possible, otherwise refund automatically through the API with an idempotency key, and tell the buyer. Claude Opus 5.5's design offered a per-session late_payment_policy: auto_refund option for that case Proposed. A session's expiry stops new tries but cannot stop a payment already in flight, so the policy is needed even when the clocks are right. Third, for later: separate authorization and capture, where the bank approves now and the money moves only after the store confirms stock, would need a capture call, an authorized state and its own events, and version 1 has none of them This book.

What nobody can promise

Arena briefs asked for designs where inventory and payments "never desync". Codex GPT-6.1-Sol's answer was blunt and correct: across an independent merchant database and a processor, that is not an honest guarantee Corrected. What a good design can promise is narrower and more useful:

• no duplicate local effects, because of the inbox and job keys;
• explicit in-between states such as "paid but not fulfilled", instead of silent gaps;
• detection within a stated time, through reconciliation and alerts;
• a written, tested compensation for every mismatch, usually a refund or a manual review.

The store-side checklist

1. Read the raw request body and verify the signature before parsing (R11).
2. Lock the order first, so a webhook, a page read and the feed take turns.
3. Insert the event id into an inbox table; stop if it is already there (R8).
4. Ignore a version older than the stored version of the same object (R9).
5. Check mode, payment, order revision, amount and currency against what was saved when checkout started.
6. Do all local changes and job inserts in the same transaction, and answer 200 only after it commits.
7. Run outside work in a worker with leases and idempotency keys (R13).
8. Sync from the event feed on boot and every few minutes (R10).
9. On the thank-you page, read the payment server-side and apply it with the same checks and job as a webhook (R12).
10. End each session before the order's stock reservation runs out, and write a late-payment policy (R6).
11. Alert on paid-but-unfulfilled orders older than a set time.

Loop 1: the attempt reconciler

The reconciler is what makes rule R4 safe to follow. When an attempt goes silent, the buyer waits on a "checking" screen while the reconciler reads the provider. The scenario below is the dangerous case: the provider charged, and its answer was lost.

Today the standard node already does a version of this. It starts a recovery read about 3 minutes after a payment page opens even if the browser never confirms, and the staging source keeps re-reading unanswered provider calls for 23 hours and undecided payments for up to 7 days before marking them unresolved for a person instead of inventing a cancel or decline Today. Claude Opus 5.5's design proposed reading every stuck attempt after 5 minutes and then every 15 minutes until the session's expiry plus 24 hours Proposed. The exact schedule matters less than three properties: it starts quickly, it never fabricates an outcome, and its age is visible.

Loop 2: events and the feed

Chapter 10 built this loop. Its bound is concrete: pushes for 72 hours, the feed for 30 days. A store offline for longer than 30 days has bigger problems and needs a manual reconciliation report, which the dashboard can export.

Loop 3: the daily ledger check

Webhooks can be wrong in ways nobody notices: a missed refund, a fee that differs from the quote, a dispute that never produced an event. The slow loop compares PayAssist's ledger with each provider's balance and settlement reports. Codex Astra proposed reconciling captures and refunds against provider records and settlement reports independently of webhook delivery, noting that a successful HTTP delivery is not settlement evidence Proposed. Running that loop once a day is this book's choice This book.

What an operator should see

PayAssist already runs an OpenTelemetry pipeline into Loki, Prometheus and Grafana with correlated payment logs and alert rules Today, and the project's telemetry contract requires every new endpoint, worker and flow to follow its instrumentation standard. The new protocol's loops plug into that stack; they do not need a new monitoring system.

The briefs shaped the answers

The owner's two messages asked for a Stripe-like standard and permission to replace legacy parts. They contained no traffic figures and no compliance target Owner-confirmed. The coordinator's briefs to the agents added several:

So the famous numbers, 100,000 events and 50,000 orders per second, were inputs from the coordinator, not measurements or forecasts. Treat every capacity figure from the arena as illustrative arithmetic Illustrative.

What each agent proposed

Where they disagreed

What the records do not show

• No vote, rubric or rebuttal round. Each agent ran once, independently. "Winners" and "champions" appear only in the coordinator's summaries.
• No owner approval of any proposal. The open decisions in Opus's and Sonnet's documents remain open.
• No research report from Gemini. The batch credited with comparing Stripe, Adyen and Shopify contains only a placeholder.
• No benchmark. Every throughput, failover and layout-shift figure is a target or arithmetic.
• No working integration. Two JavaScript modules were tested; the Next.js, host, frame and WooCommerce code are unexecuted sketches, and the review found real gaps in them.

How this book decided

Where the proposals differed, this book applied five tests in order This book:

1. Correctness under the failure list. Does the choice keep every scenario in Chapter 20 safe for money and orders?
2. Binding constraints. Does it respect the owner's decisions: separate Stripe paths with no fallback, no platform key at nodes, card data never on PayAssist's servers, the existing proxy for Connect transport?
3. Evidence. Is it supported by code, a measurement or a primary source, or only by an agent's assertion?
4. The smallest thing that works. Does it need new infrastructure before there is a measured reason?
5. Reversibility. Can PayAssist change course later without breaking stores that already integrated?

The full list of decisions, with each one's source and status, is the decision ledger in Appendix B. The claims that had to be corrected are collected in Appendix C. An independent evidence agent recovered the arena history and audited 103 claims for this book; its report is in the evidence folder listed in Appendix H.

The recommended stack

Some candidates were considered and left out This book. Redis Streams would add a second store that can disagree with Postgres. Amazon SQS caps message delay at 15 minutes and would tie a Coolify-hosted system to AWS. Public gRPC and GraphQL make life harder for PHP hosts and browsers without a measured benefit. Claude Opus 5.5's arena comparison reached the same verdicts on Redis Streams and SQS Proposed.

The complexity ladder

The three big ideas, in plain words

• Change-data capture into Kafka. Instead of a worker polling the outbox table, a connector reads the database's own change log and copies each committed row into Kafka, a durable, ordered log many consumers can read at their own pace. It helps when one database cannot keep up with polling or many systems need the same stream. Consumers must still deduplicate, because the connector can repeat rows after a restart S69.
• Fair scheduling (deficit round-robin). When thousands of endpoints compete for a limited pool of workers, a large merchant with a slow server could take most of them. Deficit round-robin gives each endpoint a turn and a small budget per round, like a teacher calling on every raised hand before anyone gets a second turn. With a few hundred stores, a per-endpoint concurrency limit and a timeout already give each store its own lane.
• Cells. A cell is an independent copy of the whole system that serves a slice of the customers, so one bad deployment or overloaded database hurts only that slice S70. PayAssist's account nodes already have a cell-like shape for provider calls, but they share Backend and its database. Full cells multiply infrastructure and need a routing layer, and AWS's own guidance reserves them for strict recovery targets S71.

In version 1, and why

Later, and the reason for waiting

New tables in version 1

Schema sketchProposedIllustrative

api_keys            id, store_id, mode, kind (pk|rk|sk), prefix, keyed_hash, scopes[], expires_at, last_used_at, revoked_at
idempotency_keys    store_id, mode, route, key, fingerprint, state (running|done), status, response, created_at
                    unique (store_id, mode, route, key); replay rows kept 7 days
order_admissions    store_id, mode, order_reference, highest_revision, live_payment_id
                    unique (store_id, mode, order_reference): every create for an order passes this row in turn (rule R2)
payments            id, store_id, mode, order_reference, order_revision, terms_digest, amount, currency,
                    status, amount_received, version, payment_request_id
                    unique (store_id, mode, order_reference, order_revision) where status <> 'canceled': a second guard
checkout_sessions   id, payment_id, ui_mode, status, expires_at, return_url, frame_nonce, version
                    unique (payment_id) where status = 'open'
attempts            today's payment_attempts rows, plus provider_object_state, frozen create parameters,
                    first_sent_at and the provider's key-retention deadline (rules R3, R5)
events              id, store_id, mode, type, object_type, object_id, object_version, payload, created_at,
                    feed_position (set by the single publisher after commit: rule R10)
                    written in the same transaction as the change: rule R7
webhook_endpoints   id, store_id, mode, url, enabled_types[], api_version, secrets (encrypted, with expiry), status
webhook_deliveries  id, event_id, endpoint_id, api_version, body (frozen when created), attempt, next_attempt_at,
                    lease_until, last_status, state
                    unique (event_id, endpoint_id); partitioned by day
underneath: payment_requests, payment_attempts, checkout tokens, routing and accounting tables

Two of those lines hide open work. Today Backend allows one payment request per store and WooCommerce order Today, while the proposal allows a new payment per order revision; how revisions map onto that rule is a design decision for step 2. And reusing today's attempts means reusing their keys, including the diagnosed /pay defect that can change a create's parameters under the same key (E1 §4). Safe retries need the parameters frozen on the attempt as well as a stable key, so gate 1 in Chapter 16 checks that repeated loads of one attempt send identical parameters.

The order of work

What has been measured so far

The proposed protocol has never run, so it has no benchmarks. The closest real numbers come from the current Stripe Connect checkout on staging, measured with a passive browser trace on 16 and 17 October 2026, one fresh load and three reloads before and after a latency patch Measured. They are the baseline any new design must at least match.

None of these is a load test. There is no measured figure for how many checkouts or events per second PayAssist can sustain, which is why Chapter 14's ladder uses measurements as triggers instead of capacity targets.

What the new protocol must measure

The gates

After version 1: the road to industry-grade

1. Stabilize. Version 1 in production for existing WooCommerce merchants, gates passed, measurements published internally.
2. Developer experience. The CLI for local webhook forwarding and test triggers, test-mode scenario cards that fail on purpose, a Python SDK, a public changelog.
3. Embedded checkout. PayAssist.js and the embedded element, with the browser certification from gate 6 extended to it.
4. Scale evidence. The skewed load test from Chapter 14, then rung 1 of the ladder if its trigger fires.
5. Owner decisions. The stable frame origin trial, saved cards per provider, and any regional requirements, each with its own measured case.

What moves, and how

What the migration must never touch

• The two Stripe paths. Standard stripe and stripe_connect remain separate supported integrations with no automatic fallback, and the migration does not move a merchant from one to the other Owner-confirmed.
• Platform keys. The Stripe Connect platform key stays in the central Connect service and never reaches a node Owner-confirmed.
• Provider calls. Standard-provider calls stay on account nodes and their dedicated IPs, and Connect calls stay in the central Connect service. The new public API does not call providers itself.
• The external order receiver. The separate e-commerce receiver used for order generation stays unchanged; PayAssist adapts to its actual behavior on its own side Owner-confirmed.

When to stop and roll back

Write the rollback triggers before the first store flips, so nobody argues about them during an incident. Reasonable triggers: any money-invariant alert from Chapter 16; form-ready time on v1 worse than legacy for the same store over a day; delivery failures on v1 that do not occur on legacy; a support pattern that points at the new flow. Rolling back is a flag change for new orders, which is why stages 2 to 4 keep both receivers running.

Installing and connecting

The merchant installs plugin 2.0 and presses "Connect to PayAssist" in WooCommerce's payment settings. The connect flow from Chapter 8 runs: the merchant approves the plugin's scopes in the PayAssist dashboard, and the plugin receives a restricted test key and the webhook secret over a server-to-server call. PayAssist registers the plugin's event route as a webhook endpoint and sends a test event to prove it works.

The settings that matter

WooCommerce runs two clocks here, and neither is the session's. When the checkout creates an order, WooCommerce reserves its stock until that moment plus the "Hold stock" minutes, and other carts respect the reservation until it expires S99. Separately, a job cancels unpaid orders whose last update is older than the hold; it runs once per hold interval and, by default, only for orders created by the checkout or the Store API S78 S100. No setting can line those clocks up by itself.

The plugin reads the order's reservation and gives each session an expiry before it, minus a margin. If a buyer comes back late, the plugin renews the reservation with wc_reserve_stock_for_order(), which fails when the stock is gone, and only then opens a new session. The API's shortest session is 15 minutes, so the plugin needs a renewed reservation that lasts at least 15 minutes plus the margin. With a shorter "Hold stock" setting, renewing cannot reach that, so the plugin refuses to open sessions and asks the merchant to raise the setting. With a blank hold nothing is reserved, and every late success goes to the late-payment policy. A session's expiry stops new tries, never a payment already in flight, so every success still goes through the late-payment policy This book.

What WooCommerce requires of a payment plugin

• A gateway class for the classic checkout. It extends WC_Payment_Gateway, and its process_payment() returns a result and a redirect S72.
• A separate integration for the block-based checkout. A JavaScript registration plus a server class; WooCommerce's documentation stresses it does not replace the gateway class S73.
• Order access through WooCommerce's own functions. Stores using high-performance order storage keep orders in custom tables, so the plugin uses wc_get_order() and order methods, never raw post queries, and declares compatibility S77.
• Marking paid with payment_complete(). It reduces stock and sets the right status; WooCommerce recommends it over setting a status directly S72. Today's plugin already calls it from the signed callback Today.
• Explicit permissions on REST routes. Every route the plugin registers declares a permission callback; the event route is public and authenticates by signature S79.

The messages, step by step

Open any step below. Hostnames, ids, keys and signatures are invented, and the request shapes are the proposal, not running code Proposed Illustrative.

POST /v1/checkout_sessions
Authorization: Bearer pa_rk_test_…            plugin's restricted key
Idempotency-Key: wc-1042-r1-s1
PayAssist-Version: 2026-11-01

{ "amount": 3850, "currency": "usd", "order_reference": "1042", "order_revision": 1,
  "ui_mode": "modal", "expires_in": 1800,
  "return_url": "https://larkspur-tea.example/checkout/order-received/1042/?key=wc_order_EXAMPLE" }

201 { "id": "cs_test_8Lk", "status": "open", "payment": "pay_3Qd", "livemode": false,
      "client_secret": "cs_test_8Lk_secret_…", "frame_nonce": "fn_4Tq…",
      "url": "https://node-a.payassist.example/c/cs_test_8Lk#cap=cs_test_8Lk_secret_…",
      "expires_at": 1792302600 }

https://node-a.payassist.example/c/cs_test_8Lk#cap=cs_test_8Lk_secret_…

POST https://api.stripe.com/v1/payment_intents       from the node's own IP, with the account's key
Idempotency-Key: pat_1:create
amount=3850&currency=usd&metadata[payassist_attempt]=pat_1

-- transaction pseudocode: every branch is real control flow, not a comment
BEGIN
  payment := SELECT * FROM payments WHERE id = 'pay_3Qd' AND store_id = 'larkspur' AND mode = 'test' FOR UPDATE
  attempt := SELECT * FROM attempts WHERE id = 'pat_1' AND payment_id = payment.id AND account_id = <the reporting node's account>
  IF attempt IS NULL OR the provider's amount or currency differ THEN
      record a review case; COMMIT; stop                       -- no success event
  IF payment.status = 'succeeded' THEN
      COMMIT; return the saved result                          -- a repeated report changes nothing
  IF payment.status = 'canceled' THEN
      record a provider-contradiction review; COMMIT; stop   -- rule R6
  changed := UPDATE payments SET status = 'succeeded', amount_received = 3850, version = version + 1
             WHERE id = payment.id
               AND status IN ('requires_payment_method', 'processing', 'requires_action')
             RETURNING *                                           -- version 4: versions 2 and 3 recorded the attempt and processing
  IF changed IS NOT NULL THEN
      event := INSERT INTO events: payment.succeeded, version changed.version, snapshot of changed   -- rule R7
      INSERT INTO webhook_deliveries: one row per endpoint of this store, in this mode, subscribed to
          payment.succeeded, each with the body frozen in that endpoint's API version
COMMIT

POST https://larkspur-tea.example/wp-json/payassist/v2/events
webhook-id: evt_1QxL
webhook-timestamp: 1792301846
webhook-signature: v1,K3m9xQ…=
Content-Type: application/json

{"id":"evt_1QxL","type":"payment.succeeded","livemode":false,"api_version":"2026-11-01",
 "data":{"object":{"id":"pay_3Qd","object":"payment","checkout_session":"cs_test_8Lk","session_status":"complete",
 "status":"succeeded","amount":3850,"amount_received":3850,"currency":"usd","order_reference":"1042","order_revision":1,
 "version":4}}}

START TRANSACTION;
  INSERT INTO wp_payassist_inbox (event_id, received_at) VALUES ('evt_1QxL', UTC_TIMESTAMP())
      ON DUPLICATE KEY UPDATE event_id = event_id;                -- 0 rows: a proven duplicate, stop
  SELECT … FROM wp_payassist_bindings WHERE order_id = 1042 FOR UPDATE;   -- one fact at a time per order
  -- binding for pay_3Qd: session cs_test_8Lk, revision 1, test mode, 3850 usd; the fact matches.
  -- No version stored yet for payment:pay_3Qd, so 4 is newer.
  INSERT version 4 for payment:pay_3Qd INTO wp_payassist_versions
  INSERT INTO wp_payassist_jobs (job_key, order_id, payment_id, fact, state)
      VALUES ('complete:pay_3Qd', 1042, 'pay_3Qd', '{…the validated fact…}', 'pending')
      ON DUPLICATE KEY UPDATE job_key = job_key;                  -- one completion job per payment, ever
COMMIT;
-- then answer 200; any failure above answers 500 and PayAssist retries

$b = Bindings::current($order);                                   // saved before checkout was shown
if ($b && !$order->is_paid()) {                                // cancelled orders too: a late success still counts
  $session = $payassist->checkoutSessions->retrieve($b->session_id);
  if ($session->payment->status === 'succeeded') ApplyPayment::read($session->payment);
}

What each side holds afterwards

How long it should take

There are no measurements of this proposed flow. The closest guide is the current staging Connect checkout in Figure 16.1: about 9 seconds from popup to a ready form on a fresh load after the October patch, about 2.3 seconds on a reload, and a callback to WooCommerce in about a second once Backend has applied the payment Measured. The new flow adds one API call before the popup and changes no provider step, so it should land near those numbers. That is a hypothesis until it is measured; the latency check in gate 7 of Chapter 16 is there to test it.

The colored dot beside each scenario, in the list and next to its title, tells you how it ends: ends well, recovers after a delay or a compensation, shows what goes wrong without the rule. Each scenario's link is shareable: the address bar updates as you choose.

What the five groups teach

The same scenarios appear as one table, with today's behavior and a test for each, in the failure matrix of Appendix E.

The files and tables

payassist-woocommerce/
  payassist-woocommerce.php     bootstrap: compatibility flags, gateway registration
  src/Gateway.php               classic checkout: process_payment, the order-pay page, process_refund
  src/BlocksIntegration.php     block checkout, server side
  assets/blocks.js              block checkout, browser side
  assets/checkout-modal.js      opens the payment frame and runs the handshake (R16)
  src/EventsRoute.php           POST /wp-json/payassist/v2/events
  src/ApplyPayment.php          one function for events and server reads (R8, R9, R12)
  src/Db.php                    money-path transactions on their own connection
  src/Jobs.php                  the plugin's own job table, its runner and the feed sync (R10, R13)
  src/Refunds.php               refund commands
  src/Install.php               the tables below, and the connect flow
  src/…                         helpers the sketch calls but does not show: Bindings, Commands, Revisions,
                                Stock, Versions, Reviews, LatePayments, Locks, Checkpoints, Fact, Money
  vendor/payassist/payassist-php  the proposed PHP SDK

wp_payassist_inbox        event_id (primary key), received_at
wp_payassist_bindings     payment_id (primary key), order_id (index), session_id, revision, mode, amount_minor, currency
wp_payassist_versions     object_key (primary key, such as "payment:pay_3Qd"), version
wp_payassist_jobs         job_key (primary key), order_id, payment_id, fact (the validated fact, as JSON), state,
                          attempts, next_run_at, lease_owner, lease_until, last_error
wp_payassist_refunds      command_id (primary key), order_id, wc_refund_id, payment_id, amount_minor, currency,
                          reason, payassist_refund_id (unique), state, created_at
wp_payassist_checkpoints  store_id + mode (primary key), cursor
wp_payassist_reviews      id, order_id, reason, fact, created_at, resolved_at

A binding row is written for every session before the buyer sees a payment page. It records exactly which payment this order expects, in which mode, for which session, revision and amount, and every later fact is checked against it. The order also carries three meta fields: the revision counter, the session generation and the saved create command.

1 · Bootstrap: declare what the plugin supports

// payassist-woocommerce.php
add_action( 'before_woocommerce_init', function () {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        // orders live in HPOS tables: use WooCommerce CRUD only, never raw post queries
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
    }
} );
add_filter( 'woocommerce_payment_gateways', function ( $gateways ) {
    $gateways[] = \PayAssist\Woo\Gateway::class;
    return $gateways;
} );

2 · The gateway: create a session, never charge directly

// src/Gateway.php (excerpt)
public $supports = [ 'products', 'refunds' ];

public function process_payment( $order_id, bool $renewed = false ) {
    $order = wc_get_order( $order_id );
    // The whole create command is built once, saved on the order, and resent unchanged on every retry.
    $cmd = Commands::saved_or_new( $order, fn( int $rev, int $gen ) => [
        'body' => [
            'amount'          => Money::toMinor( $order->get_total(), $order->get_currency() ), // the currency's decimals, not "x 100"
            'currency'        => strtolower( $order->get_currency() ),
            'order_reference' => (string) $order->get_id(),     // WooCommerce's internal id, not the display number
            'order_revision'  => $rev,                          // a counter raised when the cart changes (R2)
            'ui_mode'         => 'popup' === $this->get_option( 'display_mode' ) ? 'modal' : 'hosted',
            'expires_in'      => Stock::session_seconds( $order ), // fixed once, from the stock reservation (Chapter 18)
            'return_url'      => $this->get_return_url( $order ),
        ],
        'key' => "wc-{$order_id}-r{$rev}-s{$gen}",              // R1: one command, one key
    ] );
    try {
        $created = $this->client()->checkoutSessions->create( $cmd->body, [ 'idempotency_key' => $cmd->key ] );
        $session = $this->client()->checkoutSessions->retrieve( $created->id );  // a replay shows the first answer; read today's state
    } catch ( \PayAssist\Exception\OutcomeUnknown $e ) {
        wc_add_notice( __( 'The payment service did not answer. Please try again.', 'payassist' ), 'error' );
        return [ 'result' => 'failure' ];                       // creating a session moves no money; the retry resends the command
    } catch ( \PayAssist\Exception\Conflict $e ) {
        wc_add_notice( __( 'We are still checking an earlier payment for this order. Please try again in a minute.', 'payassist' ), 'error' );
        return [ 'result' => 'failure' ];                       // 409: an earlier session for this order may still take money
    }
    if ( 'succeeded' === $session->payment->status ) {          // paid, even if the session expired first (R6)
        ApplyPayment::read( $session->payment );
        return [ 'result' => 'success', 'redirect' => $this->get_return_url( $order ) ];
    }
    if ( 'expired' === $session->status ) {
        if ( $renewed || 'canceled' !== $session->payment->status ) {   // the old payment might still charge: wait
            wc_add_notice( __( 'We are still checking an earlier payment for this order. Please try again in a minute.', 'payassist' ), 'error' );
            return [ 'result' => 'failure' ];
        }
        Stock::renew_or_fail( $order );                         // throws if the stock is gone or the hold is too short
        Commands::next_generation( $order );                    // under the order lock; the next call builds a new command
        return $this->process_payment( $order_id, true );       // at most one renewal per click
    }
    if ( 'open' !== $session->status ) {                        // complete without a successful payment: for a person
        Reviews::open_for( $order, null, 'session complete without a successful payment' );
        wc_add_notice( __( 'We could not confirm this payment. The store has been told.', 'payassist' ), 'error' );
        return [ 'result' => 'failure' ];
    }
    Bindings::save( $order, $session );                         // payment, session, revision, mode, amount, currency
    return [ 'result'   => 'success',
             'redirect' => 'hosted' === $session->ui_mode
                 ? $session->url                                // the capability rides in the URL fragment
                 : $order->get_checkout_payment_url( true ) ];  // the order-pay page opens the modal (piece 4)
}

Four details come from real bugs and reviews. Today's plugin once looked orders up by the number shown to customers, which some stores change with sequential-numbering plugins; the staging source fixed it by saving the correlation before calling Backend, and the sketch keeps that habit Today. Claude Sonnet 5.5's headless sketch converted amounts by multiplying by 100, which is wrong for currencies with no minor unit such as the Japanese yen. The revision is a counter rather than a hash of the cart, because a cart that changes from A to B and back to A must not reuse the first revision's key. And the whole create command is saved before the first request: if a retry recomputed expires_in a few seconds later, the request would differ under the same key and the API would correctly answer 422. Because a replayed create only returns the first answer, the plugin then reads the session's current state before deciding anything.

3 · The block checkout needs its own registration

// src/BlocksIntegration.php
final class BlocksIntegration extends \Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType {
    protected $name = 'payassist';
    public function initialize() { $this->settings = get_option( 'woocommerce_payassist_settings', [] ); }
    public function is_active() { return 'yes' === ( $this->settings['enabled'] ?? 'no' ); }
    public function get_payment_method_script_handles() {
        wp_register_script( 'payassist-blocks', plugins_url( 'assets/blocks.js', PAYASSIST_FILE ),
                            [ 'wc-blocks-registry', 'wp-element' ], PAYASSIST_VERSION, true );
        return [ 'payassist-blocks' ];
    }
}
add_action( 'woocommerce_blocks_payment_method_type_registration',
            fn( $registry ) => $registry->register( new BlocksIntegration() ) );

// assets/blocks.js
const { registerPaymentMethod } = window.wc.wcBlocksRegistry;
const el = window.wp.element.createElement;
registerPaymentMethod( {
  name: 'payassist', label: 'Card', ariaLabel: 'Pay by card with PayAssist',
  content: el( 'p', null, 'You will pay in a secure window after placing the order.' ),
  edit: el( 'p', null, 'PayAssist card payment' ),
  canMakePayment: () => true,
} );

Both checkouts end in the same process_payment(), so the hosted redirect and the modal behave the same way whichever checkout the store uses.

4 · The order-pay page opens the modal

// src/Gateway.php (excerpt): WooCommerce runs this on the order-pay page after checking the order key
add_action( 'woocommerce_receipt_payassist', function ( int $order_id ) {
    $order = wc_get_order( $order_id );
    $b     = Bindings::current( $order );
    if ( ! $b || $order->is_paid() ) return;
    $session = payassist_client()->checkoutSessions->retrieve( $b->session_id );   // today's state; never a create here
    if ( 'succeeded' === $session->payment->status ) {                              // paid, even if the session expired first
        ApplyPayment::read( $session->payment );                                    // same checks and job as a webhook
        printf( '<p>%s <a href="%s">%s</a></p>', esc_html__( 'Payment received.', 'payassist' ),
                esc_url( $order->get_checkout_order_received_url() ), esc_html__( 'See your order', 'payassist' ) );
        return;
    }
    if ( 'open' !== $session->status ) {                                            // ended unpaid: process_payment decides if renewal is safe
        printf( '<p><a href="%s">%s</a></p>', esc_url( $order->get_checkout_payment_url() ),
                esc_html__( 'This checkout has ended. Start again', 'payassist' ) );
        return;
    }
    wp_enqueue_script( 'payassist-modal' );
    printf( '<div id="payassist-pay" data-url="%s" data-session="%s" data-nonce="%s"></div>',
            esc_attr( $session->url ), esc_attr( $session->id ), esc_attr( $session->frame_nonce ) );
} );

// assets/checkout-modal.js (excerpt)
const box  = document.getElementById( 'payassist-pay' );
const url  = new URL( box.dataset.url );                        // the capability is in url.hash, never sent to a server
const want = { v: 1, session: box.dataset.session, nonce: box.dataset.nonce };
const SHOW = new Set( [ 'ready', 'resize', 'change', 'overlay', 'status', 'error', 'redirect' ] );
const frame = Object.assign( document.createElement( 'iframe' ), { src: url.href, allow: 'payment', title: 'Card payment' } );
let port = null, timer = null, hid = '';
frame.addEventListener( 'load', () => {                         // every load, including a reload: a fresh handshake
  port?.close(); port = null; clearTimeout( timer );
  hid = crypto.randomUUID();                                    // this load's handshake id
  let tries = 0;
  const init = () => {                                          // the page speaks first, to the exact frame origin,
    if ( port ) return;                                         // and repeats every 500 ms until hello, for 10 s
    if ( ++tries > 20 ) return showRetry();
    frame.contentWindow.postMessage( { t: 'init', ...want, hid }, url.origin );
    timer = setTimeout( init, 500 );
  };
  init();
} );
window.addEventListener( 'message', ( e ) => {
  const d = e.data || {};
  if ( e.source !== frame.contentWindow || e.origin !== url.origin || d.t !== 'hello' || port ) return;
  if ( d.v !== want.v || d.session !== want.session || d.nonce !== want.nonce || d.hid !== hid
       || e.ports.length !== 1 ) return;                        // R16; a hello from an older load fails the hid check
  clearTimeout( timer );
  port = e.ports[0];
  port.onmessage = ( m ) => { if ( m.data?.v === 1 && SHOW.has( m.data.t ) ) showStatus( m.data ); };   // the screen only (R12)
} );
openOverlay( frame );

The order-pay page resumes the bound session and never creates one, so a reload cannot start a second payment. When the session has ended, the buyer goes back through process_payment(), which renews the stock reservation and the session together. Every load of the frame, including a reload, closes the old port and starts a fresh handshake with a new handshake id. The page accepts a hello only from the frame's own window and origin, carrying the same protocol version, session, nonce and handshake id, with exactly one private port, and it uses port messages only from a short, versioned list. After 10 seconds without an answer it offers the buyer a retry. The frame does its half: it starts listening before it verifies the capability and holds an early init until verification finishes.

5 · The event route: verify the bytes, then apply

// src/EventsRoute.php
add_action( 'rest_api_init', function () {
    register_rest_route( 'payassist/v2', '/events', [
        'methods'             => 'POST',
        'permission_callback' => '__return_true',   // public by design: the signature authenticates
        'callback'            => function ( \WP_REST_Request $request ) {
            $raw = $request->get_body();             // exact bytes; never re-encode before verifying (R11)
            try {
                $event = \PayAssist\Webhook::verify( $raw, $request->get_headers(), payassist_signing_secrets() );
            } catch ( \PayAssist\Exception\SignatureVerification $e ) {
                return new \WP_REST_Response( null, 400 );   // nothing parsed, nothing changed
            }
            try {
                \PayAssist\Woo\ApplyPayment::event( $event );
            } catch ( \Throwable $e ) {
                payassist_log( 'apply_failed', $event->id, $e );
                return new \WP_REST_Response( null, 500 );   // not committed, or commit unknown: PayAssist retries
            }
            return new \WP_REST_Response( null, 200 );       // inbox row and job are committed
        },
    ] );
} );

WordPress requires a permission callback on every REST route since version 5.5 S79. The event route is deliberately public; the SDK's verifier checks the Standard Webhooks signature, the 5-minute window and every currently valid secret, and copes with WordPress's normalized header names. A 200 tells PayAssist to stop retrying, so the route sends it only after the apply function's commit returned, and 500 for anything else.

6 · One apply function for every door

// src/ApplyPayment.php
// A fact is what an authenticated source says about one object at one version: a verified event
// (webhook or feed) or a server-side read. Events are deduplicated by event id. A read has no
// event id, so it relies on the version check and on one completion job per payment.
final class ApplyPayment {
    public static function event( object $event ): void {
        Db::transaction( function ( \mysqli $db ) use ( $event ) {
            if ( ! Db::claim_event( $db, $event->id ) ) return;      // R8: a proven duplicate
            self::fact( $db, Fact::from_event( $event ) );
        } );
    }

    public static function read( object $payment ): void {           // the thank-you and order-pay pages (R12)
        Db::transaction( fn( \mysqli $db ) => self::fact( $db, Fact::from_payment( $payment ) ) );
    }

    private static function fact( \mysqli $db, Fact $f ): void {
        $b = Bindings::lock_for_payment( $db, $f->payment_id );     // locks every binding of that order: one fact at a time
        // Check the fact against what was saved when checkout started: connected store, mode, payment,
        // session, order reference, revision, amount and currency, as far as this kind of fact carries them.
        if ( ! $b || ! $b->matches( $f ) ) {
            Reviews::open( $db, $f, 'the fact does not match the payment saved for this order' );   // never silence
            return;
        }
        if ( 'payment.succeeded' === $f->type
             && ( 'succeeded' !== $f->status || $f->amount_received !== (int) $b->amount_minor ) ) {
            Reviews::open( $db, $f, 'success without the full amount' );   // never mark paid on a mismatch
            return;
        }
        if ( ! Versions::advance( $db, $f->object_type, $f->object_id, $f->version ) ) return;   // R9, per object, after validation
        if ( 'payment.succeeded' === $f->type ) {
            Jobs::add( $db, "complete:{$f->payment_id}", $b, $f );   // one completion job per payment, carrying the fact (R13)
        } elseif ( in_array( $f->object_type, [ 'refund', 'dispute' ], true ) ) {
            Jobs::add( $db, "{$f->object_type}:{$f->object_id}:{$f->version}", $b, $f );
        }
    }
}

// src/Db.php (excerpt): money-path transactions use their own mysqli connection.
// wpdb reconnects after a lost connection and runs the failed statement again outside the
// transaction, so a group of wpdb writes cannot promise to commit together.
final class Db {
    private static ?\mysqli $link = null;

    public static function transaction( callable $work ) {
        mysqli_report( MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT );           // every failure throws
        $db = self::$link ??= new \mysqli( DB_HOST, DB_USER, DB_PASSWORD, DB_NAME );   // no automatic reconnect
        $db->begin_transaction();
        try {
            $result = $work( $db );
            $db->commit();               // a lost acknowledgement throws too, so the route answers 500
            return $result;
        } catch ( \Throwable $e ) {
            try { $db->rollback(); } catch ( \Throwable $ignored ) {}
            self::$link = null;          // never reuse a connection after a failure
            throw $e;                    // every write is keyed, so PayAssist's retry is safe
        }
    }

    public static function claim_event( \mysqli $db, string $id ): bool {
        $q = $db->prepare( 'INSERT INTO ' . payassist_table( 'inbox' ) . ' (event_id, received_at)
              VALUES (?, UTC_TIMESTAMP()) ON DUPLICATE KEY UPDATE event_id = event_id' );
        $q->bind_param( 's', $id );
        $q->execute();
        return 1 === $q->affected_rows;  // 1: new; 0: the id was already there
    }
}

WordPress's own database helper, wpdb, reports errors through return values rather than exceptions S91, and when a connection drops it reconnects and runs the failed statement again on the new connection. That is convenient for page loads and wrong for money: a COMMIT replayed on a fresh connection reports success for a transaction that was already rolled back. So the money path opens its own mysqli connection, which fails loudly instead, and every write in it is keyed, so a retry after an unknown commit cannot double anything. All of it lives in the plugin's own InnoDB tables (InnoDB is MySQL's storage engine with transactions); WooCommerce's order is changed later, by the job. The lock on the order's bindings makes a webhook, a thank-you page read and the feed take turns, which the event id alone cannot do, because those are different messages about the same payment. Every fact is checked against the saved binding before its version is recorded, and versions are kept per object, so a refund at version 1 is never mistaken for old news about a payment at version 4. A mismatch opens a review case instead of throwing, because retrying a wrong amount for three days would only delay the alert.

7 · Jobs: finish the order, retry, and pull what pushes missed

// src/Jobs.php
// Retry state lives in the plugin's own table. Action Scheduler only wakes the runner, because it
// marks a failed one-time action as failed and never retries it (S95).
final class Jobs {
    public static function run_due(): void {
        while ( $job = self::claim() ) {     // sets lease_owner to a fresh random token and lease_until to now + 5 min
            try {
                self::handle( $job );        // checks it still owns the lease before any order write
                self::finish( $job );        // UPDATE … WHERE job_key = ? AND lease_owner = ?: a stale worker changes nothing
            } catch ( \Throwable $e ) {
                self::retry_later( $job, $e );   // same owner check; attempts + 1, next_run_at = now + min(6 h, 30 s × 2^attempts);
            }                                    // after 12 failures: state = 'failed', a review case and an alert
        }
    }

    private static function complete( object $job ): void {          // job key "complete:pay_…"
        $f = Fact::from_json( $job->fact );                           // the validated success, saved with the job
        Locks::order( $job->order_id, function () use ( $job, $f ) {  // one worker per order for the read and the write
            $order = wc_get_order( $job->order_id );
            $b     = Bindings::for_payment( $job->payment_id );
            if ( $order->is_paid() ) {                                // finished before a crash, or paid by another payment
                if ( $order->get_transaction_id() !== $b->payment_id ) Reviews::conflict( $order, $f );
                return;
            }
            $late = 'expired' === $f->session_status || (int) $b->revision !== Revisions::current( $order );
            if ( $late || $order->has_status( 'cancelled' ) || ! Stock::hold_again( $order ) ) {   // renew; false if gone (S99)
                LatePayments::decide( $order, $b, $f );               // the store's setting: fulfill if stock, refund, or review
                return;
            }
            if ( ! $order->has_status( [ 'pending', 'failed', 'on-hold', 'cancelled' ] ) ) {
                Reviews::open_for( $order, $f, 'paid while the order was ' . $order->get_status() );
                return;
            }
            Jobs::assert_owner( $job );                               // stop if another worker took the lease meanwhile
            $order->payment_complete( $b->payment_id );               // its true return value proves nothing (S96)
            $fresh = wc_get_order( $job->order_id );
            if ( ! $fresh->is_paid() || $fresh->get_transaction_id() !== $b->payment_id ) {
                throw new \RuntimeException( 'order not paid after payment_complete' );   // retried, then a review case
            }
        } );
    }
}

add_action( 'init', function () {       // wake-ups: jobs every minute, the feed every 5 minutes (R10)
    if ( ! function_exists( 'as_has_scheduled_action' ) ) return;
    if ( ! as_has_scheduled_action( 'payassist_run_jobs' ) )    as_schedule_recurring_action( time(), 60, 'payassist_run_jobs', [], 'payassist' );
    if ( ! as_has_scheduled_action( 'payassist_sync_events' ) ) as_schedule_recurring_action( time(), 300, 'payassist_sync_events', [], 'payassist' );
} );
add_action( 'payassist_run_jobs', [ Jobs::class, 'run_due' ] );
add_action( 'payassist_sync_events', function () {
    $c = payassist_connection();                                       // the connected store id and mode
    Locks::named( "payassist_sync_{$c->store_id}_{$c->mode}", function () use ( $c ) {   // one sync at a time
        $cursor = Checkpoints::get( $c->store_id, $c->mode );         // a checkpoint per store and mode, set at connect time
        do {
            $page = payassist_client()->events->list( [ 'after' => $cursor, 'limit' => 100 ] );   // oldest first
            foreach ( $page->data as $event ) \PayAssist\Woo\ApplyPayment::event( $event );       // the same inbox as pushes
            Checkpoints::advance( $c->store_id, $c->mode, $cursor, $page->next_cursor );   // compare-and-set; throws if not saved
            $cursor = $page->next_cursor;
        } while ( $page->has_more );
    } );
} );

A late success is never dropped, and late means more than a cancelled order. The job carries the verified fact, so it knows whether the session had expired when the money moved and which revision was paid. Every late case, every cancelled order and every case where the stock cannot be reserved again goes to LatePayments::decide(). It fulfills automatically only a pending order whose reservation it has just renewed; otherwise it creates one refund command or opens a review case, as the merchant's setting says, and it tells the merchant which. On the normal path the job checks the order afterwards instead of trusting payment_complete(), which returns true even when it changed nothing S96. A worker that pauses past its lease loses ownership, and the owner token stops it from finishing the job; the order lock stops a second worker from completing the order at the same time, but only while the lock's own database session lives (see the list at the end of this chapter). One limit stays: payment_complete() saves the paid status before it runs WooCommerce's hooks, so a crash between the two can skip a hook on the next run. Work the plugin owns, such as a warehouse call, therefore goes in its own job with its own key, not in a hook. By default Action Scheduler runs from WP-Cron and loopback requests S93, so a quiet site can run jobs late; for money paths, run its queue from a real system schedule with WP-CLI S94. The feed checkpoint belongs to one store and one mode, so moving from test to live starts a separate stream instead of sending a test cursor with a live key. WooCommerce's own webhooks run through WP-Cron and switch themselves off after five failed deliveries S75, which is why they are not used for payment truth. The backoff and the twelve-failure alert are illustrative numbers.

8 · Refunds from WooCommerce admin

// src/Refunds.php (excerpt)
// WooCommerce saves its refund record and then calls process_refund(); if the gateway returns false
// or an error, it deletes that record (S97). So the plugin keeps its own refund command row.
add_action( 'woocommerce_create_refund', function ( \WC_Order_Refund $refund ) {   // before WooCommerce saves it
    // The plugin's admin script puts one action id on the refund screen when it opens, so a
    // double-click or a resubmitted form carries the same id. Other callers get a fresh one.
    $action = sanitize_key( $_POST['payassist_refund_action'] ?? '' ) ?: wp_generate_uuid4();
    $refund->update_meta_data( '_payassist_action', $action );
    Refunds::$current = $refund;                                   // the same PHP request calls process_refund() next
} );

// src/Gateway.php (excerpt)
public function process_refund( $order_id, $amount = null, $reason = '' ) {
    $order  = wc_get_order( $order_id );
    $record = Refunds::$current;
    $minor  = Money::toMinor( $amount, $order->get_currency() );
    try {
        $cmd = Db::transaction( function ( \mysqli $db ) use ( $order, $record, $minor, $reason ) {
            Bindings::lock_order( $db, $order->get_id() );                         // one refund decision at a time per order
            // get or create: the same action id returns its saved command; different terms are refused
            $cmd = Refunds::get_or_create( $db, $record->get_meta( '_payassist_action' ), $order, $minor, $reason );
            if ( $cmd->created_now && Refunds::unresolved_other( $db, $order->get_id(), $cmd->command_id ) ) {
                throw new RefundBlocked( 'An earlier refund is still being confirmed.' );
            }
            return $cmd;                                                           // committed before any money moves
        } );
    } catch ( RefundBlocked $e ) {
        return new \WP_Error( 'payassist_refund', $e->getMessage() );             // nothing was sent; WooCommerce deletes its record
    }
    if ( ! $cmd->created_now ) {                                                  // a second submission of the same action
        return new \WP_Error( 'payassist_refund', __( 'This refund was already sent.', 'payassist' ) );   // WooCommerce deletes the extra record
    }
    return Refunds::send( $cmd );
}

public static function send( object $cmd ) {                                   // Refunds::send, also used by the recovery job
    try {
        $r = payassist_client()->refunds->create(
            [ 'payment' => $cmd->payment_id, 'amount' => $cmd->amount_minor, 'reason' => $cmd->reason,
              'client_reference' => $cmd->command_id ],                           // unique per payment forever (Appendix D)
            [ 'idempotency_key' => 'wc-refund-' . $cmd->command_id ] );
    } catch ( \PayAssist\Exception\OutcomeUnknown $e ) {
        return true;    // the command stays "sending"; a job asks again with the same client_reference until it knows
    }
    Refunds::record_result( $cmd->command_id, $r );                              // PayAssist refund id and status on the command
    return 'failed' === $r->status ? new \WP_Error( 'payassist_refund', $r->failure_reason ) : true;
}

Each refund the merchant asks for gets one action id when the refund screen opens, and becomes one command row, saved with its amount, reason and id before any money moves. A double-click or a resubmitted form carries the same action id, finds the same command and goes no further; WooCommerce deletes the extra record. The command id travels to PayAssist as client_reference, which the proposed API keeps unique per payment forever, not just for the seven days it keeps idempotency replays. So if PHP dies after PayAssist accepted the call, the recovery job can ask again with the same reference a day or a month later and get the same refund back, never a second one. While any refund on the order is unresolved, new refunds are refused, and a failed refund needs a new refund action. Events and reads carry the refund's client_reference, so they find their command even if they beat the POST response or WooCommerce deleted its own record. When refund.succeeded or refund.failed arrives, its job updates that command and its WooCommerce record. A refund that failed after WooCommerce already counted it puts the order on hold with a note that no money moved, for a person to correct. A refund started outside WooCommerce, for example in the PayAssist dashboard, gets one WooCommerce record with refund_payment set to false, once per refund id. No event ever starts a provider refund.

Today refunds happen in the provider's dashboard, and the plugin only records them in WooCommerce when the refund event arrives; it does not advertise refund support Today. Version 1 lets a merchant refund from the order screen as shown above.

What this sketch still leaves out

• The helper classes it calls. Each hides real rules: Commands saves the create command and advances the session generation under the order lock; Refunds::get_or_create() refuses a known action id with different terms; the admin script adds the refund action id to WooCommerce's refund screen.
• Fencing a stale worker. Locks::order() is a MySQL named lock, and it stops a second worker from completing the order only while the lock's own database session lives. If that session dies after the ownership check, a paused worker can still write through WooCommerce's connection while a new worker runs. A real implementation must fail closed at the order write itself; until then this is an open limit, and gate 2 must cut the lock's session right after the ownership check.
• Proving stock admission. Renewing WooCommerce's reservation is not proof that the stock stays allocated until completion: WooCommerce counts a reservation only while its order is pending or a checkout draft and before its deadline, so it does not protect a cancelled order, and a worker that pauses past the deadline can lose the unit. Until that proof exists, the sketch fulfills a late payment automatically only for a pending order whose reservation it has just renewed, and sends every other late success to a refund or a review case. Gate 2 must pause a worker after renewal until the deadline passes, sell the unit elsewhere and resume it.
• Parsing DB_HOST for a port or socket the way WordPress does, and TLS to the database.
• Admin screens for review cases, failed jobs and refund commands.
• Uninstall, data retention, and the personal data inside saved facts.
• Multisite installs.
• Every gate in Chapter 16. Gate 2 in particular must cut the database connection before the commit, between writes and during a refund send.