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        → "ConnectPay"
// 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
5. Returns to your page and clicks "I've Sent the Payment"

Add a prominent "I've Sent the Payment" button on your page. When they click it, you move to Step 5.

When the customer clicks "I've Sent the Payment", your page makes two types of calls:

5a. Tell our API the customer says they paid

Copy// Call confirm_paid — tells our system to start checking ConnectPay
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 })
});

5b. Poll every 7 seconds until payment is found

Copy// Poll check_payment every 7 seconds
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 after ~7 minutes. Show retry or contact support.
  }
  // "pending" — keep polling, show a spinner
}, 7000);

When a payment is confirmed, we send a POST request to the callback_url you provided when creating the session. This is your server-side confirmation — use it to update your order database.

Copy// Your webhook endpoint receives this JSON:
{
  "event": "payment.confirmed",
  "merchant_order_id": "ORD-12345",   // YOUR order number
  "reference_number": "DP-260406-XA6HSX",
  "invoice_amount": 49.99,
  "amount_paid": 49.99,
  "currency": "EUR",
  "paid_at": "2026-04-06 14:32:10",
  "customer_email": "customer@example.com",
  "customer_name": "John Smith"
}

Return HTTP 200 to acknowledge receipt. If we don't get a 200, the notification is flagged as undelivered.

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]);