Payment Gateway API

X-Api-Key:    pk_live_<token>   # public — safe to log
X-Api-Secret: sk_live_<token>   # secret — server-side only, never browser

{ "success": false, "code": "INVALID_API_KEY", "message": "Invalid API key." }

curl -X POST "https://dev.eupayv1apis.european-pay.fr/api/v1/gateway/payments" \
  -H "X-Api-Key: pk_live_YOUR_KEY" \
  -H "X-Api-Secret: sk_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29.99,
    "currency": "EUR",
    "description": "Order #1042",
    "reference": "ORDER-1042",
    "success_url": "https://yourstore.com/success",
    "cancel_url": "https://yourstore.com/cancel"
  }'

{
  "success": true,
  "data": {
    "reference": "PAY-20260617-0B25921FB72918ED",
    "amount": 29.99, "currency": "EUR",
    "status": "pending_sca",
    "payment_url": "https://eu-pay.biapi.pro/...",  // Option A: redirect
    "qr_data": {
      "qrData": "https://www.european-pay.fr/pay?data=...",  // Option B: QR
      "deepLinkData": "eupay://pay?data=..."
    },
    "created_at": "2026-06-17T12:20:20.979Z"
  }
}

{
  "payload": {
    "v": 1, "type": "gateway_qr_payment",
    "gateway_reference": "PAY-20260617-XXXXXXXX",
    "merchant": { "id": "...", "name": "My Store" },
    "amount": 29.99, "currency": "EUR",
    "expiresAt": "2026-06-17T12:30:00Z"  // 30 min TTL
  },
  "sig": "<hmac_sha256_hex>"
}

import QRCode from "qrcode";

const payment = await createPayment({ amount: 29.99, ... });
const dataUrl = await QRCode.toDataURL(payment.qr_data.qrData, {
  errorCorrectionLevel: "H",  // Required for logo overlay
  width: 400, margin: 2,
});
// <img src={dataUrl} />

async function waitForPayment(ref, ms = 600_000) {
  const end = Date.now() + ms;
  while (Date.now() < end) {
    const { data } = await fetch(
      `/api/v1/gateway/payments/${ref}/status`
    ).then(r => r.json());
    if (data.status === "completed") return data;
    if (["failed","cancelled"].includes(data.status))
      throw new Error(data.status);
    await new Promise(r => setTimeout(r, 3000));
  }
  throw new Error("timeout");
}

{
  "event": "payment.completed",
  "timestamp": "2026-06-17T12:25:30Z",
  "data": {
    "reference": "PAY-20260617-0B25921FB72918ED",
    "amount": 29.99, "currency": "EUR",
    "status": "completed",
    "merchant_reference": "ORDER-1042"
  }
}

# Webhooks are server→server POST requests from EU Pay to your URL.
# Test with webhook.site or ngrok during development.
curl -X POST "https://yoursite.com/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-EuPay-Signature: sha256=<hmac>" \
  -H "X-EuPay-Event: payment.completed" \
  -d '{"event":"payment.completed","data":{"reference":"PAY-..."}}'

Customer Rewards API

Award EuPay Points on payment events. Query balances and configure loyalty rules programmatically.

Subscriptions API

Recurring SEPA mandates for subscription billing via Powens PIS recurring payments.

// Response when fully enrolled and active:
{
  "enrolled":       true,
  "mandate_id":     "mdt_5ca4c022",
  "mandate_status": "active",
  "ready":          true,       // can submit invoices now
  "siret":          "12345678901234"
}

// Response when KYB still pending:
{ "enrolled": true, "mandate_status": "pending_kyb", "ready": false }

// Not enrolled yet:
{ "enrolled": false, "ready": false }

POST /api/v1/einvoice/invoices
X-Api-Key: pk_live_...
X-Api-Secret: sk_live_...

// If merchant is NOT enrolled yet → 403:
{
  "success": false,
  "code": "NOT_ENROLLED",
  "message": "E-invoicing is not enabled for this account.",
  "action": "Log in to the EU Pay merchant portal → Settings → E-Invoicing → Enroll"
}

// Once enrolled → 201 Created:
{
  "invoice_number":    "INV-2026-AB12CD-000001",
  "seqino_invoice_id": "draft_abc123",
  "seqino_status":     "submitted",
  "total_ttc":         1800.00,
  "_seqino": { "submitted": true, "mandate_status": "active" }
}

