Instant Payments API

Accept instant SEPA payments from your customers with zero chargebacks, no rolling reserves, and same-day settlement. This API lets you create checkout sessions and receive payment confirmations.

Overview

The Dapit Instant Payments API enables merchants to accept EUR payments via SEPA Instant Credit Transfer. Instead of credit cards, your customers pay directly from their bank account (Wise, Revolut, or any EUR-enabled bank). Payments settle in under 10 seconds and are irrevocable — no chargebacks.

Base URL:

https://www.maxafi.com/api/gateway/gateway.php

Payment Flow

The customer never leaves your website. When they choose "Pay with Instant Payments" at your checkout, your server talks to our API behind the scenes.

Authentication

All API requests require your merchant API key. Include it in one of the following request headers:

X-Api-Key: mk_your_api_key_here

or, for legacy integrations:

X-Gateway-Key: your_api_key_here

Keys beginning with mk_ are unified keys that also carry permissions, rate limits, and environment (sandbox/production) metadata. Legacy plaintext keys without a prefix remain accepted.

Your API key is provided during merchant onboarding. Keep it secret — it authenticates all requests to our API on your behalf.

Quick Start — Option A: API Integration

Your developer adds Instant Payments as a payment option on your existing checkout page. The customer never leaves your website.

Step 1: Customer selects "Pay with Instant Payments" on your checkout

Your checkout page already has credit card, ACH, etc. Add an "Instant Payments" button alongside them. When they click it, your server creates a session:

Copy// YOUR SERVER — Create a session when customer chooses Instant Payments
const response = 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_here'
  },
  body: JSON.stringify({
    amount: 49.99,
    currency: 'EUR',
    items: [
      { name: 'Premium Game Credits', qty: 1, price: 49.99, total: 49.99 }
    ],
    callback_url: 'https://yoursite.com/webhooks/dapit'
  })
});

const session = await response.json();
// session.session_token → save this (you'll need it for polling)
// Now call create_invoice to get the payment details...

Step 2: Get payment details and display on YOUR page

Copy// YOUR SERVER — Get the IBAN, beneficiary, and reference number
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());

// Display these on YOUR checkout page:
// invoice.beneficiary_name → "Longemalle Trustees OU"
// invoice.iban             → "LT913740020058585210"
// invoice.reference_number → "DP-260330-XA6HSX"
// invoice.amount           → 49.99
// invoice.invoice_number   → "INV-260330-04821"
// invoice.qr_url           → scannable EPC QR (drop into <img src>)
//
// Tell the customer:
// 1. Scan the QR with your banking app (most EU banks support this) —
//    OR transfer manually if your app is Wise / Revolut / N26 (no EPC QR support)
// 2. Beneficiary: Longemalle Trustees OU
// 3. IBAN: LT913740020058585210
// 4. Reference: DP-260330-XA6HSX (must include EXACTLY)
// 5. Choose "Instant" or "SEPA Instant" on your bank's confirmation screen
// 6. Click "I've Sent the Payment" button on your page

Step 3: Customer clicks "I Paid" — start polling

Copy// YOUR PAGE (JavaScript) — When customer clicks "I Paid"

// First, tell our API the customer says they paid
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 })
});

// Then poll every 7 seconds until payment is confirmed
const pollInterval = 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(pollInterval);
    // 🎉 Full payment confirmed!
    showPaymentSuccess(check.total_paid, check.invoice_amount);

  } else if (check.status === 'partial') {
    clearInterval(pollInterval);
    // ⚡ Partial payment — show receipt + remaining balance
    showPartialPayment(check.total_paid, check.amount_remaining, check.payments);
    // When customer sends remaining: call confirm_paid again, restart polling

  } else if (check.status === 'overpaid') {
    clearInterval(pollInterval);
    // 💰 Overpayment — order confirmed, refund will be processed
    showOverpaid(check.total_paid, check.overpaid_amount, check.refund_net, check.refund_fee);

  } else if (check.status === 'timeout') {
    clearInterval(pollInterval);
    showPaymentRetry();
  }
  // 'pending' — keep polling
}, 7000);

Step 4: Receive webhook confirmation (your server)

Copy// YOUR SERVER — Webhook endpoint receives POST when payment is confirmed
// Fires for both exact and overpayments (not for partial — only when fully paid)
app.post('/webhooks/dapit', (req, res) => {
  const { event, merchant_order_id, invoice_amount, amount_paid,
          overpaid_amount, refund_amount, refund_fee } = req.body;

  if (event === 'payment.confirmed') {
    // ✅ Payment confirmed! Update your order database.
    console.log(`Order ${merchant_order_id} paid: €${amount_paid} of €${invoice_amount}`);

    if (overpaid_amount > 0) {
      // Customer overpaid — refund of €(overpaid - fee) will be processed
      console.log(`Overpaid by €${overpaid_amount}. Refund: €${refund_amount} (fee: €${refund_fee})`);
    }

    // Mark order as paid, send confirmation email, trigger fulfillment
  }

  res.status(200).json({ received: true });
});

