FoxpayDocs
Custom REST APIv1.0Beta
Foundation

Authentication

Foxpay custom REST integrations authenticate with Bearer API keys. Send `Authorization: Bearer <apiKey>` from your backend and keep merchant credentials out of any browser context.

Inspect authenticated routesReview error handling

Bearer API key

Use `Authorization: Bearer <apiKey>` for `POST /payments/initialize` and the related custom REST routes.

Merchant-scoped credentials

Each key is tied to one merchant store and one environment (test or live). Use the credential issued for the request's intended environment.

Webhook trust model

Inbound webhooks use signed requests. Verify `X-Foxpay-Signature` separately from outbound API authentication.

Send the Bearer header

Forward the API key on every request to the custom integration endpoints. The canonical custom flow is server-to-server, so the key never reaches the buyer's browser.

Bearer header
# Initialization request
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"
  }'

# Polling request
curl -H "Authorization: Bearer fp_live_example" \
  "https://app.foxpay.it/api/payments/tx_123/status"
  • The Bearer scheme is case-insensitive (`Bearer`, `bearer`); standardize on `Bearer` to match published examples.
  • Polling and bank-detail reads use the same Bearer credential as initialization; do not mint a separate token type.
  • Send the API key on the server side only. Browser-originated requests should call your backend, which forwards to Foxpay.

Test vs live keys

  • Foxpay issues distinct credentials for test and live traffic; the runtime mode is inferred from the key, not from a request parameter.
  • The initializer response returns `testMode: true` for test-mode keys and `testMode: false` for live keys — persist that flag with your order record.
  • A live key against a test-only payment method is rejected with `403 Payment method unavailable`.
  • Never reuse a live key in development environments. Treat it as production-grade material from day one.

Distinguish keys by prefix

Key prefixes
fp_live_…   # production-mode merchant API key
fp_test_…   # test-mode merchant API key
fp_legacy_… # pre-Bearer compatibility token (still accepted)

The prefix is part of the issued credential and is logged on usage. Use it to route traffic to the correct environment in your own configuration system.

Issue and rotate keys in the merchant panel

Custom integration keys are managed from the merchant store's Integration tab in the Foxpay app. Treat the issued secret as one-time visible material.

  1. Open the store in the Foxpay app, then choose Integration on the store detail page.
  2. Open the API Keys card and choose Generate API key. Pick the environment (test or live).
  3. Copy the displayed secret immediately. The full value is shown only at generation time; only the prefix is visible afterwards.
  4. Store the secret in your backend secret manager; never commit it to source control.
  5. Rotate by generating a new key first, deploying the new value, then revoking the old key from the same panel.

Authentication failure modes

  • `401 API key required via Authorization: Bearer <key>` — the header is missing or malformed.
  • `401 Invalid API key` — the key does not exist, has been revoked, or expired.
  • `401 API key does not belong to the requested merchant` — the `merchantId` (or `shopId` alias) does not match the key's store.
  • `403 API key does not allow test mode` / `403 API key does not allow production mode` — the key is restricted to the opposite environment.

Operational guidance

  • Rotate credentials when scope changes, when staff with access leaves, or when a key may have been disclosed.
  • Run rotations through a generate–deploy–revoke sequence so live traffic never sees a missing credential.
  • Record the key prefix in your audit trail when a payment is created; the full secret should never appear in your logs.
  • Webhook deliveries do not use the API key — they are validated through `X-Foxpay-Signature: sha256=<hex>`. See the webhook reference for the exact contract.