Foxpay

Public API docs for Foxpay custom REST integrations.

Public APICustom REST integrationv0.1
Resources
Custom REST Integration

Build a Foxpay checkout without a commerce plugin

Use the custom REST API when your backend creates payments directly, redirects buyers into Foxpay-hosted checkout, and reconciles final order state from signed merchant-hosted webhooks.

Create the first paymentUnderstand webhooks

Implement this sequence

The integration is intentionally small: one backend initializer, one hosted checkout redirect, status polling for UX, and one signed webhook handler for backend truth.

01Authenticate server-side

Call Foxpay only from your backend with `Authorization: Bearer <apiKey>`. Never expose merchant credentials in browser code.

02Initialize the payment

Send `merchantId`, `orderId`, `amountCents`, `currency`, optional buyer context, and metadata to `POST /payments/initialize`.

03Redirect to hosted checkout

Use the returned `paymentUrl` as the browser redirect target. Keep `paymentId` for status checks and support lookup.

04Reconcile with webhooks

Use polling for buyer-facing progress. Use signed webhooks to make durable backend order-state changes.

Amounts are cents

`amountCents: 12345` means EUR 123.45. Do not send major currency units in custom REST requests.

Webhook is merchant-hosted

Custom API integrations expose their own HTTPS callback URL. It is separate from the WooCommerce plugin webhook.

Signatures use the raw body

Verify `X-Foxpay-Signature: sha256=<hex>` against the exact raw JSON payload using the shop webhook secret.

Polling is not settlement

Status polling supports checkout UX. Final order reconciliation belongs on your backend webhook handler.

Initiated is not paid

`success: true` with `paymentId` and `paymentUrl` means Foxpay accepted the checkout handoff. It does not mean the buyer has completed payment.

Public endpoint surface

Start with the custom REST endpoints. Only use WooCommerce endpoints when the merchant is integrating through the plugin.

CreatePayment initialization

Create or reuse a pending hosted checkout session for a merchant order.

POST /payments/initialize
ReadCheckout progress

Inspect buyer-facing state and fetch transfer instructions when checkout needs bank details.

GET /payments/{paymentId}/statusGET /payments/{paymentId}/bank-details
PluginWooCommerce only

Use these only when integrating through the WooCommerce plugin flow, not for a custom API build.

POST /woocommerce/initiate-paymentPOST /woocommerce/webhook