Quick Start — Option B: Hosted Checkout

If you don't have a developer or want the simplest possible integration, use our hosted checkout page. You just create a session and redirect — we handle the entire payment UI.

Copy// YOUR SERVER — Create session and redirect customer to our hosted page
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_here'
  },
  body: JSON.stringify({
    amount: 49.99,
    currency: 'EUR',
    items: [{ name: 'Premium Game Credits', qty: 1, price: 49.99, total: 49.99 }],
    callback_url: 'https://yoursite.com/webhooks/dapit'
  })
}).then(r => r.json());

// Redirect customer to our hosted checkout
res.redirect('https://www.maxafi.com' + session.checkout_url);
// Customer sees: your merchant name, invoice, IBAN, reference, "I Paid" button
// When confirmed, we POST to your callback_url

Verify Key

{
  "success": true,
  "merchant_id": 42,
  "merchant_name": "Acme Co.",
  "environment": "stage",
  "permissions": ["write:transactions", "read:transactions"],
  "key_type": "unified",
  "server_time": "2026-04-21T14:22:18Z"
}

{
  "success": false,
  "error": "Invalid API key"
}

curl -X POST "https://www.maxafi.com/api/gateway/gateway.php?action=verify_key" \
  -H "X-Api-Key: mk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Create Session

{
  "success": true,
  "session_id": 42,
  "session_token": "a1b2c3d4e5f6...",
  "checkout_url": "/checkout/pay.html?session=a1b2c3d4e5f6...",
  "expires_at": "2026-03-30 23:30:00",
  "amount": 49.99,
  "currency": "EUR",
  "merchant_order_id": "ORD-12345"
}

Create Invoice

{
  "success": true,
  "reference_number": "DP-260330-XA6HSX",
  "invoice_number": "INV-260330-04821",
  "amount": 49.99,
  "currency": "EUR",
  "iban": "LT913740020058585210",
  "beneficiary_name": "Longemalle Trustees OU",
  "account_name": "Dapit Financial Infrastructure",
  "bank_name": "Dapit",
  "qr_url": "https://www.maxafi.com/api/gateway/epc_qr.php?ref=DP-260330-XA6HSX&token=..."
}

Scan-to-Pay QR Code

// React / JSX
<img src={invoice.qr_url} alt="Scan to pay" width="240" height="240" />

// Plain HTML / template
<img src="{{ invoice.qr_url }}" alt="Scan to pay" />

BCD                              # service tag (fixed)
002                              # version
1                                # UTF-8
SCT                              # SEPA Credit Transfer
CNUALT21XXX                      # BIC
Longemalle Trustees OU           # beneficiary name
LT913740020058585210             # IBAN
EUR49.99                         # amount
OTHR                             # purpose code
                                 # structured ref (blank — we use unstructured)
DP-260330-XA6HSX                 # the Dapit reference
                                 # B2B info (blank)

// 1. Create session
const session = await fetch('https://www.maxafi.com/api/gateway/gateway.php?action=create_session', {
    method: 'POST',
    headers: { 'X-Api-Key': 'mk_live_...', 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 49.99, currency: 'EUR', items: [...] })
}).then(r => r.json());

// 2. Create invoice — this returns qr_url ready to render
const invoice = await fetch('https://www.maxafi.com/api/gateway/gateway.php?action=create_invoice', {
    method: 'POST',
    headers: { 'X-Api-Key': 'mk_live_...', 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: session.session_token })
}).then(r => r.json());

// 3. Render the QR + manual fallback
document.getElementById('checkout').innerHTML = `
    <h2>Pay €${invoice.amount}</h2>
    <img src="${invoice.qr_url}" alt="Scan with your banking app" />
    <p>Or transfer manually:</p>
    <p><strong>Recipient:</strong> ${invoice.beneficiary_name}</p>
    <p><strong>IBAN:</strong> ${invoice.iban}</p>
    <p><strong>Reference:</strong> ${invoice.reference_number}</p>
`;

Confirm Paid (optional)

{
  "success": true,
  "status": "polling",
  "reference": "DP-260330-XA6HSX",
  "message": "Payment verification started. We are checking for your transfer."
}

Check Payment (Polling) (optional)

{
  "success": true,
  "status": "confirmed",
  "paid_at": "2026-03-31 10:05:12",
  "invoice_amount": 7.00,
  "total_paid": 7.00,
  "payment_count": 1,
  "payments": [{ "amount": 7.00, "debtor_name": "John Smith", "debtor_iban": "DE89370400440532013000" }],
  "amount_match": true
}

