Integration RecipesCopy Anchor Link

Use these recipes when you are wiring a merchant backend to the gateway. They focus on the customer-facing integration surface and avoid deployment internals.

Recipe 1: Create A Hosted CheckoutCopy Anchor Link

Use the Admin API host for checkout creation. This is a trusted server-to-server call and must never be made from browser code.

curl -X POST https://api.yourcompany.com/api/v1/checkouts/{siteId}/create \
  -H "Authorization: Bearer sk_live_keyid.secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4900,
    "currency": "EUR",
    "email": "buyer@example.com",
    "externalReference": "order_12345",
    "returnUrl": "https://yourapp.com/success?txId={transactionId}",
    "cancelUrl": "https://yourapp.com/cancel",
    "ipnUrl": "https://yourapp.com/webhooks/payment-ipn",
    "items": [
      {
        "description": "Professional Plan",
        "quantity": 1,
        "unitPrice": 4900,
        "itemType": "digital_service"
      }
    ]
  }'

Required setup:

• Create an Organization API key with checkout:create.
• Create a Site and copy its Site ID.
• Assign at least one provider to the Site.
• Configure returnUrl, cancelUrl, and ipnUrl if your application needs redirect and server-side notification.

Use Settings > API Keys for the one-time sk_... secret reveal, and Sites > Edit Site for the Site ID plus Webhook Signing Secret.

Recipe 2: Let Hosted Checkout Calculate TaxCopy Anchor Link

Your merchant backend does not normally call the checkout tax-preview endpoint directly. Hosted checkout calls it while the buyer enters billing details:

POST https://webhook.yourcompany.com/api/v1/checkouts/{sessionPublicId}/tax-preview

The final transaction still recalculates tax authoritatively when the buyer submits payment. This means your integration should send stable line-item data at checkout creation time and let the gateway apply organization tax settings, rates, rules, VAT validation, OSS evidence rules, and rounding.

When you need deterministic tax behavior:

• Set item itemType consistently (goods, digital_service, shipping, tax, or discount).
• Use gross or net pricing consistently with the organization's Settings > Tax price mode.
• Configure tax rules before sending production traffic.
• Use externalReference to correlate gateway records with your order.

Recipe 3: Register Provider WebhooksCopy Anchor Link

Provider webhooks belong on the Main Backend host, not the Admin API host.

POST https://webhook.yourcompany.com/hooks/stripe/{providerId}
POST https://webhook.yourcompany.com/hooks/mollie/{providerId}
POST https://webhook.yourcompany.com/hooks/gocardless/{providerId}
POST https://webhook.yourcompany.com/hooks/paypal/{providerId}

Setup checklist:

1. Create the provider in the Admin Panel.
2. Copy the provider ID from the provider detail URL or provider record.
3. Register the webhook URL in the provider dashboard.
4. Save the provider webhook signing secret or verification identifier on the provider record where the provider requires one.
5. Run a provider test event and confirm that the gateway accepts it.

Provider webhooks update gateway transaction state. Your own application should listen to outbound IPN unless you intentionally poll the Admin API.

The provider detail page is the source of truth for the provider ID and the saved provider webhook secret.

Recipe 4: Receive And Verify Outbound IPNCopy Anchor Link

Set ipnUrl when creating the checkout. The gateway sends a small signed JSON payload to that URL when transaction status changes.

On a gateway release containing versioned IPN controls, v2 uses a signed body with schemaVersion: 2, deliveryId, a positive eventVersion, and occurredAt in addition to the transaction fields. Require X-IPN-Version: 2 and X-IPN-Delivery-ID matching the body deliveryId. Existing sites remain on signed v1; new sites default to v2. Upgrade compatible published receivers and matching gateway components before v2 traffic.

Verify these headers before trusting the payload:

• X-Signature-Timestamp
• X-Signature-HMAC-SHA256

The signature is the hex HMAC-SHA256 of {timestamp}.{rawBody} using the Site Webhook Signing Secret. Return 200 OK after accepting the message. Transient failures use the selected format's retry policy; non-retryable errors need operator attention.

[!IMPORTANT] Store and process IPN idempotently. For v2, atomically claim deliveryId before the business effect and retain that claim for at least the delivery window plus a safety margin. Also persist the highest eventVersion per transaction; ignore older events so delayed notifications cannot regress a later state. A duplicate or older event should still return 2xx.

Keep compact ordering and effect receipts beyond detailed attempt-log retention, including for later manual replay. Use the optional typed readiness probe where supported, transaction delivery history, and authorized retries described in Migrating to IPN v2. Follow the release-qualified support window and rollback instructions before changing IPN format.

Recipe 5: Reconcile Transaction, Invoice, And TaxCopy Anchor Link

A typical paid-order reconciliation flow looks like this:

Recommended reconciliation rules:

• Treat provider webhooks as input to the gateway, not as your application fulfillment trigger.
• Treat signed IPN or Admin API polling as your application fulfillment trigger.
• Use externalReference to match gateway transactions to your order ID.
• Read invoice and tax report data from the Admin API when you need accounting exports, not from provider dashboards.

Recipe 6: Export Tax Evidence For FilingCopy Anchor Link

For VAT OSS and by-country reports, use the Admin API report endpoints or the Admin Panel:

GET /api/v1/tax/reports/vat-oss?year=2026&quarter=2&timezone=Europe/Berlin&source=both
GET /api/v1/tax/reports/vat-oss/export?year=2026&quarter=2&timezone=Europe/Berlin&source=both
GET /api/v1/tax/records?sourceKind=transaction&taxTreatment=oss

Reports are backed by canonical tax_records, including refund, chargeback, and credit-note adjustments. Use the detail endpoints when you need to explain an aggregate number back to source transactions or invoices.