ecomPay card payments: developer guide

import express from 'express';
const app = express();
app.use(express.json());
app.use(express.static('public'));

const ECOMPAY = 'https://api.ecompay.co.uk';
const KEY = process.env.ECOMPAY_SECRET_KEY; // sk_test_... from your dashboard

// 1. The page asks for a checkout session.
app.post('/api/checkout', async (req, res) => {
  const r = await fetch(`${ECOMPAY}/v1/checkout/sessions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: 4999,                 // £49.99
      currency: 'GBP',
      reference: 'order_1001',      // your order id
      description: 'Blue running shoes, size 9',
      customer: { email: req.body.email },
    }),
  });
  const session = await r.json();
  if (!r.ok) return res.status(400).json(session);
  // Only the client_secret goes to the browser.
  res.json({ clientSecret: session.client_secret, id: session.id });
});

// 3. ecomPay tells us the result. Verify the signature, then mark the order paid.
import crypto from 'node:crypto';
function verifyWebhook(rawBody, header, secret) {
  const p = Object.fromEntries(String(header || '').split(',').map((x) => x.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest('hex');
  const same = expected.length === String(p.v1).length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(String(p.v1)));
  return same && Math.abs(Date.now() / 1000 - Number(p.t)) < 300;
}
const seen = new Set(); // use your database for this in production
app.post('/webhooks/ecompay', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifyWebhook(req.body, req.get('Ecompay-Signature'), process.env.ECOMPAY_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  if (seen.has(event.id)) return res.sendStatus(200);   // the same event can arrive twice
  seen.add(event.id);
  if (event.type === 'session.completed') {
    markOrderPaid(event.data.reference, event.data.id); // your code
  }
  res.sendStatus(200);
});

// 4. The thank-you page asks the server, never the browser, whether it is really paid.
app.get('/api/order-status', async (req, res) => {
  const r = await fetch(`${ECOMPAY}/v1/checkout/sessions/${req.query.session_id}`, { headers: { Authorization: `Bearer ${KEY}` } });
  const s = await r.json();
  res.json({ paid: r.ok && s.status === 'paid' });
});

app.listen(3000);

<form id="buy">
  <input id="email" type="email" placeholder="Email for your receipt" required>
  <button>Buy for £49.99</button>
</form>
<div id="pay"></div>

<script src="https://api.ecompay.co.uk/v1/ecompay.js"></script>
<script>
  document.getElementById('buy').addEventListener('submit', async (e) => {
    e.preventDefault();
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: document.getElementById('email').value }),
    });
    const { clientSecret, id } = await r.json();
    EcomPay.checkout({ clientSecret })
      .on('complete', () => { location.href = '/thanks?session_id=' + id; })
      .mount('#pay');
  });
</script>

Add ecomPay card payments to this site.

Read the integration guide at https://api.ecompay.co.uk/llms-full.txt and follow it exactly.

Summary of what to build:
1. A server route that creates a checkout session with POST https://api.ecompay.co.uk/v1/checkout/sessions, using the secret key from the environment variable ECOMPAY_SECRET_KEY (never in browser code). Send amount in minor units (pence), currency, our order reference and the customer email. Return only the client_secret and session id to the browser.
2. On the checkout page, load <script src="https://api.ecompay.co.uk/v1/ecompay.js"></script>, call EcomPay.checkout({ clientSecret }).on('complete', ...).mount('#pay'), and on complete send the customer to a thank-you page.
3. A webhook route that verifies the Ecompay-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" with ECOMPAY_WEBHOOK_SECRET>, constant-time compare, reject if t is older than 5 minutes), then marks the order paid on session.completed. Make it idempotent: the same event can arrive twice, so skip event ids you have seen. The webhook address is registered in the ecomPay dashboard (Developers, Webhook) or with POST https://api.ecompay.co.uk/v1/webhook_endpoints; the secret returned there is ECOMPAY_WEBHOOK_SECRET.
4. On the thank-you page, confirm on the server with GET https://api.ecompay.co.uk/v1/checkout/sessions/{id} and only show "paid" when status is "paid". Never mark an order paid from browser code alone.

Use test card 4012 0000 0006 0085 (any future expiry, any CVC) to try it. Webhook addresses must be public https, so while developing locally rely on step 4 or use a tunnel. Tell me where to put ECOMPAY_SECRET_KEY and ECOMPAY_WEBHOOK_SECRET.

curl https://api.ecompay.co.uk/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 4999, "currency": "GBP", "reference": "order_1001", "customer": {"email": "sam@example.com"}}'

{
  "id": "cs_test_8HAbtgvZuqCktLdzMouJJ2EE",
  "object": "checkout.session",
  "status": "open",
  "livemode": false,
  "amount": 4999,
  "amount_refunded": 0,
  "currency": "GBP",
  "reference": "order_1001",
  "description": null,
  "customer": { "email": "sam@example.com" },
  "billing_address": null,
  "shipping_address": null,
  "success_url": null,
  "cancel_url": null,
  "expires_at": "2026-10-15T12:30:00.000Z",
  "attempts": 0,
  "failure_code": null,
  "failure_message": null,
  "payment": null,
  "paid_at": null,
  "created_at": "2026-10-15T12:00:00.000Z",
  "metadata": {},
  "client_secret": "cs_test_8HAbtgvZuqCktLdzMouJJ2EE_secret_...",
  "url": "https://api.ecompay.co.uk/c/cs_test_8HAbtgvZuqCktLdzMouJJ2EE?s=..."
}

<div id="pay"></div>
<script src="https://api.ecompay.co.uk/v1/ecompay.js"></script>
<script>
  const checkout = EcomPay.checkout({ clientSecret: CLIENT_SECRET });
  checkout.on('ready', (s) => {});                 // form is showing; s has id, status, amount, currency
  checkout.on('complete', (s) => {});              // the customer has paid (confirm on your server)
  checkout.on('failed', (s) => {});                // session failed after the last allowed attempt
  checkout.on('error', (e) => {});                 // e.code, for example invalid_client_secret
  checkout.mount('#pay');                          // a CSS selector or an element
  // checkout.unmount();
</script>

curl https://api.ecompay.co.uk/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/webhooks/ecompay"}'

{
  "id": "evt_...",
  "type": "session.completed",
  "created": "2026-10-15T12:01:05.000Z",
  "livemode": false,
  "data": { ...the session object, without client_secret or url }
}

import crypto from 'node:crypto';
export function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(',').map((x) => x.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest('hex');
  const ok = expected.length === p.v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
  return ok && Math.abs(Date.now() / 1000 - Number(p.t)) < 300;
}

function ecompay_verify(string $rawBody, string $header, string $secret): bool {
  parse_str(str_replace(',', '&', $header), $p);
  $expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
  return hash_equals($expected, $p['v1']) && abs(time() - (int) $p['t']) < 300;
}

import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    p = dict(x.split('=') for x in header.split(','))
    expected = hmac.new(secret.encode(), f"{p['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p['v1']) and abs(time.time() - int(p['t'])) < 300

{ "id": "re_...", "object": "refund", "session": "cs_test_...", "amount": 1500, "status": "succeeded", "reason": null, "failure_message": null, "created_at": "..." }

{
  "error": {
    "code": "parameter_invalid",
    "param": "amount",
    "message": "amount must be a whole number in minor units.",
    "fix": "Send 4999 for £49.99, not 49.99.",
    "doc_url": "https://docs.ecompay.co.uk/#error-parameter_invalid",
    "request_id": "req_..."
  }
}

// app/api/checkout/route.ts
export async function POST(req: Request) {
  const { email } = await req.json();
  const r = await fetch('https://api.ecompay.co.uk/v1/checkout/sessions', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ECOMPAY_SECRET_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 4999, currency: 'GBP', reference: 'order_1001', customer: { email } }),
  });
  const s = await r.json();
  if (!r.ok) return Response.json(s, { status: 400 });
  return Response.json({ clientSecret: s.client_secret, id: s.id });
}

// app/checkout/Pay.tsx
'use client';
import Script from 'next/script';
import { useEffect, useRef } from 'react';
declare global { interface Window { EcomPay: any } }

export default function Pay({ clientSecret, id }: { clientSecret: string; id: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const start = () => {
    if (!window.EcomPay || !ref.current || ref.current.childElementCount) return;
    window.EcomPay.checkout({ clientSecret })
      .on('complete', () => { location.href = `/thanks?session_id=${id}`; })
      .mount(ref.current);
  };
  useEffect(start, [clientSecret]);
  return <><Script src="https://api.ecompay.co.uk/v1/ecompay.js" onLoad={start} /><div ref={ref} /></>;
}

// app/api/webhooks/ecompay/route.ts
import crypto from 'node:crypto';
export async function POST(req: Request) {
  const raw = await req.text();
  const p = Object.fromEntries((req.headers.get('ecompay-signature') || '').split(',').map((x) => x.split('=')));
  const expected = crypto.createHmac('sha256', process.env.ECOMPAY_WEBHOOK_SECRET!).update(`${p.t}.${raw}`).digest('hex');
  const same = expected.length === String(p.v1).length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(String(p.v1)));
  if (!same || Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return new Response('bad signature', { status: 400 });
  const event = JSON.parse(raw);
  if (await alreadyHandled(event.id)) return new Response('ok');       // your database
  if (event.type === 'session.completed') await markOrderPaid(event.data.reference, event.data.id);
  return new Response('ok');
}

<?php
// create-session.php
$body = json_encode(['amount' => 4999, 'currency' => 'GBP', 'reference' => 'order_1001']);
$ch = curl_init('https://api.ecompay.co.uk/v1/checkout/sessions');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ECOMPAY_SECRET_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_RETURNTRANSFER => true,
]);
$session = json_decode(curl_exec($ch), true);
header('Content-Type: application/json');
echo json_encode(['clientSecret' => $session['client_secret'], 'id' => $session['id']]);

import os, requests
from flask import Flask, request, jsonify
app = Flask(__name__)
ECOMPAY = 'https://api.ecompay.co.uk'

@app.post('/api/checkout')
def checkout():
    r = requests.post(f'{ECOMPAY}/v1/checkout/sessions',
        headers={'Authorization': f"Bearer {os.environ['ECOMPAY_SECRET_KEY']}"},
        json={'amount': 4999, 'currency': 'GBP', 'reference': 'order_1001', 'customer': {'email': request.json['email']}})
    s = r.json()
    if not r.ok:
        return jsonify(s), 400
    return jsonify(clientSecret=s['client_secret'], id=s['id'])