{
  "success": true,
  "status": "partial",
  "invoice_amount": 7.00,
  "total_paid": 3.00,
  "amount_remaining": 4.00,
  "payment_count": 1,
  "payments": [{ "amount": 3.00, "debtor_name": "John Smith" }],
  "message": "We received €3.00 of your €7.00 payment. Remaining balance: €4.00."
}

{
  "success": true,
  "status": "overpaid",
  "paid_at": "2026-03-31 10:05:12",
  "invoice_amount": 5.00,
  "total_paid": 8.00,
  "overpaid_amount": 3.00,
  "refund_fee": 1.00,
  "refund_net": 2.00,
  "message": "Payment received! You overpaid by €3.00. A refund of €2.00 will be processed (€3.00 minus €1.00 processing fee)."
}

{
  "success": true,
  "status": "pending",
  "message": "Payment not yet detected. Checking again...",
  "poll_count": 5,
  "max_polls": 60
}

{
  "success": true,
  "status": "timeout",
  "message": "Payment not detected after maximum attempts. Please contact support."
}

Get Session

{
  "success": true,
  "session_id": 42,
  "merchant_name": "Your Store Name",
  "amount": 49.99,
  "currency": "EUR",
  "status": "confirmed",
  "reference_number": "DP-260330-XA6HSX",
  "invoice_number": "INV-260330-04821",
  "qr_url": "https://www.maxafi.com/api/gateway/epc_qr.php?ref=DP-260330-XA6HSX&token=...",
  "paid_at": "2026-03-30 22:05:12"
}

Payment Status

{
  "success": true,
  "reference_number": "DP-260330-XA6HSX",
  "invoice_number": "INV-260330-04821",
  "amount": 49.99,
  "currency": "EUR",
  "status": "confirmed",
  "confirmed_at": "2026-03-30 22:05:12"
}

List Transactions

{
  "success": true,
  "transactions": [
    {
      "reference_number": "DP-260330-XA6HSX",
      "amount": 49.99,
      "status": "confirmed",
      "confirmed_at": "2026-03-30 22:05:12"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Webhook: Payment Confirmed

When a payment is confirmed, we send a POST request to your registered callback_url with the payment details.

Webhook Payload

{
  "event": "payment.confirmed",
  "reference_number": "DP-260330-XA6HSX",
  "invoice_number": "INV-260330-04821",
  "merchant_order_id": "ORD-12345",
  "invoice_amount": 7.00,
  "amount_paid": 7.00,
  "amount_remaining": 0,
  "overpaid_amount": 0,
  "refund_amount": 0,
  "refund_fee": 0,
  "currency": "EUR",
  "paid_at": "2026-03-31 10:05:12",
  "session_token": "a1b2c3d4e5f6...",
  "customer_email": "john@example.com",
  "customer_name": "John Smith"
}

Expected Response

Return a 200 status code to acknowledge receipt. If we don't get a 200, we'll flag the notification 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'];  // YOUR order number
    $ref     = $payload['reference_number'];   // Our reference (DP-XXXXXX-XXXXXX)
    $amount  = $payload['amount'];
    $paidAt  = $payload['paid_at'];
    $email   = $payload['customer_email'];

    // Match to your order and mark as paid
    $db->query("UPDATE orders SET status = 'paid', paid_at = '$paidAt' WHERE order_id = '$orderId'");

    // Send confirmation email to customer
    // Trigger fulfillment / shipping

    error_log("Order $orderId paid: €$amount (ref: $ref)");
}

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

Webhook Security

Every webhook delivery is signed with HMAC-SHA256 using a secret specific to your merchant account. You verify the signature on your side to confirm the webhook originated from Dapit and the body was not modified in transit.

Headers

Every signed webhook delivery includes two extra headers:

Verification algorithm

1. Read the raw body (do not parse JSON yet).
2. Read X-Dapit-Timestamp and X-Dapit-Signature.
3. Reject the request if the timestamp is older than 5 minutes (replay guard).
4. Compute expected = hmac_sha256(timestamp + "." + raw_body, webhook_secret).
5. Strip the sha256= prefix from X-Dapit-Signature.
6. Compare with a constant-time string comparison (crypto.timingSafeEqual in Node, hash_equals in PHP).
7. If they match, the webhook is authentic. Only then parse the JSON and act on it.

TypeScript verification

Copy// Express / Node 18+ example
import express from "express";
import crypto from "node:crypto";

const WEBHOOK_SECRET = process.env.DAPIT_WEBHOOK_SECRET!;  // whsec_...
const MAX_AGE_SECONDS = 300;  // 5 minutes

// IMPORTANT: capture the raw body for signature verification
const app = express();
app.use("/webhooks/dapit", express.raw({ type: "application/json" }));

app.post("/webhooks/dapit", (req, res) => {
  const timestamp = req.header("X-Dapit-Timestamp");
  const signature = req.header("X-Dapit-Signature");
  const rawBody   = (req.body as Buffer).toString("utf8");

  if (!timestamp || !signature) {
    return res.status(400).send("Missing signature headers");
  }

  // Replay guard
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > MAX_AGE_SECONDS) {
    return res.status(400).send("Timestamp out of range");
  }

  // Compute expected
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const received = signature.startsWith("sha256=")
    ? signature.slice(7)
    : signature;

  // Constant-time compare
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send("Bad signature");
  }

  // Signature valid \u2014 safe to parse and act
  const event = JSON.parse(rawBody);
  // ... fulfil order (see main webhook section) ...

  res.status(200).json({ received: true });
});

