Headless storefronts (GraphQL)
Use Stripe Payment from an app or a custom frontend.
Background
Read this if your shop is used by something other than the standard OXID theme: a separate web storefront, a mobile app, a kiosk, a partner site. Such a frontend takes Stripe payments through the shop’s GraphQL API, while your shop keeps full control of orders, the Stripe account and the money.
Every order a headless frontend takes is a normal shop order with the Stripe payment method: same order management, same capture and refund, same webhook processing as orders from the OXID theme.
The frontend never receives a Stripe secret. It receives only the publishable key, and only over an encrypted exchange bound to the customer’s session. There is nothing to copy into the frontend.
After payment, customers can only be sent back to pages on origins you allow.
The order is finished by Stripe’s webhook. A customer who closes the app right after paying still gets the order.
Note
Module versions: Headless checkout requires Stripe Payment 3.4 or later and OXID Payment Base 1.3 or later.
Checkout for guests without a customer account requires Stripe Payment as of version 3.5 and OXID Payment Base as of version 1.5.
What your customers see
The frontend chooses the presentation for each checkout:
Mode |
What the customer sees |
Requirements |
|---|---|---|
Embedded |
The Stripe payment form inside the frontend’s own checkout page (Stripe Embedded Checkout) |
The publishable key – delivered automatically by the shop |
Hosted |
A redirect to Stripe’s checkout page, then back to the frontend |
None |
If the automatic key delivery is not available, a well-built frontend falls back to the hosted page by itself.
Note
The setting Use iframe instead of checkout button (see Choose the checkout presentation) only applies to the OXID theme. In a headless frontend, the frontend decides.
Set up the shop for a headless frontend
Prerequisites
Stripe Payment is installed and configured as described in Configuration: Stripe account connected, mode (test/live), capture mode.
The publishable key of the mode in use is set. This is the key the frontend receives.
The webhook is created and reachable over HTTPS (see Create webhook).
Procedure
Install and activate the OXID GraphQL modules oxid-esales/graphql-base and oxid-esales/graphql-storefront.
Without them, Stripe Payment still works for the OXID theme, but there is no API for a frontend.
Clear the GraphQL schema cache. On the server, in the directory of your OXID eShop, run:
vendor/bin/oe-console oe:graphql:cache-clearIn the OXID Docker SDK, the command is bin/oe-console.
Important
Repeat this step after every activation or update of Stripe Payment, OXID Payment Base or any other module that adds API calls. The API schema is cached on disk and the shop never clears it by itself. Without this step, an updated shop keeps answering with the old API.
Allow the frontend’s origins:
Go to .
Under Headless checkout (GraphQL, apps), enter every origin your frontends run on in Allowed return origins for headless clients, separated by commas or line breaks.
Example
https://shop.example.com, https://app.example.com, http://localhost:5173
An origin consists of scheme, host and port:
https://app.example.com:8443andhttps://app.example.comare two separate entries. Your shop’s own URL is always allowed. If the field is empty, only the shop itself is allowed.Save your settings.
If the frontend runs on a different domain than the shop, allow it to call the API (CORS for
/graphql/). This is a web server setting; ask your hosting partner.Give the frontend team the URL of your shop – and nothing else. The shop delivers the keys itself; the Stripe secret key, the OAuth token and the webhook secret never leave the module settings.
Test in Stripe test mode first: Pay with a test card in the frontend, then check that
the order appears under with the Stripe payment method,
the Stripe Dashboard shows the test payment,
the webhook was delivered.
Then switch the module to live mode.
Result
The frontend can start Stripe payments through the GraphQL API. The resulting orders are processed in your shop like any other Stripe order.
Responsibilities: shop and frontend
In the shop (you) |
In the frontend (the developers) |
|---|---|
Stripe account, secret key, webhook secret, capture mode |
Which presentation to offer (embedded or hosted) |
Which origins customers may be sent back to |
The look of the checkout page |
The order, its number and status, capture and refund |
Showing the order number and status to the customer |
The publishable key, handed over encrypted per session |
Requesting it when the payment step opens |
The log policy: no provider texts, no full return URLs and no tokens in the shop log. Set zend.exception_ignore_args=On in PHP (the production default). |
Logging without query strings in its own web server |
Orders, capture and refunds
Nothing changes compared to orders from the OXID theme; see Operation.
With manual capture, a headless order is created as authorized and is paid once you capture it.
Cancelled or abandoned payment attempts leave no finished order: the frontend retires them, and the order created at the start of the checkout is cancelled.
Guest checkout
Note
Available as of Stripe Payment 3.5 and OXID Payment Base 1.5.
Customers without an account can pay as well. The frontend sends their e-mail address and invoice address – and optionally a delivery address – together with the start of the checkout. The shop keeps a guest account without a password for that e-mail address and reuses it for the next guest order with the same address.
If the e-mail address belongs to a registered customer account, the checkout is refused and the account is not changed. The frontend asks the customer to log in.
Known limitation: The order is currently shipped to the invoice address, also when the guest has entered a different delivery address.
Troubleshooting
Symptom |
Cause |
Solution |
|---|---|---|
The frontend reports return_url_rejected / origin_not_allowed. |
The frontend’s origin is not allowed. |
Add it to Allowed return origins for headless clients and clear the GraphQL schema cache. |
The frontend shows Stripe’s hosted page although the embedded form was expected. |
The publishable key of the current mode is empty or not a pk_… key – or OXID Payment Base is too old to deliver the key. |
Set the publishable key; update OXID Payment Base and reactivate the modules. |
The order stays “pending” in the frontend. |
The webhook has not reached the shop yet, or it is not registered. |
Create the webhook; check the delivery errors under . The shop must be reachable over HTTPS. |
Cannot query field “stripeCheckoutStart” |
The GraphQL modules are not installed or not active, or Stripe Payment was activated before them. |
Install and activate graphql-base and graphql-storefront, then reactivate Stripe Payment. |
Cannot query field “…” for a documented call although the module is active |
The GraphQL schema cache still holds the schema from before the activation or update. |
Run vendor/bin/oe-console oe:graphql:cache-clear and repeat the call. |
A guest receives account_exists. |
The e-mail address belongs to a registered customer account. |
The customer logs in. Nothing was changed on the account. |
A guest receives guest_details_required. |
The frontend sent no or incomplete guest details (e-mail address, invoice address). |
Fix the frontend’s form; the error message names the missing field. |
Limitations
Only Stripe’s hosted page and Stripe Embedded Checkout are supported; custom Stripe Elements are not.
For developers: The API (mutations, call sequence, error codes) is described in the OXID Payment Base developer documentation, chapter Headless Checkout (GraphQL).