Custom REST API launch: build a FoxPay checkout without a commerce plugin

Not every merchant should be forced through a plugin. WooCommerce is the fastest path for many shops, but agencies, headless commerce teams, B2B portals, marketplace operators, and ERP-connected backends often need a more direct integration model. The FoxPay REST API is built for that pattern: the merchant backend creates a payment session, FoxPay handles the hosted checkout and payment handoff, and the merchant system reconciles the final payment state through backend events.

That framing matters. The API is not a tiny developer toy for dropping a button onto a page. It is an integration path into payment infrastructure: merchant context, payment-session creation, method selection, checkout URL generation, status handling, webhook reconciliation, public documentation, and an OpenAPI contract. That is useful for ordinary merchants that want a clean backend-controlled checkout. It is even more important for regulated or hard-to-place merchants, where payment acceptance is an operating process, not only a front-end experience.

The model: backend-driven, hosted checkout

The core flow is intentionally familiar. Your system owns the order. It calculates the amount, currency, cart, tax, discounts, and internal references. Your server then calls POST /payments/initialize. FoxPay creates a payment session and returns a paymentUrl. The buyer is then redirected from your shop, portal, or app into FoxPay's hosted checkout.

This separation keeps the integration practical. You do not move sensitive payment logic into browser code, and you do not have to build bank or provider handoff flows yourself. At the same time, your backend keeps control over the commercial workflow. Your system decides when an order is payable; FoxPay creates the payment session and checkout handoff; your backend receives and reconciles the final status.

POST /payments/initialize: the important details

Initialization starts the payment process. It does not prove that a payment has succeeded. A sanitized request uses the established concepts from the FoxPay documentation:

POST https://app.foxpay.it/api/payments/initialize
Authorization: Bearer <server-side-api-key>
Content-Type: application/json

{
  "merchantId": "merch_B2P18X",
  "orderId": "ord_A7K39Q",
  "amountCents": 123456,
  "currency": "EUR",
  "paymentMethod": "qr_pay"
}

The response includes the payment reference, checkout URL, and initial status:

{
  "success": true,
  "paymentId": "pay_A7K39Q",
  "paymentUrl": "https://app.foxpay.it/p/pay_A7K39Q",
  "status": "initialized"
}

Three implementation rules are worth spelling out. First, amountCents is an integer in minor units, not a floating-point amount. That keeps rounding mistakes out of reconciliation. Second, API keys must stay server-side. They do not belong in browser bundles, mobile clients without a backend, public repositories, or analytics logs. Third, initialized means FoxPay has prepared the checkout flow. It does not mean the order should be fulfilled.

The paymentUrl handoff

After initialization, your backend can return the paymentUrl to your front end. The browser then navigates to hosted checkout. For the buyer, this is a clear payment step. For the development team, it keeps the flow predictable because the merchant application does not need to infer every downstream payment detail.

The redirect back to your site is still not enough to mark an order as paid. A buyer may close a tab, complete a bank step later, return more than once, or never return at all. Treat the return page as UX: show a confirmation view, load the latest known status, explain a pending state, or give the customer a support path. Treat backend reconciliation as the place where order state becomes final.

Polling is UX. Signed webhooks are backend truth.

Polling has a real role. After a redirect, a shop can poll status for a short period so the buyer does not sit on a static waiting page. Support tools can also use status checks to help teams understand what is happening with a payment session.

For fulfillment, invoicing, license activation, shipment release, or accounting, polling should not be the primary source of truth. FoxPay supports signed webhook semantics for payment status and order reconciliation. The merchant backend should verify webhook signatures against the raw request body, process events durably, and only then update internal order state.

This discipline matters most when the merchant is regulated or operationally complex. A wrong payment status is not just a visual glitch. It can create support tickets, manual review, premature fulfillment, refund confusion, and inaccurate finance records.

Idempotency is part of production readiness

Payment integrations should assume duplicates and delays. A webhook may be delivered more than once. A buyer may refresh a return page. A backend may retry after a timeout. None of those cases should corrupt order state.

That is why idempotency belongs in the first implementation pass. An order should not be fulfilled twice because the same event arrived twice. A payment should not be recorded as paid in two competing ways. Retry and redelivery scenarios should remain traceable. Store your order and payment references, define allowed status transitions, and make state changes inside durable transaction boundaries.

This is one of the differences between a demo checkout and a production integration. CTOs and agencies should review idempotency as part of the payment architecture, not as a late QA note after the first incident.

OpenAPI makes the API reviewable

FoxPay's developer documentation and OpenAPI artifact make the integration surface reviewable. That is useful beyond code generation. OpenAPI helps teams inspect request and response shapes, write precise tickets, align backend and frontend work, and build QA cases around the actual contract.

Agencies can use it to scope implementation work. Internal engineering teams can use it to decide where payment responsibilities live. CTOs can review whether the checkout path fits their risk and operations model. For regulated merchants, this traceability is especially valuable because technical decisions eventually show up in onboarding, compliance review, support, and reconciliation.

Environments, credentials, and release hygiene

A serious REST integration separates test and live environments carefully. Test credentials belong in staging or sandbox-like systems. Live credentials belong only in production. Return URLs, webhook URLs, merchant context, and logging should be checked per environment before launch. Teams working with multiple shops or merchant accounts should document which credential belongs to which merchant context.

Secrets should live in server environment variables or a proper secret-management system. They should not appear in example code, screenshots, support tickets, front-end configuration, or project-management comments. Agencies should also define who can access live credentials and how keys are rotated if a repository, laptop, or third-party service is compromised.

Who should use the REST API?

The custom API path is a strong fit when a plugin would be too narrow:

• headless commerce with a custom checkout
• B2B portals with approval or invoice-adjacent flows
• marketplace or multi-merchant architectures
• ERP-connected order processing
• agencies managing several regulated merchants
• WooCommerce merchants planning a more custom backend over time

For a straightforward WooCommerce shop, the plugin can still be the faster start. For teams that own their backend and need precise control, the REST API is the cleaner route into the same FoxPay payment infrastructure.

Conclusion: checkout is an infrastructure decision

The custom REST API launch makes FoxPay more flexible and more relevant to serious merchant stacks. Teams do not have to choose between plugin convenience and building payment logic from scratch. They can create payment sessions server-side, hand buyers into hosted checkout, use polling where it improves UX, and reconcile final truth through signed webhooks.

That is the right model for teams that treat payments as an operating layer rather than a button. If you are building a normal or regulated merchant stack without a commerce plugin, plan FoxPay early in the backend design and use the OpenAPI documentation as the technical contract for implementation.