Integration type
Open bank transfer (OBT)
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.
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.
- 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.
- 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`.