FoxpayDocs
Custom REST APIv1.0Beta
Guide

Payment flow

The current Foxpay custom flow is backend init, frontend redirect, and backend reconciliation. This guide reflects the latest contract around `POST /payments/initialize` so merchants understand the runtime split instead of treating the initializer as a standalone HTTP call.

Read the quickstartCross-check endpoint details

Primary sequence

  1. Merchant backend calls `POST /payments/initialize` with `Authorization: Bearer <apiKey>`, `merchantId`, `orderId`, `amountCents`, buyer context, and optional method controls.
  2. Foxpay resolves the merchant/store, enforces eligibility and payment-method gating, and either creates/reuses a hosted checkout transaction or creates a direct provider session.
  3. Initialization has succeeded when the response is HTTP 2xx and includes `success: true`, `paymentId`, and `paymentUrl`.
  4. Merchant frontend redirects the buyer into `paymentUrl` for hosted checkout, or `redirectUrl`/`sessionUrl` for direct provider sessions.
  5. During checkout, poll `GET /payments/{paymentId}/status` to reflect progress states.
  6. If the buyer needs manual transfer data, fetch `GET /payments/{paymentId}/bank-details` with the `orderId` query parameter.
  7. Merchant backend reconciles final payment state through webhook-style callbacks and internal order updates.

Successful initialization

  • HTTP 2xx means the initializer accepted the request.
  • `success: true` confirms Foxpay created or reused a checkout handoff.
  • `paymentId` is the Foxpay transaction identifier to store with the merchant order.
  • `paymentUrl` is the buyer redirect target for hosted checkout.
  • `redirectUrl`, `sessionUrl`, and `paymentUrl` are returned for direct provider handoff such as Calytics OBT.
  • `status: pending` is normal immediately after initialization and does not mean payment completion.

Payment outcome

  • Use polling to update the buyer-facing checkout screen or return page.
  • Use signed webhook delivery to update your backend order record durably.
  • Only mark the merchant order as paid after the later status or webhook indicates a completed payment state.
  • If initialization returns HTTP 4xx or 5xx, do not redirect the buyer because no usable checkout handoff exists.

Bank references and EndToEndId

The custom REST contract supports merchant-controlled remittanceInfo for the SEPA remittance/payment reference and endToEndId for the provider-side SEPA EndToEndId on direct Calytics OBT.

  • Send `remittanceInfo` when the merchant wants to control what Foxpay sends as the payment reference to the provider.
  • Allowed characters are letters, numbers, spaces, and `. , - _ / + : #`; the maximum length is 140 characters.
  • If `remittanceInfo` is omitted, Foxpay generates `FP-{orderNumber}-{transactionIdSuffix}`.
  • Send `endToEndId` for direct-provider OBT when the merchant wants a stable bank-side identifier; keep it SEPA-safe and at most 35 characters.
  • If `endToEndId` is omitted on direct-provider OBT, Foxpay derives one from the order or transaction reference because some banks require it.
  • The response returns `remittanceInfo` and `remittanceInfoSource` so the merchant can persist exactly what was used.
  • Direct-provider OBT responses also return `endToEndId` so the merchant can correlate provider, bank, and support conversations.
  • `metadata` is still only reconciliation context and does not replace `remittanceInfo`.

Hosted checkout vs direct provider

  • Default hosted checkout: omit `paymentMethod` and `checkoutMode`, then redirect to `paymentUrl`.
  • Hosted checkout with preselect: pass `paymentMethod` (e.g. `open_bank_transfer` or `qr_pay`) with the default `checkoutMode: foxpay_checkout` — the matching tile is preselected on the Foxpay page; the buyer can still switch.
  • Direct OBT: send `paymentMethod: open_bank_transfer` and `checkoutMode: direct_provider`.
  • Direct OBT currently uses `provider: calytics` and requires buyer country. Omit `senderName` and `senderIban` to let the buyer enter/select their bank details in the Calytics/finAPI hosted webform.
  • If direct OBT sends payer context, send both `senderName` and `senderIban`; partial sender data is rejected with `400 VALIDATION_ERROR`.
  • Do not send reconciliation-mode controls from the merchant request. Foxpay admins configure provider confirmation vs full settlement confirmation on the store payment-method settings.
  • For hosted-mode OBT the buyer data collection behavior is controlled on the Foxpay store payment-method settings - the merchant does not send those fields server-side.
  • SEPA Instant vs standard SEPA is configured per store. Direct-provider requests can send `instantPayment`, but omission is recommended when the store default should apply.
  • When Foxpay initiates Calytics Instant OBT it also enables a standard-SEPA fallback path, so buyers can still complete payment when Instant is unavailable or declined.
  • Both modes return a Foxpay `paymentId` and should be reconciled through the same polling and webhook model.

How to answer payment-init questions

  • Successful initialization means Foxpay accepted the session and returned a redirect target.
  • It does not mean the payment is paid, settled, or final.
  • Persist the identifiers, redirect the buyer, then listen for the later status/webhook outcome.

State transitions that matter

  • `pending` is the normal initial state.
  • `paymentId` is the Foxpay-side transaction identifier and should be stored for later polling and reconciliation.
  • Checkout flow statuses collapse some lower-level transaction states into buyer-facing progress labels.
  • For direct Calytics OBT, provider-side `UNKNOWN` and `INDETERMINATE` should be treated as unresolved, not as success or terminal failure.
  • Provider confirmation mode is the default: provider success can drive the merchant success webhook.
  • Full reconciliation is a Foxpay-admin enabled paid add-on: provider success remains processing until settlement is confirmed asynchronously.
  • Polling and webhooks solve different problems and should usually coexist.
  • The custom initializer is cent-based end to end: `amountCents` is the canonical request field.

Where to go next

  • Reliability and retries covers idempotency for initialization, polling, and webhook handling.
  • Webhook reference documents headers, payload shape, statuses, and retry semantics.
  • Direct OBT best practices covers Calytics-specific rollout, failure diagnostics, and settlement expectations.
  • Authentication shows the Bearer header in context and explains test vs live key separation.
  • Sequence diagrams for hosted vs direct OBT and an end-to-end example app are still on the roadmap.