# Taking payments PhantomStudio does not support

> PhantomStudio's checkout bridge is built for three payment methods, Stripe, PayPal and bank transfer, which covers most shops. Adding Polish instalments through Przelewy24 took one failed attempt with the official plugin, a near miss with its sandbox, and in the end a small bridge of my own.

- URL: https://www.443monkeys.com/blog/payments-outside-phantomwp/
- Published: 13 November 2026
- Author: 443 Monkeys
- Category: Strategy, Technical
- Tags: Payments, Przelewy24, WooCommerce, PhantomStudio, Astro, Headless

## The short version

A headless shop built with PhantomStudio takes payments through PhantomStudio's own checkout bridge, which is built for three methods: Stripe, PayPal and bank transfer. Each has code on both the storefront and the WordPress side, so other WooCommerce gateways appear in its configuration as unsupported, and an order placed with one ends with "Selected payment method is not available". For most shops those three are enough, because Stripe alone covers cards, Apple Pay, Google Pay, BLIK, Przelewy24 transfers and Klarna.

It was not enough for one shop I run. Its two most expensive products cost about €2,500 and €5,800, and Polish customers expect to buy items like that in instalments through a local provider. Przelewy24, one of the largest Polish payment operators, offers exactly that as "Przelewy24 Raty" (raty is Polish for instalments), payment method 303.

It can be done, though the provider's WordPress plugin was the wrong route. What works is a bridge in three parts: the order is created through PhantomStudio as a placeholder Stripe order; the storefront's own server talks to Przelewy24's API; and a 200-line WordPress plugin relabels the order, records every Przelewy24 identifier on it and marks it paid once Przelewy24 has confirmed the money. The first real test in Przelewy24's sandbox was paid and recorded 21 seconds after the order was placed.

I know payments from the strategy and product side, having worked in lending and banking, so I was confident that this was possible in principle. I am not a payments engineer. I worked through the build with the operator's documentation, a sandbox account and an AI coding agent, and what follows is what held for me; check it against your own setup before relying on it.

---

## Why a local method is worth the effort

Stripe and PayPal are the defaults in most headless starter kits, but payments remain local. In the United States and the United Kingdom, an expensive purchase online often goes on a credit card. In Poland most people pay by debit card, BLIK or bank transfer, and expensive items are often bought in instalments from a local lender instead. Around the world, and especially in emerging markets, such lenders assess customers in their own market, support them in the local language and charge no annual card fee. Other markets have their own habits, such as iDEAL in the Netherlands, Pix in Brazil and UPI in India; Stripe covers some of these well and others only in part, and a local instalment product is rarely on its list. My years in lending showed me how often an option like that decides whether a large purchase happens at all.

A connector's list of supported methods is a starting point rather than a boundary. Most payment operators publish a REST API with a sandbox, and the pattern is broadly the same everywhere: register a transaction, send the customer to the operator, receive a signed notification and verify it. This article records one such integration, to show that the limitation can be worked round by someone curious enough to try.

## What PhantomStudio pays for you

PhantomStudio connects an Astro storefront to WooCommerce. The cart lives in the browser; at checkout the storefront sends the order to a PhantomStudio endpoint in WordPress, which creates it in WooCommerce, and then the storefront collects the money. For Stripe it creates a PaymentIntent and confirms it in the page; for PayPal it renders PayPal's buttons; for bank transfer it shows the thank-you page and leaves the order on hold.

Each of those three has code on both sides of the bridge. A WooCommerce gateway installed in WordPress gets none of that. The bridge lists it with `supported: false`, the storefront hides it, and if an order names it anyway, PhantomStudio does not create the order. That is a reasonable design: a gateway plugin expects to run WooCommerce's own checkout page, and PhantomStudio cannot know what each one needs.

The practical consequence is that any payment method outside those three needs code that the storefront owner writes.

## The first attempt: through the plugin

Przelewy24 publishes a WooCommerce plugin, and my first attempt, earlier in the month, used it for PayPo, a Polish buy-now-pay-later service, something like a local Klarna, which shops can offer through the Przelewy24 payment gateway. The plugin can show selected methods as separate gateways, so PayPo appeared in WooCommerce as `p24-online-payments-317`. The plan was to let PhantomStudio create the order, switch it to that gateway in WordPress, and call the gateway's own payment function to get the redirect to PayPo.

It went wrong in stages. My helper plugin hid PayPo whenever there was no cart to inspect, and a headless order has no WordPress cart, so every attempt failed with "Selected payment method is not available". With that fixed, PhantomStudio itself still did not accept the gateway, and the only way through was to create the order as a Stripe order and relabel it afterwards. The separate PayPo gateway also worked only while Przelewy24's main method picker stayed switched on in WooCommerce, so more code was needed to hide the picker. Then I looked at the numbers: PayPo's limit on the account was, as far as I could tell, below both products it was meant for, so it would never have appeared at checkout. I abandoned it.

