Quickstart

Custom integration quickstart

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`.

Open the reference Read the full payment guide

Before you start

These are the only assumptions you need for a first successful custom REST integration.

Environment

Know whether you are targeting production, staging, or a local integration loop.

Credentials

Have a Foxpay API key ready for `Authorization: Bearer <apiKey>`.

Canonical identifiers

Use `merchantId` and `amountCents` as the canonical request fields. `shopId` is only a temporary alias.

Integration split

Your backend creates the payment, your frontend redirects to `paymentUrl`, and your backend reconciles later state updates.

Custom integration sequence

This is the shortest practical runtime path through the current public profile.

Create the payment on your backend

Send Authorization: Bearer <apiKey> to POST /payments/initialize with merchantId, orderId, amountCents, currency, optional buyer context, and optional payment-method controls.

Confirm the payment was initiated

Treat HTTP 2xx plus success: true, paymentId, and paymentUrl as successful initialization. Persist those values before redirecting the buyer.

Redirect into checkout

Move the buyer into the returned handoff URL. Hosted Foxpay checkout returns paymentUrl; direct provider sessions return redirectUrl and sessionUrl.

Poll for status

During checkout, query GET /payments/{paymentId}/status to reflect progress and buyer outcome.

Show bank details if needed

Fetch GET /payments/{paymentId}/bank-details?orderId=... when the buyer needs manual transfer instructions.

Reconcile payment state on your backend

Treat webhook reconciliation as authoritative for your order lifecycle and use polling for buyer-facing progress updates.

Request and response you should expect

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"
  }'

{
  "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"
}

How to read the init response

Initialization succeeded

HTTP 2xx with success: true, paymentId, and paymentUrl means Foxpay accepted the checkout handoff.

Payment is still pending

The initial status is normally pending. That is expected and does not mean the buyer has paid.

Initialization failed

HTTP 4xx or 5xx means no usable checkout handoff was created. Show a recoverable error and do not redirect the buyer.

Payment outcome arrives later

Use GET /payments/{paymentId}/status for checkout progress and signed webhooks for durable backend reconciliation.

Bank statement reference

Send remittanceInfo when you need a merchant-controlled SEPA remittance text. If omitted, Foxpay generates FP-{orderNumber}-{transactionSuffix}.

Hosted checkout mode

Omit paymentMethod and checkoutMode for the default Foxpay checkout. The buyer sees the active payment methods configured for the merchant.

Response handoff field: paymentUrl.
Recommended default for most custom integrations.
Use this when Foxpay should choose from all enabled payment methods at checkout time.

Direct OBT mode

Set paymentMethod: open_bank_transfer and checkoutMode: direct_provider to create a direct Calytics A2A/OBT session instead of showing the Foxpay method-selection page.

{
  "merchantId": "merchant_fxp_ABC12345",
  "orderId": "order_1001",
  "amountCents": 12345,
  "currency": "EUR",
  "paymentMethod": "open_bank_transfer",
  "checkoutMode": "direct_provider",
  "provider": "calytics",
  "customerCountry": "DE",
  "senderName": "Jane Doe",
  "senderIban": "DE89370400440532013000",
  "remittanceInfo": "ORDER-1001"
}

What to persist locally

Persist the initialization response before redirecting so your backend can reconcile the final payment outcome later.

Canonical amount field

amountCents is canonical. Do not send major-unit floats for the custom integration path.

Canonical merchant field

merchantId is the public merchant identifier. shopId is only still accepted for rollout compatibility.

Persist these identifiers

Store orderId, paymentId, merchantId, and the final reconciled payment state in your own order record.

Persist environment context

Store testMode so support and reconciliation flows can distinguish test traffic from production traffic.

Eligibility gates

The initializer enforces KYC, store verification, and payment-method availability. This is not just a schema check.

Duplicate protection

Pending transactions with the same store, order, amount, and currency can be reused instead of duplicated.

Authentication Environments Testing Errors