Merchant Setup Guide

Open a terminal and run this curl command (replace YOUR_API_KEY with your actual key):

Copycurl -X POST "https://www.maxafi.com/api/gateway/gateway.php?action=create_session" \
  -H "Content-Type: application/json" \
  -H "X-Gateway-Key: YOUR_API_KEY" \
  -d '{
    "amount": 1.00,
    "currency": "EUR",
    "items": [{"name": "Test Item", "qty": 1, "price": 1.00, "total": 1.00}]
  }'

Expected response:

{
  "success": true,
  "session_id": 1,
  "session_token": "a1b2c3d4e5f6...",
  "checkout_url": "/checkout/pay.html?session=a1b2c3d4...",
  "environment": "stage"
}

Option B — Hosted Checkout (no code)

If you don't have a developer, you can skip Steps 3–5 entirely. Just create a session from your server and redirect the customer:

Copy// Create session (from your server), then redirect customer to:
https://www.maxafi.com/checkout/pay.html?session=SESSION_TOKEN

// We handle the entire payment UI.
// When confirmed, we POST to your callback_url.

Then skip ahead to Step 6 (Webhook).

Option A — API Integration

Continue to Step 3 below. You'll build the payment flow into your existing checkout page.

When a customer clicks "Pay with Instant Payments" on your checkout page, your server makes two API calls:

Call 1: Create Session

Copy// POST to create_session — creates the payment session
const session = await fetch('https://www.maxafi.com/api/gateway/gateway.php?action=create_session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Gateway-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    amount: 49.99,
    currency: 'EUR',
    order_id: 'ORD-12345',  // YOUR order number — returned in webhook
    customer_email: 'customer@example.com',
    customer_name: 'John Smith',
    callback_url: 'https://yoursite.com/webhooks/dapit',
    items: [
      { name: 'Premium Plan', qty: 1, price: 49.99, total: 49.99 }
    ]
  })
}).then(r => r.json());

// Save session.session_token — you need it for all subsequent calls

Call 2: Create Invoice

This generates the reference number and returns the IBAN + beneficiary details:

Copy// POST to create_invoice — generates reference number + payment instructions
const invoice = await fetch('https://www.maxafi.com/api/gateway/gateway.php?action=create_invoice', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: session.session_token })
}).then(r => r.json());

// invoice.beneficiary_name → "Longemalle Trustees OU"
// invoice.iban             → "LT913740020058585210"
// invoice.bank_name        → "Dapit"
// invoice.reference_number → "DP-260406-XA6HSX"
// invoice.amount           → 49.99

Send these values back to your frontend to display on the checkout page.

On your checkout page, display the payment details from Step 3. The customer needs to see:

The customer then:

1. Opens their banking app (Wise, Revolut, N26, or any EUR-enabled bank)
2. Creates a new SEPA transfer to the beneficiary name and IBAN
3. Enters the reference number in the "Reference" or "Message to recipient" field
4. Sends the exact EUR amount

That's all the customer has to do. The next step (receiving the webhook on your server) happens automatically — no further action from the customer or your page is required. If you want the customer to see "Payment received" in their browser faster than the ~60-second reconciliation interval, you can optionally add an "I've Sent the Payment" button (covered in Step 6).

That's it for the required flow. Our reconciliation runs every ~60 seconds against the custodial IBAN, looking for incoming SEPA Instant credits whose remittance text matches your reference number. When it finds the match, it POSTs to the callback_url you supplied in Step 3 — automatically. You don't have to do anything else. The customer doesn't have to click anything. If they pay, you get the webhook within ~60 seconds of SEPA Instant settlement.

