Node / TypeScript example
Server-side example for payment initialization, status polling, webhook signature verification, and the custom webhook verification handshake.
Samples and integration assets
Use these sample assets to accelerate Foxpay custom REST integration work and validate request, polling, and webhook flows in your own environment.
Postman collection
Example requests for payment initialization, status polling, bank-details inspection, and a merchant-hosted webhook verification payload.
What the samples cover
- Create a custom REST payment session with `POST /payments/initialize`.
- Create a direct Calytics OBT session with `paymentMethod: open_bank_transfer` and `checkoutMode: direct_provider`.
- Send `remittanceInfo` when the merchant wants to control the SEPA remittance/payment reference.
- Poll `GET /payments/{paymentId}/status` for buyer-facing checkout progress.
- Fetch `GET /payments/{paymentId}/bank-details` when the checkout method requires transfer instructions.
- Verify `X-Foxpay-Signature: sha256=<hex>` against the exact raw webhook body.
- Respond to `foxpay.webhook_verification` by echoing the challenge after signature validation.
Required substitutions
- Replace `FOXPAY_API_KEY` with the merchant API key for the target environment.
- Replace `merchantId`, `orderId`, and buyer fields with values from the merchant backend.
- Use integer cents for custom REST amounts, for example `12345` for EUR 123.45.
- Use `remittanceInfo` only for the bank/provider-visible payment reference; keep internal context in `metadata`.
- Set `FOXPAY_WEBHOOK_SECRET` to the shop webhook secret before validating signatures.
- Use your own `webhookUrl`; do not point custom integrations at WooCommerce plugin webhook routes.
Recommended validation order
Validate initialization first, then redirect behavior, status polling, bank details, and finally webhook handling in the same environment. Treat the webhook handler as the durable backend reconciliation path before promoting the integration to production traffic.