## Why I stopped using the plugin

When I came back to instalments, the plugin route had three more problems.

1. **I could not read its code.** The plugin is not on wordpress.org, and the administrator access I had could read settings but not plugin files. I would have been calling a payment function without knowing what it sends to Przelewy24 or how it handles the return. I could have asked Przelewy24 for the package or copied it off the server and read it, but that would have left the next two problems in place, and I preferred owning a short plugin to auditing someone else's.
2. **It needs a public hole in WordPress.** The plugin receives Przelewy24's payment notification on WordPress. On the shops I run, WordPress sits behind Cloudflare and is closed to the public, in the way I described in [an earlier article](/blog/headless-wordpress-security/), and every exception in that wall is one more thing to maintain.
3. **Its sandbox switch is global.** To test, the plugin's sandbox mode was switched on in WooCommerce. Once my PayPo helper had been removed, nothing hid Przelewy24's options on WordPress's own checkout page, which customers still use for subscriptions. Until I noticed, a customer on that page could have chosen Przelewy24, paid in the sandbox, where no money moves, and received a real order marked as paid. Nobody did; the plugin is now deactivated.

The third problem decided it. A payment method that can be switched into test mode for every customer at once is a risk I did not want, and the alternative, talking to Przelewy24's API directly, turned out to be smaller than the workarounds.

## How the bridge works