Copy// Your webhook endpoint receives this JSON:
// Fires for both exact and overpayments (not for partial — only when fully paid)
{
  "event": "payment.confirmed",
  "merchant_order_id": "ORD-12345",     // YOUR order number
  "reference_number": "DP-260406-XA6HSX",
  "invoice_number":   "INV-260406-01234",
  "invoice_amount":   49.99,
  "amount_paid":      49.99,
  "amount_remaining": 0.00,
  "overpaid_amount":  0,
  "currency":         "EUR",
  "paid_at":          "2026-04-06 14:32:10",
  "session_token":    "a1b2c3d4...",
  "customer_email":   "customer@example.com",
  "customer_name":    "John Smith"
}

Return HTTP 200 to acknowledge receipt. If we don't receive a 200, the delivery is flagged in our retry queue and the operator dashboard surfaces the failure for redelivery.

Webhook signature

Each webhook POST carries two headers you can use to verify authenticity:

• X-MaxaFi-Signature — HMAC-SHA256 of timestamp + "." + raw_body, keyed on your merchant webhook_secret
• X-MaxaFi-Timestamp — Unix timestamp at the moment the webhook was signed

If your webhook_secret is configured, always recompute the HMAC on your side and compare with constant-time string equality before trusting the payload.

Recovery flag (manual + automatic re-matches)

If a payment lands outside the normal reconciliation window — for example, the SEPA credit arrives after the session has already been failed — and our nightly orphan sweep or an operator-driven manual sync later matches it, the webhook still fires, but includes two extra fields so you can branch on it if your idempotency rules require:

Copy{
  ...standard payment.confirmed fields...,
  "recovered": true,
  "recovery_method": "cron_orphan_sweep"   // or "manual_admin_sync"
}

For most integrations you can treat a recovered webhook identically to a fresh confirmation — the field is informational. Only branch on it if you have strict accounting rules that distinguish "received during checkout" from "received late and reconciled later."

PHP Example

Copy<?php
$payload = json_decode(file_get_contents('php://input'), true);

if ($payload['event'] === 'payment.confirmed') {
    $orderId = $payload['merchant_order_id'];
    $amount  = $payload['amount_paid'];

    // Mark order as paid in your database
    $db->query("UPDATE orders SET status='paid' WHERE order_id='$orderId'");

    // Send confirmation email, trigger shipping, etc.
}

http_response_code(200);
echo json_encode(['received' => true]);

If you want the customer to see "✓ Payment received" in their browser within seconds instead of up to a minute, expose an "I've Sent the Payment" button on your page. When the customer taps it, call confirm_paid to start a tighter polling cycle (every 5–7 seconds instead of every 60), then poll check_payment for status. The webhook in Step 5 still fires either way — this just speeds up what the customer sees in the foreground.

6a. Tell our API the customer says they paid

Copy// OPTIONAL: when customer taps "I've Sent the Payment"
// Switches our system into a tighter, short-lived polling cycle
await fetch('https://www.maxafi.com/api/gateway/gateway.php?action=confirm_paid', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: sessionToken })
});

6b. Poll every 7 seconds until payment is found

Copy// OPTIONAL: only if you want a fast in-page confirmation UX
const poll = setInterval(async () => {
  const check = await fetch('https://www.maxafi.com/api/gateway/gateway.php?action=check_payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: sessionToken })
  }).then(r => r.json());

  if (check.status === 'confirmed') {
    clearInterval(poll);
    // ✅ Payment confirmed! Show success page.

  } else if (check.status === 'partial') {
    clearInterval(poll);
    // ⚠ Customer sent less than the invoice amount.
    // Show: "We received €X. Remaining: €Y. Send the rest with the same reference."
    // When they send more: call confirm_paid again, restart polling.

  } else if (check.status === 'overpaid') {
    clearInterval(poll);
    // 💰 Customer sent too much. Order is confirmed.
    // Refund of (overpaid - €1 fee) will be processed automatically.

  } else if (check.status === 'timeout') {
    clearInterval(poll);
    // ⏰ Payment not found in the fast-polling window.
    // The ~60-second background reconciliation continues to run;
    // most payments still arrive — just outside the in-page cycle.
  }
  // "pending" / "polling" — keep polling, show a spinner
}, 7000);