Create a Foxpay payment session over HTTP and redirect the buyer into hosted checkout. This quickstart follows the current custom integration contract implemented around `POST /payments/initialize`.
These are the only assumptions you need for a first successful custom REST integration.
Know whether you are targeting production, staging, or a local integration loop.
Have a Foxpay API key ready for `Authorization: Bearer <apiKey>`.
Use `merchantId` and `amountCents` as the canonical request fields. `shopId` is only a temporary alias.
Your backend creates the payment, your frontend redirects to the returned handoff URL, and your backend reconciles later state updates.
This is the shortest practical runtime path through the current public profile.
Send Authorization: Bearer <apiKey> to POST /payments/initialize with merchantId, orderId, amountCents, currency, optional buyer context, and optional payment-method controls.
Treat HTTP 2xx plus success: true, paymentId, and paymentUrl as successful initialization. Persist those values before redirecting the buyer.
Move the buyer into the returned handoff URL. Hosted Foxpay checkout returns paymentUrl; direct provider sessions return redirectUrl, sessionUrl, and paymentUrl as aliases for the same provider handoff.
During checkout, query GET /payments/{paymentId}/status to reflect progress and buyer outcome.
Fetch GET /payments/{paymentId}/bank-details?orderId=... when the buyer needs manual transfer instructions.
Treat webhook reconciliation as authoritative for your order lifecycle and use polling for buyer-facing progress updates.
The canonical request is cent-based and Bearer-authenticated. The response gives you the buyer handoff URL plus the identifiers you should persist on your side.
curl -X POST "https://app.foxpay.it/api/payments/initialize" \
-H "Authorization: Bearer fp_live_example" \
-H "Content-Type: application/json" \
-d '{
"merchantId": "merchant_fxp_ABC12345",
"orderId": "order_1001",
"amountCents": 12345,
"currency": "EUR",
"customerEmail": "buyer@example.com",
"remittanceInfo": "ORDER-1001",
"returnUrl": "https://merchant.example/orders/order_1001/return"
}'
# 200 OK
{
"success": true,
"paymentUrl": "https://app.foxpay.it/payment/order_1001?version=v2&transactionId=tx_123&source=custom_api",
"paymentId": "tx_123",
"orderId": "order_1001",
"merchantId": "merchant_fxp_ABC12345",
"amount": 12345,
"amountCents": 12345,
"currency": "EUR",
"customerEmail": "buyer@example.com",
"status": "pending",
"paymentMethod": "qr_pay",
"checkoutMode": "foxpay_checkout",
"remittanceInfo": "ORDER-1001",
"remittanceInfoSource": "merchant",
"testMode": false,
"returnUrl": "https://merchant.example/orders/order_1001/return"
}HTTP 2xx with success: true, paymentId, and paymentUrl means Foxpay accepted the checkout handoff.
The initial status is normally pending. That is expected and does not mean the buyer has paid.
HTTP 4xx or 5xx means no usable checkout handoff was created. Show a recoverable error and do not redirect the buyer.
Use GET /payments/{paymentId}/status for checkout progress and signed webhooks for durable backend reconciliation.
Send remittanceInfo when you need a merchant-controlled SEPA remittance text. If omitted, Foxpay generates FP-{orderNumber}-{transactionSuffix}.
Omit paymentMethod and checkoutMode for the default Foxpay checkout, or pass paymentMethod alone to preselect a tile while still letting the buyer switch.
paymentUrl.paymentMethod: open_bank_transfer (with the default checkoutMode: foxpay_checkout) to land buyers on the OBT tile; they can still pick another enabled method.senderName, senderIban, or customerCountry for hosted mode.Set paymentMethod: open_bank_transfer and checkoutMode: direct_provider to bypass the Foxpay method-selection page entirely and receive a direct Calytics A2A/OBT session URL.
{
"merchantId": "merchant_fxp_ABC12345",
"orderId": "order_1001",
"amountCents": 12345,
"currency": "EUR",
"paymentMethod": "open_bank_transfer",
"checkoutMode": "direct_provider",
"provider": "calytics",
"customerCountry": "DE",
"remittanceInfo": "ORDER-1001"
}senderName or senderIban when the buyer should enter/select their bank details inside the Calytics/finAPI hosted webform.400 VALIDATION_ERROR.instantPayment to use that store default; send true or false only when the integration intentionally overrides it for a single request.Persist the initialization response before redirecting so your backend can reconcile the final payment outcome later.
amountCents is canonical. Do not send major-unit floats for the custom integration path.
merchantId is the public merchant identifier. shopId is only still accepted for rollout compatibility.
Store orderId, paymentId, merchantId, and the final reconciled payment state in your own order record.
Store testMode so support and reconciliation flows can distinguish test traffic from production traffic.
The initializer enforces KYC, store verification, and payment-method availability. This is not just a schema check.
Pending transactions with the same store, order, amount, and currency can be reused instead of duplicated.