Integration type
QR-Pay / Manual Transfer
QR-Pay / Manual Transfer
QR-Pay is the default payment method for Foxpay hosted checkout. The buyer sees the merchant IBAN, beneficiary, and a SEPA QR code, then completes a manual bank transfer. It is the same underlying flow as `manual_transfer`, `bank_transfer`, `manual_pay`, and `manual` — Foxpay normalizes these aliases to `qr_pay` server-side.
Primary amount field
amountCents
Buyer handoff
paymentUrl for hosted checkout; redirectUrl for direct-provider OBT
Route focus
- `POST /payments/initialize` with `paymentMethod` omitted defaults to `qr_pay`; the buyer is redirected to the returned `paymentUrl` for the hosted checkout page.
- `POST /payments/initialize` with `paymentMethod: qr_pay` (or any alias: `manual_transfer`, `bank_transfer`, `manual_pay`, `manual`) explicitly selects the method.
- `GET /payments/{paymentId}/status` polls buyer-facing progress; the buyer typically completes the transfer in their banking app and is then redirected back through the hosted page.
- `GET /payments/{paymentId}/bank-details?orderId=…` returns the IBAN, BIC, beneficiary, amount, and SEPA reference when your own UI needs to display the transfer instructions outside the hosted page.
Implementation guidance
- QR-Pay only supports hosted Foxpay checkout — `checkoutMode: direct_provider` is rejected for this method (`400 Checkout mode unavailable`).
- Send `amountCents`, not major-unit floats; QR-Pay enforces a `100` (€1.00) minimum by default unless the store overrides it.
- Use `remittanceInfo` to control the SEPA remittance/payment reference shown on the buyer's bank statement; if omitted, Foxpay generates `FP-{orderNumber}-{transactionSuffix}`.
- Persist `paymentId`, `orderId`, `merchantId`, and `testMode` from the initializer response before redirecting the buyer.
- Use polling for buyer-facing UX and signed webhook delivery for durable backend reconciliation — manual transfers can take hours or days to settle, so webhook reconciliation is essential.
- QR-Pay is auto-enabled as a fallback even if the store has not explicitly configured a `qr_pay` payment method, so it is the safest default for new integrations.