Returns full invoice with a live SEQINO status refresh (polls SEQINO API if seqino_status = submitted).

curl https://api.european-pay.eu/api/v1/einvoice/invoices/UUID/pdf \
  -H 'X-Api-Key: pk_live_...' \
  -H 'X-Api-Secret: sk_live_...' \
  -H 'Accept: application/pdf' \
  --output facture.pdf

POST /api/v1/product/create
Authorization: Bearer JWT
{
  "name":           "Café Noisette",
  "category":       "boissons",
  "price_ttc":      3.50,
  "vat_rate":       10,
  "stock_quantity": 500
}
// Response includes computed fields:
// "price_ht": 3.1818  "vat_amount": 0.3182  "vat_code": "TVA10"

// Step 1: Get presigned URL (expires in 5 min)
POST /api/v1/product/upload-image-url
{ "filename": "coffee.jpg", "contentType": "image/jpeg" }

// Step 2: PUT bytes directly to S3 (not via API)
PUT https://s3.eu-west-3.amazonaws.com/...?X-Amz-Signature=...
Content-Type: image/jpeg
<raw image bytes>

// Step 3: Save CDN URL on the product
PUT /api/v1/product/:id
{ "image_url": "https://cdn.european-pay.fr/product-images/UUID.jpg" }

// 1. Build the payload
const payload = {
  v: 1,
  type: "powens_qr_payment_request",  // or "gateway_qr_payment"
  requestId: crypto.randomUUID(),
  merchant:  { id, merchantId, name, euPayId },
  amount:    29.99,    // null = customer enters any amount
  currency:  "EUR",
  expiresAt: null,
};

// 2. HMAC-SHA256 sign (server-side — secret never leaves backend)
const sig = crypto.createHmac("sha256", config.jwt.secret)
  .update(JSON.stringify(payload)).digest("hex");

// 3. Base64url-encode the envelope
const encoded = Buffer.from(JSON.stringify({ payload, sig })).toString("base64url");

// 4. Build QR URL
const qrData = `https://www.european-pay.fr/pay?data=${encodeURIComponent(encoded)}`;

// Error correction MUST be level H (30%) for logo overlay:
// QRCode.toDataURL(qrData, { errorCorrectionLevel: "H", width: 900 });

POST /api/v1/table-order/tables
Authorization: Bearer JWT
{ "name": "Table 4", "zone": "Terrasse", "capacity": 4 }
→ qr_token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
→ qr_url:   https://european-pay.fr/order/UUID/a1b2c3...

// To regenerate (e.g. card stolen):
POST /api/v1/table-order/tables/:id/refresh-qr

// Public — no auth — rate-limited: 60 req/min per IP
GET /api/v1/table-order/menu/UUID/a1b2c3...

// Security:
// • merchantId must be valid UUID format
// • token must be 32 hex chars
// • Both invalid → same 404 (prevents enumeration)
// • table.status must be 'active'

// Response:
{ "table": {...}, "merchant": {...},
  "menu": { "boissons": [...], "plats": [...] },
  "offers": [...], "productOffers": [...] }

// Rate-limited: 10 orders / 5 min per IP
POST /api/v1/table-order/menu/UUID/a1b2c3...
{
  "items":      [{ "productId": "3f8a...", "quantity": 2, "notes": "sans sucre" }],
  "orderType":  "dine_in",   // "dine_in" | "takeaway"
  "payNow":     false         // true → Powens PIS initiated
}

// Server enforces:
// • Max 30 items per order
// • All productIds must belong to THIS merchant (prevents injection)
// • All products must have is_available = true
// • Takeaway always pay_now (server-side, not client-trusted)
// • All strings stripped of HTML tags (XSS prevention)

// Decoded gateway QR payload:
{
  "v": 1,
  "type": "gateway_qr_payment",           // distinguishes from merchant QR
  "requestId":         "PAY-20260617-...",
  "gateway_reference": "PAY-20260617-...",  // links back to gateway transaction
  "merchant": { "id": "...", "name": "My Store" },
  "amount": 29.99, "currency": "EUR",
  "expiresAt": "2026-06-17T20:50:00Z"
}

// Completion chain:
// 1. Customer scans → POST /qr/pay → stores metadata.qr.gateway_reference
// 2. Powens webhook → marks QR transaction completed
// 3. Webhook handler finds gateway_reference → marks gateway transaction completed
// 4. Fires merchant webhook_url: { event: 'payment.completed' }