FoxpayDocs
Custom REST APIv1.0Beta
Payment method

Open bank transfer

Foxpay open bank transfer (OBT) is reachable through either hosted Foxpay checkout or a direct Calytics A2A provider handoff. Both modes share the same custom REST initializer and reconcile through the same webhook surface.

Read payment flowOpen API reference

Integration type

Open bank transfer (OBT)

Primary amount field

amountCents

Buyer handoff

paymentUrl for hosted checkout; redirectUrl for direct-provider OBT

Route focus

  • `POST /payments/initialize` creates the hosted checkout handoff by default; the buyer picks OBT from the Foxpay payment-method screen.
  • `POST /payments/initialize` with `paymentMethod: open_bank_transfer` (and the default `checkoutMode: foxpay_checkout`) preselects the OBT tile on the Foxpay hosted page; the buyer can still switch to another enabled method.
  • `POST /payments/initialize` with `paymentMethod: open_bank_transfer` and `checkoutMode: direct_provider` bypasses the Foxpay page and creates a direct Calytics OBT session that returns `redirectUrl` / `sessionUrl` / `paymentUrl` for the buyer handoff.
  • `GET /payments/{paymentId}/status` polls buyer-facing progress in any mode.
  • `GET /payments/{paymentId}/bank-details` returns the IBAN, BIC, beneficiary, and remittance reference when the checkout needs manual transfer instructions.

Implementation guidance

  • Send `amountCents`, not major-unit floats, on the custom REST integration path.
  • Use `remittanceInfo` to control the SEPA remittance/payment reference; Foxpay generates `FP-{orderNumber}-{transactionSuffix}` when omitted.
  • Send a stable `endToEndId` for direct-provider Calytics OBT when you want deterministic bank-side correlation. Keep it SEPA-safe and at most 35 characters. Foxpay derives one when omitted.
  • Persist `paymentId`, `orderId`, `merchantId`, and `testMode` before redirecting the buyer.
  • Keep Bearer API keys server-side only; the merchant frontend never sees them.
  • For direct-provider OBT, omit `senderName` and `senderIban` when the buyer should enter/select bank details in the Calytics/finAPI hosted webform. If one sender field is supplied, both must be supplied and valid.
  • Configure SEPA Instant vs standard SEPA on the store OBT settings in Foxpay. Direct-provider calls can send `instantPayment`, but omission uses the store/provider default and is the recommended integration default.
  • Do not include reconciliation-mode fields in merchant initialization requests. Provider confirmation vs full settlement confirmation is configured by Foxpay admins on the store OBT settings.
  • Provider confirmation is the default settlement mode. Full reconciliation is a paid add-on that holds provider-success payments in processing until asynchronous settlement confirmation arrives.
  • When Instant OBT is used, Foxpay enables Calytics standard-SEPA fallback so eligible buyers can still complete the payment after an Instant rejection or unsupported-bank path.
  • Treat Calytics `UNKNOWN` and `INDETERMINATE` as unresolved. Reconciliation can still later move the payment to success after settlement refreshes.
  • Capture `failure_code`, `failure_message`, payer IBAN, `remittanceInfo`, and `endToEndId` in merchant logs because support cases frequently need those exact values.
  • Use polling for buyer-facing UX and signed webhook delivery for durable backend reconciliation.
  • Confirm OBT is enabled on the merchant store before live rollout - a live key against a disabled method returns `403 Payment method unavailable`.