![The checkout creates the order through PhantomStudio as a Stripe placeholder. A Vercel route asks a small WordPress plugin to check and relabel the order, registers the transaction with Przelewy24 using method 303, and sends the customer to Przelewy24's application page. Przelewy24 notifies the route, the route verifies the transaction, and only then does WordPress mark the order paid and store Przelewy24's identifiers. On the customer's return, the thank-you page asks the route to check the transaction directly.](https://www.443monkeys.com/_astro/fig-01-payment-bridge.BwoCc9Q2_1s9Muq.png?dpl=dpl_FRXEgMtgSN2NHXhzd4KXShRjCjki)
*Fig. 01: The six steps of an instalment payment. Przelewy24's keys never leave the storefront's server, and WordPress marks nothing paid until Przelewy24 has confirmed the transaction.*

There are six steps, and each part does one job.

1. **The order, as a placeholder.** The checkout creates the order through PhantomStudio exactly as it would for Stripe, with `payment_gateway: 'stripe'`. No Stripe payment is started. Raty is offered only when the cart contains one of the two products, and the phone number becomes required, because the lenders ask for it.
2. **Prepare.** A server route on Vercel, `/api/payments/p24/register`, calls the WordPress plugin. The plugin checks the order key, that the order is unpaid, in złoty (PLN) and contains an eligible product, then switches the payment method to Przelewy24 Raty and opens a new session with an ID such as `shop-10231-x7Kd2mQp9a`.
3. **Register.** The route registers the transaction with Przelewy24, naming method 303 so that the customer goes straight to the instalment application rather than a list of payment methods. Przelewy24 returns a token, and the customer is redirected to its page.
4. **Apply.** The customer fills in the application on Przelewy24's site, and a lender decides. That can take minutes.
5. **Notify and verify.** Przelewy24 reports the payment to `/api/payments/p24/status`. The route checks the signature, then calls Przelewy24's `verify` endpoint, which is what turns a notification into a confirmed payment.
6. **Complete.** Only after verification does the route ask WordPress to mark the order paid. The plugin refuses if the amount differs from the order total, and leaves a note instead.

Every message to Przelewy24 is signed with a SHA-384 hash of a small JSON object that includes a secret, the CRC key. The order of the fields matters, and the JSON must not escape slashes or Polish characters; JavaScript's `JSON.stringify` already behaves that way.

```ts
// Registration signature (Przelewy24 REST API v1)
const sign = createHash('sha384')
    .update(JSON.stringify({ sessionId, merchantId, amount, currency, crc }))
    .digest('hex');
```

The WordPress side is a plain plugin with three REST routes, each guarded by a shared key in a request header that WordPress compares with a constant in `wp-config.php`. The heart of it is the last route:

```php
if ((int) $r->get_param('amount_minor') !== shop_raty_amount_minor($order)) {
    // The live shop writes this note in Polish, for the people who run it.
    $order->add_order_note('Przelewy24 Raty: the amount from P24 does not match the order. NOT marked as paid.');
    return new WP_Error('shop_amount', 'Amount mismatch', ['status' => 409]);
}
$order->update_meta_data('_p24_order_id', $p24_order);
$order->payment_complete($p24_order);
```

The amount WordPress compares is the one Przelewy24 signed in its notification, or reported for the session, and then confirmed through `verify`; the browser never sends an amount. Completion is also idempotent. The notification and the return check described below can arrive at the same moment, so WordPress takes a database lock per order, reads the order again inside it, and treats a second call for the same transaction as already done. The order is paid once, and the customer receives one order confirmation.

Sandbox keys on the live site would carry the same risk that made me drop the plugin, so two checks now guard against it. The storefront switches instalments off when a production deployment on Vercel has the sandbox flag set, and logs why. The WordPress plugin refuses to prepare or complete a sandbox payment unless a test constant is set in `wp-config.php`; because this shop has a single WordPress for testing and for customers, the constant is set only while a test runs. Each order also records which environment paid it.

One more route covers the return. When the customer comes back, the thank-you page asks `/api/payments/p24/check`, which looks the session up at Przelewy24 and settles the order if the money is there. That makes the flow independent of when the notification arrives, and it made testing possible on a local machine, which Przelewy24's servers cannot reach. Until the payment is confirmed, the page says that the application is in progress and keeps the cart, so that a customer who abandons the application can go back and pay another way.

## Choosing what can be bought in instalments

Building the bridge myself had a benefit I had not planned for: the shop decides which products qualify. A payment plugin usually offers its methods for any cart within the lender's limits. Here the list is explicit, two product IDs, and it is used in three places: the "Kup na raty" (buy in instalments) button appears only on those two product pages, the checkout offers instalments only when one of them is in the cart, and WordPress refuses to prepare an instalment payment for any other order.

That keeps the rest of the shop clean. A €10 serum does not need a finance offer next to its price, and an instalment button on every product page would suggest that the shop depends on credit to sell. Shown only on the two products where it helps, the option reads as a service for a large purchase.

It also leaves room to change the rule without touching the payment code. The same check could use a price threshold, a category, a minimum basket or a campaign with an end date, and a second lender could be offered for a different range of products. The rule is a short list in the storefront and in the plugin, and those are the only places it has to change.

## Finding a transaction later

A payment that only one system knows about becomes a problem the first time a customer calls. Each instalment order therefore carries Przelewy24's identifiers in WooCommerce:

- the transaction ID is Przelewy24's own order number, the one its panel searches by;
- a "Przelewy24" box on the order screen shows the session ID, the order number, the method, the transfer title and whether the payment came from the sandbox or production;
- the order notes record each step, from "customer sent to the application" to "payment confirmed (verify OK)", with the same numbers;
- the order list search finds an order by any of them.

The test order shows the result, with the numbers changed here: status "processing", paid 21 seconds after it was placed, transaction 1234567890, title `P24-ABC-DEF-GHI`, environment sandbox.

## What went wrong

None of these broke the live shop, and most of them were mine.

1. **The credentials would not authenticate.** The sandbox keys came in a text file with Windows line endings, and my first parser kept the carriage return at the end of each value. Przelewy24 answered 401 until the parser stripped it.
2. **The agent printed the keys.** While checking the format of that file, the AI agent I worked with printed its contents. They were sandbox keys, so nothing was lost, but production keys now go only into files that are read by scripts which never echo them.
3. **The bot check failed on localhost.** The checkout uses Cloudflare Turnstile, and its key is registered for the shop's real domains, so the widget turned red on the development machine. For the test, the development copy used Cloudflare's published test keys, which always pass, and the real ones went back afterwards. I did not try to get round the check itself.
4. **"This content is blocked."** The first real attempt ran inside PhantomStudio's editor preview, which is a frame, and Przelewy24, like every payment operator, refuses to load inside one. The same test passed in a normal browser tab. Customers never see the frame, so only testing was affected.
5. **The test order was real.** There is only one WordPress, so the sandbox order took the product off the stock count, sent the shop's "new order" emails and was logged as a purchase in the mailing tool. It has to be cancelled before it is deleted, so that WooCommerce puts the stock back.
6. **The shop's "new order" notification went out twice.** This is the internal e-mail WooCommerce sends to the shop; the customer's confirmation went out once. I have not yet found out why. It was not a double completion, because the log shows a single check call and the notification never reached my machine, and one ordinary Stripe order will show whether the bridge is involved at all.
7. **The payment option was called "Credit Card (Stripe)".** That is WooCommerce's default title, and it only became visible once there were two options to choose between. Stripe offers far more than cards on this shop, so the option is now "Płatność online" (online payment), with the methods listed underneath, and the separate Przelewy24 transfer inside Stripe is described as a transfer, so that it is not confused with instalments.
8. **A second review found three gaps.** As with [the security work](/blog/headless-wordpress-security/), I asked for a second review after the build, and it found problems the sandbox test could not show. Nothing stopped the notification and the return check from completing the same order twice; the lock above came from that. The review also asked what happens when a lender's decision arrives for an order that can no longer be paid. WooCommerce's automatic cancellation of unpaid orders does not reach these orders, because it applies only to orders from its own checkout, but a pending order can still be cancelled by hand during a clean-up, and my first version would then have answered "already done" and dropped the payment. Such a payment is now recorded with a warning note and an e-mail to the shop, and the plugin keeps instalment orders out of the automatic cancellation in case that rule ever reaches them. The third gap was the sandbox, covered in the bridge section above.

## What this does not cover

Refunds are not wired up. The refund button in WooCommerce does nothing for these orders, and a refund has to be issued in Przelewy24's panel and recorded in WooCommerce by hand. An abandoned application leaves an unpaid order behind. It holds no stock, because stock is reduced only when an order is paid, and WooCommerce does not cancel it automatically, so such orders are cleared by hand, as abandoned card orders on this headless shop are. The test constant that allows sandbox payments is also set and removed by hand. The list of eligible products lives in two places, the storefront and the WordPress plugin, and both have to change together.

For now the button says only "Kup na raty" (buy in instalments), with a note that the lender decides. Przelewy24 offers an [instalment calculator](https://www.przelewy24.pl/metody-platnosci/przelewy24-raty) that could show a monthly amount on the product page. That is the next thing I want to look at, together with the Polish rules on advertising consumer credit, which apply once a page quotes monthly costs.

## Handing the legwork to an AI coding agent

An AI coding agent such as Claude Code can do nearly all of this, including the sandbox test, provided a person handles the parts that involve money and accounts: opening the Przelewy24 account, installing the WordPress plugin and its key, adding the variables in Vercel and choosing when to switch to production. The prompt below is the one I would use today; the `<…>` placeholders need replacing.

```text
Goal: offer <provider> <method> on my headless WooCommerce shop (Astro on Vercel, PhantomStudio
checkout bridge), for <products> only. PhantomStudio's bridge supports Stripe, PayPal and bank transfer only,
so build a bridge rather than using the provider's WordPress plugin.

How to work:
1. Read the provider's REST API docs and confirm, against the SANDBOX, that my test keys
   authenticate and that method <id> exists. Never print keys: read them from <file> in a
   script that does not echo values (watch for CRLF line endings).
2. Order: create it through PhantomStudio as 'stripe' (placeholder, no Stripe payment started).
3. WordPress plugin with REST routes guarded by a shared key header (constant in wp-config):
   prepare (check order key, unpaid, currency, eligible products; set the payment method and
   title; new session ID), state, and complete (amount must match; payment_complete with the
   provider's transaction ID; store every provider ID as order meta, show it on the order
   screen, make it searchable, add an order note per step). complete must be idempotent:
   take a lock per order, re-read it, and treat a second call for the same transaction as
   done (no second e-mail). Exempt these orders from WooCommerce's unpaid-order cancellation;
   if money arrives for an order that can no longer be paid, record it and alert me.
4. Storefront server routes: register (signed, method fixed, return URL with order ID and key),
   status (check signature, verify with the provider, then complete) and check (on the
   customer's return, ask the provider by session and settle if paid). Mark nothing paid
   before the provider's verify call succeeds.
5. Checkout: show the method only for eligible carts, never as the default unless a
   "buy in instalments" button sent the customer; make the phone number required.
   Thank-you page: "application in progress" until paid; keep the cart until then.
6. Test end to end in the sandbox in a normal browser tab (payment pages refuse frames).
   Tell me the test order numbers so I can cancel them; they reduce stock and send emails.
7. Guards: the storefront refuses sandbox keys on a production deployment, and the plugin
   refuses sandbox payments unless a test constant is set in wp-config.php.
8. Do not commit or push. List the files changed and the environment variables to set, and
   remind me that production must run with production keys.

Never: print keys, weaken signature checks, disable bot protection on the live site, or
change WordPress, Vercel or provider settings without asking me first.
```

---

## The broader point

A connector that pays orders for you defines what a shop can sell, and its list of supported methods reflects someone else's priorities. Customers in many markets pay in ways that list leaves out. In my case the gap was smaller than it looked: one API, one signature scheme and a few hundred lines of code across the storefront and WordPress. That code takes on the jobs the connector used to do, such as checking amounts, recording identifiers and deciding when an order is paid. The official plugin would have been quicker to install, but I could not see what it did, and its sandbox switch nearly let test payments through on the live checkout.

It is worth questioning a tool's limits before treating them as the shop's limits. Payments look intimidating from outside, but the mechanics are documented, every serious operator offers a sandbox, and a curious person with a test account can find out whether a method is within reach before deciding that it is not.
