Bank cards

Environments

The API key you send decides the environment — there is nothing else to configure.

Before you start

Three things to check — they account for nearly every integration error.

Taking a payment

The sequence is identical in both environments, from the first call through to the final webhook.

1. You initiate the payment from your server.
2. KPay replies with a payment URL (`gatewayUrl`) and status `PENDING`.
3. You redirect the customer there: they pick card, enter their number in the Stripe form and complete 3-D Secure if their bank requires it.
4. KPay updates the status and sends the webhook to your server.
5. The customer is redirected to your `returnUrl`.

Initiate a payment

const res = await fetch("https://test.admin.kpay.site/api/v1/payments/init", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KPAY_API_KEY,
    "X-Secret-Key": process.env.KPAY_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "amount": 25,
  "paymentMethod": "CARD",
  "externalId": "CMD-2026-001",
  "returnUrl": "https://votre-site.com/merci",
  "cancelUrl": "https://votre-site.com/panier",
  "description": "Commande #2026-001",
  "customerEmail": "client@example.com"
}),
});
const data = await res.json();

Response

Redirect the customer to `gatewayUrl`. The `isTest` field tells you the environment: handle the response the same way in both cases.

{
  "id": "9f1c8a2e-...",
  "reference": "KPAY-A1B2C3D4",
  "externalId": "CMD-2026-001",
  "status": "PENDING",
  "mode": "GATEWAY",
  "amount": 25,
  "gatewayUrl": "https://pay.kpay.cm/pay/gw_YbSiijvNB0rRrPJ5...",
  "isTest": true
}

Test cards

Test mode mounts the real Stripe form. Enter one of these numbers there: it decides the outcome, exactly as in production.

Failure reasons

When a payment fails, `failureReason` explains why in terms you can show your customer.

Customer abandons

In test as in production, a customer may close the tab without paying. The transaction then stays pending and no webhook is sent. To reproduce it, open the payment page then close it without submitting the form.

Statuses

Only three outcomes, and only one means you got paid.

The browser return

KPay appends to your returnUrl: status, reference, externalId, ts and sig. The signature covers the string "status|reference|externalId|ts", as HMAC-SHA256 with your application's gateway secret.

import crypto from "crypto";

/**
 * Vérifie les paramètres ajoutés à votre returnUrl par KPay.
 *
 * Sert à afficher le bon message au client. Ne livrez JAMAIS une commande
 * sur cette seule base : ces paramètres passent par son navigateur.
 * C'est le webhook qui fait foi.
 */
export function verifyReturn(query, gatewaySecret) {
  const { status, reference, externalId, ts, sig } = query;

  const expected = crypto
    .createHmac("sha256", gatewaySecret)
    .update(`${status}|${reference}|${externalId ?? ""}|${ts}`)
    .digest("hex");

  return sig === expected;
}

Common errors

What you will see most often, and why.

Webhooks

Webhooks are sent and signed the same way in both environments. The `isTest` field lets you tell them apart if you use one URL for both testing and production.

POST /votre-endpoint HTTP/1.1
X-KPay-Signature: 8f2c9a...
Content-Type: application/json

{
  "event": "payment.completed",
  "reference": "KPAY-A1B2C3D4",
  "externalId": "CMD-2026-001",
  "amount": 25,
  "currency": "USD",
  "status": "COMPLETED",
  "isTest": true
}

Verify the signature

Every webhook carries an X-KPAY-Signature header: an HMAC-SHA256 of the raw request body, computed with your application's secret. Compare it before processing anything — this is what tells a genuine KPay notification from a forged request. Use the RAW body, not the re-serialised object: regenerating the JSON changes whitespace and breaks the signature.

import express from "express";
import crypto from "crypto";

const app = express();

// express.raw, PAS express.json : la signature porte sur les octets reçus.
app.post(
  "/webhooks/kpay",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-kpay-signature"];
    const expected = crypto
      .createHmac("sha256", process.env.KPAY_WEBHOOK_SECRET)
      .update(req.body)              // le Buffer brut
      .digest("hex");

    if (signature !== expected) {
      return res.status(401).send("signature invalide");
    }

    const event = JSON.parse(req.body.toString());

    // Répondez 200 vite, traitez ensuite : un traitement lent fait
    // retenter KPay et vous recevrez le même événement plusieurs fois.
    res.sendStatus(200);

    if (event.status === "COMPLETED") {
      // Idempotence : cette commande est peut-être déjà livrée.
      fulfillOrderOnce(event.externalId, event.reference);
    }
  },
);

app.listen(3000);

Going live

Once your tests pass:

1. Swap your test keys for production keys.
2. Check that your webhook and return URLs point to your real domain.
3. Run one small real payment before opening up traffic.

Related resources