PHP verification

Copy<?php
$secret    = getenv('DAPIT_WEBHOOK_SECRET');
$timestamp = $_SERVER['HTTP_X_DAPIT_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_DAPIT_SIGNATURE'] ?? '';
$rawBody   = file_get_contents('php://input');

// Replay guard \u2014 5 minute window
if (!$timestamp || abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit('Timestamp out of range');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
$received = str_starts_with($signature, 'sha256=')
    ? substr($signature, 7)
    : $signature;

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Bad signature');
}

// Signature valid \u2014 parse and act
$event = json_decode($rawBody, true);
// ... fulfil order ...

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

Session & Transaction Statuses

Error Handling

All errors return a JSON object with success: false and an error message:

{
  "success": false,
  "error": "Missing API key"
}

Testing & Environments

Every merchant account starts in staging mode. This lets you integrate and test the full payment flow against a sandbox banking environment before going live with real money.

Staging vs Production

Integration Checklist — Staging

1. Onboard with Dapit and receive your mk_live_... API key (the same key works for staging and production)
2. Confirm your account environment is set to staging — check the environment field in any create_session response
3. Build your checkout flow using Quick Start Option A or Option B
4. Test end-to-end with the test accounts below — send a small SEPA transfer from one of them to your staging custodial IBAN using your session's reference number
5. Verify your webhook endpoint receives the payment.confirmed event with valid signature
6. Once everything works, email us to flip your account to production

Test Accounts for Staging

Use these pre-funded test IBANs to simulate payments in the staging environment. Send EUR from either account to the staging custodial IBAN with the reference number from your checkout session.

Integration Checklist

• Call create_session with your API key and verify you get a session_token
• Call create_invoice and verify you receive the IBAN, beneficiary name, and reference number
• Display the payment details on your checkout page
• Send a small EUR payment (€1-5) from Wise/Revolut to the staging IBAN with the reference number
• Wait up to 60 seconds for the cron reconciler to match the credit. Optionally, call confirm_paid + poll check_payment for a faster client-side UX.
• Verify your webhook endpoint receives the payment.confirmed event with your merchant_order_id
• Call payment_status and verify it returns confirmed

Going Live

• Contact us to switch your account from staging to production
• No code changes needed — same API key, same endpoints, same flow
• Verify create_session response shows "environment": "production"
• Run one real test transaction (€1) to confirm end-to-end
• You're live!

Create Refund

Initiate a full or partial refund for a completed payment. A €1 processing fee is deducted automatically.

{
  "success": true,
  "refund_id": 42,
  "reference_number": "R7A3F2B1",
  "amount": 25.00,
  "processing_fee": 1.00,
  "status": "pending"
}
Copy

Send Refund

Execute a pending refund via SEPA transfer to the customer's IBAN. Triggers an outbound payment from our settlement bank.

List Refunds

Settlement Report

Get an aggregated settlement report for a date range — gross volume, refunds, fees, and net settlement amount with daily breakdown.

Dashboard

Recurring Billing — Overview

The recurring billing system sends periodic payment reminders to customers via SMS and/or email. Each cycle generates a new reference number and a link back to the merchant's checkout page. The customer must voluntarily initiate each payment — this is not a direct debit.

Base URL:

https://www.maxafi.com/api/recurring.php

Authentication: Same gateway merchant API key via X-Api-Key header or api_key parameter.

Create Schedule

curl -X POST https://www.maxafi.com/api/recurring.php \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_schedule",
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "customer_phone": "+4712345678",
    "delivery_method": "both",
    "frequency": "monthly",
    "amount": 99.00,
    "discount_percent": 5,
    "currency": "EUR",
    "order_items": [{"name": "Premium Plan", "qty": 1, "price": 99}],
    "payment_url": "https://merchant-site.com/pay"
  }'
Copy

{
  "success": true,
  "schedule_id": 7,
  "amount": 94.05,
  "original_amount": 99.00,
  "discount_percent": 5,
  "frequency": "monthly",
  "next_billing_date": "2026-04-03"
}
Copy

List Schedules

Update Schedule

Recurring — Configuration

Configure Twilio (SMS) and Gmail SMTP (email) credentials for payment notifications. Stored securely in the database.