Canonical handoff
Use `redirectUrl` for buyer redirect. `sessionUrl` and `paymentUrl` are compatibility aliases.
Direct OBT best practices
Use this guide when onboarding a merchant onto Foxpay direct-provider OBT with Calytics. It captures the practical integration rules that matter after the request is already technically valid, including the admin-controlled settlement mode.
Stable identifiers
Keep `orderId`, `endToEndId`, and `remittanceInfo` stable across retries for the same payment attempt.
Settlement mode
Provider confirmation is the default. Full reconciliation is an admin-enabled paid add-on.
Recommended request shape
The fastest clean rollout path is still the shared public contract on `POST /payments/initialize`.
{
"merchantId": "merchant_fxp_ABC12345",
"orderId": "order_1001",
"amountCents": 12345,
"currency": "EUR",
"paymentMethod": "open_bank_transfer",
"checkoutMode": "direct_provider",
"provider": "calytics",
"customerCountry": "DE",
"endToEndId": "ORDER-1001",
"remittanceInfo": "ORDER-1001",
"returnUrl": "https://merchant.example/orders/order_1001/return"
}- Omit `senderName` and `senderIban` unless the merchant really has both values at request time and wants to prefill them.
- Send `endToEndId` when the merchant wants deterministic bank-side correlation. Keep it SEPA-safe and at most 35 characters.
- Send `remittanceInfo` when the merchant wants to control the payment reference shown to the buyer or bank; keep internal-only context in `metadata`.
- Do not change `orderId`, `endToEndId`, `remittanceInfo`, `amountCents`, or `currency` across retries for the same order attempt.
- Do not send a reconciliation-mode field from the merchant API request. Settlement behaviour is configured by Foxpay admins on the store payment-method settings.
Calytics runtime expectations
- `UNKNOWN` is no longer the final unresolved webhook outcome. `INDETERMINATE` is the explicit unresolved state after Calytics re-polls the bank and still cannot determine the result.
- `INDETERMINATE` does not mean success and does not mean permanent failure. Reconciliation may still later move the payment to success after settlement refreshes.
- In the default provider-confirmation mode, a successful provider finalization is enough for Foxpay to emit the merchant success path.
- In full-reconciliation mode, provider success is held as processing until the asynchronous settlement confirmation arrives.
- Non-success outcomes can include `failure_code` and `failure_message`. Persist both because support and merchant ops need them for triage.
- No-sender direct OBT can still return payer IBAN later even when payer name stays unavailable. Treat payer identity fields as partially available provider evidence, not as a complete KYC payload.
Instant vs standard SEPA
- When the store default is standard SEPA, do not force `instantPayment` from the merchant integration.
- When Instant OBT is intended, Foxpay sends `instant_payment: true` and also enables Calytics standard-SEPA fallback when available.
- The fallback path matters operationally because some banks reject or do not support Instant while still allowing a standard transfer flow.
- Merchant UX should not present Instant as a guaranteed outcome unless the merchant is prepared for the standard fallback path.
Settlement and fulfilment
Direct OBT rollout usually fails when merchants treat buyer redirects as settlement truth. The fulfilment trigger depends on the store settlement mode.
- Use signed Foxpay merchant webhooks as the durable fulfilment trigger.
- Use polling for buyer-facing progress only; do not fulfil solely on an optimistic buyer redirect or intermediate provider state.
- Provider confirmation mode is the default and keeps existing integrations fast: merchant success handling runs after provider success.
- Full reconciliation is a paid add-on configured by Foxpay admins. When enabled, merchant success handling waits for settlement confirmation instead of provider success alone.
- Calytics settlement reconciliation is not instant. Bank statement refreshes are periodic and can take hours, so full-reconciliation payments may remain processing while settlement is pending.
- Store `paymentId`, `orderId`, `endToEndId`, `remittanceInfo`, payer IBAN, and any provider failure diagnostics together so support can compare Foxpay, Calytics, and bank traces quickly.
Go-live checklist
- Confirm OBT is enabled on the merchant store and the target API key environment matches the intended store mode.
- Confirm with Foxpay whether the store should use default provider confirmation or the paid full-reconciliation add-on before go-live.
- Validate one no-sender direct OBT session end to end before enabling sender-prefill variants.
- Confirm the merchant logs include `paymentId`, `orderId`, `endToEndId`, `remittanceInfo`, `failure_code`, and `failure_message`.
- Train merchant ops that unresolved Calytics outcomes and full-reconciliation settlement waits are processing states, not automatic refund or shipment states.