Integrating InstaSettle with a decoupled WooCommerce storefront using the Store API.
This is the Headless WooCommerce Developer Integration Guide for InstaSettle. It is for development teams building a headless or decoupled WooCommerce storefront who want to integrate InstaSettle as a payment method.
You will use the WooCommerce Store API to manage the cart and initiate checkout — the InstaSettle plugin handles the rest.
Plugin installation: This guide assumes the InstaSettle for WooCommerce plugin was installed from one of the official distribution sources: instasettle.net or the Merchant Dashboard.
Important — read this before writing any integration code:
Your frontend never interacts directly with payment providers. You do not need to build payment session logic, initialize crypto wallets, or configure provider SDKs. The InstaSettle plugin handles all of this automatically.
Here is what happens the moment your checkout POST reaches WooCommerce:
The InstaSettle plugin registers as a WooCommerce payment gateway. When your checkout request specifies instasettle-stripe as the payment method, the plugin takes over — your code is done at this point.
The plugin constructs a payment session using the merchant configuration — wallet address, currency conversion, and callback URL. No frontend involvement is required for this step.
The plugin calls the InstaSettle infrastructure to generate a unique payment address linked to your merchant wallet. Developers do not need to manage provider SDKs or pass routing parameters from the frontend.
The plugin generates a checkout session and returns a redirect URL pointing to the InstaSettle hosted checkout environment at pay.instasettle.net. Your only job is to send the customer's browser to this URL immediately.
The customer arrives at the InstaSettle hosted checkout (pay.instasettle.net), completes their card payment, and USDC settles on-chain directly to the merchant wallet on Polygon.
A server-side callback from InstaSettle updates the WooCommerce order status. No polling or frontend action required. The payment is also logged to the Merchant Dashboard if an API key is configured.
The takeaway for developers: Your integration has exactly two responsibilities — (1) call the WooCommerce Store API in sequence to build the cart and submit checkout, and (2) redirect the customer to the URL the plugin returns. Everything else — payment routing, currency conversion, session handling, and settlement — is handled by InstaSettle infrastructure.
In a headless setup, your frontend (React, Next.js, Vue, or similar) communicates with WooCommerce exclusively through REST API calls. The InstaSettle plugin operates as a standard WooCommerce payment gateway on the backend — your frontend simply selects it as the payment method at checkout, and the plugin returns a redirect URL that sends the customer to the hosted payment flow.
This means your frontend never needs to handle crypto logic, wallet addresses, or payment provider SDKs. InstaSettle takes care of all of that behind the scenes.
Your React, Next.js, Vue, or custom frontend. Manages the shopping experience and calls the Store API.
The standard headless API layer. Handles cart, customer data, and order creation.
Intercepts checkout, generates a payment address, and returns a redirect URL to pay.instasettle.net.
Customer completes card payment at pay.instasettle.net. USDC settles to merchant wallet on Polygon.
Before starting your integration, make sure the following are in place. Missing any of these is the most common cause of checkout failures.
| Requirement | Details & Notes |
|---|---|
| WooCommerce installed | WooCommerce must be installed, activated, and configured with at least one product and a valid store setup. |
| InstaSettle plugin | Install the InstaSettle for WooCommerce plugin from instasettle.net. After installation: activate the plugin, configure your USDC wallet address and API key in WooCommerce → Settings → Payments. Perform a test transaction using standard WooCommerce checkout before attempting a headless integration. |
| Store API enabled | The Store API (wc/store/v1) is included with WooCommerce 6.9+. No additional plugin required. Confirm it is accessible at /wp-json/wc/store/v1/cart before proceeding. |
| Store API publicly reachable | The Store API must be reachable without interactive WordPress login. If behind Basic Auth, a WAF, or a reverse proxy, ensure /wp-json/wc/store/v1/* is whitelisted for unauthenticated access. |
| HTTPS required | Both your WooCommerce backend and headless frontend must be served over HTTPS. The InstaSettle hosted checkout requires a secure origin. |
| Cookie persistence | Your frontend must preserve and resend WooCommerce session cookies (wp_woocommerce_session_*) on every request. Without this, the cart resets between calls. See Section 5. |
| pay.instasettle.net accessible | The browser must be able to redirect to the InstaSettle hosted checkout domain. Ensure pay.instasettle.net is not blocked by CSP headers, firewall rules, or proxy configuration. |
| Inbound callbacks not blocked | WooCommerce must be able to receive inbound HTTP callbacks from InstaSettle infrastructure to update order statuses. Ensure your hosting does not block inbound POST requests from external IPs. |
When submitting the checkout request via the Store API, you must reference the InstaSettle gateway using its exact payment method identifier. Using a different string will result in WooCommerce returning a payment method not available error.
instasettle-stripe
This identifier is passed as the payment_method field in your POST /wc/store/v1/checkout request body. It must match exactly — including the hyphen and lowercase.
The following steps represent a complete headless checkout integration from cart creation through payment redirect. Each step corresponds to one Store API call. Implement them in order — skipping or reordering steps will cause session or cart errors.
Before adding any items, ensure a WooCommerce cart session exists.
POST /wc/store/v1/cart
Host: yourstore.com
Content-Type: application/jsonSession cookie: The response from this call will set a wp_woocommerce_session_* cookie. You must capture and resend this cookie on every subsequent Store API request. If using fetch() or axios in the browser, set credentials: "include". If making server-side calls, capture the Set-Cookie header and forward it manually.
Add the customer's selected product(s) to the cart. Repeat for each distinct product.
{
"id": 123,
"quantity": 1
}The id field must be the WooCommerce product ID (integer), not a slug or SKU. For variable products, use the variation ID. Retrieve product IDs from the WooCommerce Products REST API at /wp-json/wc/v3/products.
WooCommerce requires a billing address to process a checkout. At minimum, provide first_name, last_name, email, and country. The InstaSettle plugin uses the email for the payment provider's KYC flow.
{
"billing_address": {
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"country": "US"
}
}For digital-only products, the four fields above are sufficient. For physical goods, also include a shipping address and select a shipping rate before checkout.
{
"billing_address": {
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"address_1": "123 Main St",
"city": "Austin",
"state": "TX",
"postcode": "78701",
"country": "US"
},
"shipping_address": {
"first_name": "Jane",
"last_name": "Smith",
"address_1": "123 Main St",
"city": "Austin",
"state": "TX",
"postcode": "78701",
"country": "US"
}
}Shipping rate selection: After setting the shipping address, retrieve available rates with GET /wc/store/v1/cart (includes a shipping_rates array). Select a rate with POST /wc/store/v1/cart/select-shipping-rate before checkout. Skipping this returns a “no shipping rate selected” error.
Tax calculation: WooCommerce calculates taxes automatically based on the address and store settings. The amount the customer pays at the InstaSettle hosted checkout includes any WooCommerce-calculated taxes — no additional tax handling is required in your frontend.
This is the key step. Submitting checkout with payment_method set to instasettle-stripe triggers the InstaSettle plugin to create a payment session and return a redirect URL.
{
"payment_method": "instasettle-stripe"
}{
"order_id": 1234,
"status": "pending",
"payment_result": {
"redirect_url": "https://pay.instasettle.net/process-payment.php?address=0x...&amount=49.99&provider=hosted&email=jane%40example.com¤cy=USD"
}
}The redirect_url is time-sensitive: Do not cache or store the redirect_url. Redirect the customer immediately after receiving it. The URL contains session parameters that expire — presenting a stale URL will result in a session error.
Once you have the redirect_url, send the customer's browser to it immediately. Do not attempt to load this URL in an iframe — redirect the full browser window.
// Use the redirect_url exactly as returned — do not modify it
window.location.href = response.payment_result.redirect_url;// In a Next.js API route or server action:
res.redirect(302, response.payment_result.redirect_url);
// Or in App Router:
redirect(response.payment_result.redirect_url);Never iframe the checkout: The InstaSettle hosted checkout and payment provider pages must open in the full browser window. Iframing will break security requirements and result in checkout failures. Always use a full-page redirect.
Use the URL exactly as returned: Do not modify the URL or its query parameters. Any modification will invalidate the payment session.
This is the most common source of integration issues in headless WooCommerce setups. WooCommerce uses server-side sessions to track cart state. Your frontend must capture the wp_woocommerce_session_* cookie on the first request and send it back on every subsequent request.
const response = await fetch(
'https://yourstore.com/wp-json/wc/store/v1/cart/add-item',
{
method: 'POST',
credentials: 'include', // Required: sends and receives cookies
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ id: 123, quantity: 1 })
}
);Cross-origin note: If your frontend domain differs from your WooCommerce domain, configure WooCommerce to allow cross-origin requests and set appropriate CORS headers. The SameSite cookie attribute may need to be set to None with Secure.
// Receive the cookie from the browser request
const cookie = req.headers.cookie;
// Forward it to WooCommerce
const wcResponse = await fetch(
'https://yourstore.com/wp-json/wc/store/v1/checkout',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Cookie': cookie, // Forward the session cookie
},
body: JSON.stringify({ payment_method: 'instasettle-stripe' })
}
);
// Forward the Set-Cookie header back to the browser
const setCookie = wcResponse.headers.get('set-cookie');
if (setCookie) res.setHeader('Set-Cookie', setCookie);What happens if cookies are not persisted: WooCommerce will treat each request as a new anonymous session. The cart will appear empty, customer data will not be attached, and checkout will fail with a “cart is empty” error. If you see these errors, cookie forwarding is almost always the cause.
Once the customer completes their card payment at the InstaSettle hosted checkout, the order status in WooCommerce updates automatically via a server-side callback. Your frontend does not need to poll for status.
| Status | What It Means |
|---|---|
| Pending | Checkout submitted, order created. Customer has been redirected to the payment page but has not yet completed payment. |
| On Hold | Payment initiated but on-chain settlement has not yet confirmed. Some provider flows set this intermediate status. |
| Processing | On-chain USDC settlement confirmed. Payment is complete. This is the primary success status — trigger fulfillment actions here. |
| Completed | Order has been fulfilled. Typically set manually by the merchant or by a fulfillment plugin after Processing. |
| Failed | Payment not completed. Customer abandoned checkout, card was declined, session expired, or the paid amount was less than 60% of the order total. |
Post-payment redirect behaviour: Most payment provider flows do not redirect customers back to your storefront automatically. Design your post-checkout UX to show a “processing payment” or “order received” state immediately after the redirect. WooCommerce order status updates server-side via callback regardless of whether the customer returns.
The InstaSettle for WooCommerce plugin is the same plugin for all integration types — classic WooCommerce checkout, WooCommerce Blocks, and headless storefronts. No special build is required for a headless integration.
Work through these before contacting support — most can be resolved without any changes to the InstaSettle plugin.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Cart returns empty after add-item | Session cookie not persisted | Add credentials: 'include' to all fetch calls (browser) or manually forward the wp_woocommerce_session_* cookie on server-side requests. |
| 400 error on checkout POST | Cart is empty or customer data not set | Confirm the session cookie is present. Confirm add-item succeeded. Confirm update-customer was called before checkout. |
redirect_url missing in response |
Plugin not activated or gateway not enabled | Go to WooCommerce → Settings → Payments and confirm InstaSettle Gateway is active. Check that the wallet address is configured. |
| 404 or session expired at checkout page | Stale redirect_url or URL was modified | Redirect immediately after receiving the URL. Do not store, reuse, or modify query parameters. |
| Order stuck in Pending forever | Inbound callback blocked | Check: (1) Wordfence firewall rules, (2) WAF/Cloudflare blocking POST to /wp-json/instasettle/, (3) server error logs for 403/503, (4) temporarily disable security plugins and retry. |
| CORS error on Store API call | Cross-origin requests not configured | Add your frontend domain to allowed origins, or route Store API calls through your server to avoid cross-origin issues entirely. |
| SameSite cookie warning | Session cookie not configured for cross-origin | Set SameSite=None; Secure on the session cookie at the server level. Contact your hosting provider if needed. |
Run through this checklist before going live. Every item represents a real failure mode discovered in headless integrations.
/wp-json/wc/store/v1/cart/wp-json/wc/store/v1/*)wp_woocommerce_session_*) persisted and forwarded on all Store API callspayment_method: 'instasettle-stripe' submitted exactly in checkout POSTredirect_url performed immediately after receiving it (no caching or modification)pay.instasettle.net accessible from the browser — not blocked by firewall, CSP, or proxy| Endpoint | Purpose |
|---|---|
POST /wc/store/v1/cart | Initialize or retrieve the cart session. |
POST /wc/store/v1/cart/add-item | Add a product to the cart by WooCommerce product ID. |
POST /wc/store/v1/cart/update-customer | Set billing address and customer email on the cart. |
POST /wc/store/v1/checkout | Submit checkout. Returns order_id and redirect_url. |
| Item | Value |
|---|---|
| Payment method identifier | instasettle-stripe |
| Hosted checkout domain | pay.instasettle.net |
| Merchant dashboard | app.instasettle.net |
| Plugin download | instasettle.net/#download |
| Compatible with | Classic WooCommerce checkout, WooCommerce Blocks, and headless storefronts |
| Session cookie name | wp_woocommerce_session_* (suffix varies by site) |
| Minimum order total | $2.00 USD |
| Settlement | USDC on Polygon, directly to merchant wallet |
The standard InstaSettle plugin works with all WooCommerce setups: Classic checkout, WooCommerce Blocks, and headless storefronts using the Store API. No different version or build is required.