Build with EasyPay

EasyPay is the leading payment platform for Mauritania. Accept mobile money payments (Bankily, Sedad, Masrvi, BFI Cash), QR code payments, NFC tap-to-pay, and web checkout -- all through a single, unified API.

This documentation covers everything you need to integrate EasyPay into your application, from creating your first checkout session to handling webhooks in production.

Payment Methods

Environments

Both environments share the same base URL: the API key decides. A checkout session created with an ek_test_ key is a sandbox session — see Testing & Sandbox.

EasyPay uses two credentials, depending on the endpoint: an API key for checkout sessions, and the session of your EasyPay account for the other merchant endpoints.

API Keys

Generate your keys in the EasyPay app — merchant account or Pro space — under Settings → API & Integration. The live key and the test key are generated together and shown once; regenerating replaces both, and the previous keys stop working at once.

Example: list your checkout sessions

curl https://easypay.emko.ink/api/v1/checkout/sessions \
  -H "X-API-Key: ek_test_abc123def456"

A missing X-API-Key header gives 400, an unknown key 401 with "message": "Invalid API key".

Merchant Session

The other merchant endpoints take the session of your EasyPay account, as the EasyPay app does: sign in with the account's phone number and PIN, then send the access token in the Authorization header.

# 1. Sign in with the phone number and PIN of your EasyPay account
curl -X POST https://easypay.emko.ink/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+22236000000",
    "pin": "1234",
    "deviceId": "order-server-1",
    "deviceName": "Order server"
  }'

# 2. Send data.tokens.accessToken with your requests
curl https://easypay.emko.ink/api/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

A wrong phone number or PIN gives 401 with "message": "Invalid credentials". Logins are limited to 10 per minute per IP address (429 beyond).

The customer always pays on the EasyPay payment page. Your server creates a checkout session with its API key; the browser only opens the session's checkoutUrl. The script https://easypay.emko.ink/sdk/easypay.js (version 2.0.0) does that part for you: it opens the page in a popup and gives your page the result. It defines a global EasyPay object. There is no npm package: @easypay/js is not published.

Open the Payment Page

Your server creates the session (see Checkout Sessions) and returns its checkoutUrl. In the browser, call EasyPay.open() inside the click handler: browsers block a popup opened after an await. When the URL comes from a request to your server made at click time, pass a function or a promise: the popup opens at once and loads the payment page as soon as the URL is known.

// Your server creates the session, with your API key (never sent to the browser)
app.post("/orders/:id/pay", async (req, res) => {
  const order = await findOrder(req.params.id); // your own lookup, not an amount from the browser
  const response = await fetch("https://easypay.emko.ink/api/v1/checkout/sessions", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.EASYPAY_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Order #" + order.id,
      amount: order.total,
      orderId: String(order.id),
      returnUrl: "https://yoursite.com/orders/" + order.id + "/return",
      callbackUrl: "https://yoursite.com/easypay/callback",
    }),
  });
  const body = await response.json();
  if (!response.ok) return res.status(502).json({ error: body.detail || body.message });

  await saveSessionToken(order.id, body.data.sessionToken);
  // Only the payment page URL goes to the browser
  res.json({ checkoutUrl: body.data.checkoutUrl });
});

If the page already has the URL (your server created the session when it rendered the payment step), pass it directly:

payButton.addEventListener("click", () => {
  EasyPay.open(checkoutUrl).then(onResult, onError);
});

In popup mode, EasyPay.open() resolves with { sessionToken, status, transactionId }. It only accepts the message of the window it opened, from the EasyPay origin, for that session. If your function or promise fails, the popup closes and the promise rejects with that error.

• The result only drives your page: confirm the order on your server, from the checkout.paid callback or by reading the session (PAID) — see Webhooks.
• A customer without an EasyPay account pays after an SMS code, and the payment waits for your approval in the EasyPay app: the page reports its result only when that payment is approved or rejected. If the customer closes the popup earlier, you get cancelled: rely on checkout.paid.
• The payment page cannot be shown inside an iframe: it is served with X-Frame-Options: DENY. Use a popup or a redirect.

Redirect

EasyPay.open(checkoutUrl, { mode: "redirect" }) sends the current tab to the payment page (or set it for the whole page with EasyPay.init({ mode: "redirect" })). You can also do without the script: answer the customer's "Pay" click on your server with a redirect to checkoutUrl. Once the payment is final, the page sends the customer back to your returnUrl with easypay_status=paid or failed, session and transactionId: a hint as well, to check on your server.

Buttons

EasyPay.renderButton(selector, options) renders a "Payer avec EasyPay" button that calls EasyPay.open(). The URL comes from options.getCheckoutUrl() (called at each click), options.checkoutUrl or the element's data-checkout-url. Elements with a data-easypay-button attribute become buttons on their own when the page loads.

<script src="https://easypay.emko.ink/sdk/easypay.js"></script>

<!-- Without JavaScript: your server writes the checkoutUrl of the session -->
<div data-easypay-button data-checkout-url="<%= checkoutUrl %>"></div>

<!-- With callbacks: the URL is asked from your server at each click -->
<div id="easypay-button"></div>
<script>
  EasyPay.renderButton("#easypay-button", {
    getCheckoutUrl: () =>
      fetch("/orders/1234/pay", { method: "POST" })
        .then((response) => response.json())
        .then((data) => data.checkoutUrl),
    onSuccess: () => { window.location.href = "/orders/1234/return"; },
    onCancel: () => console.log("Payment page closed"),
    onFailure: () => showError("Payment rejected"),
    onError: (error) => showError(error.message),
  });
</script>

Reference

Migrating from 1.x

Version 1.x took your API key in the page and created the session from the browser. Every visitor could read the key, and the API refused those calls from any other website (CORS) anyway. Move the session creation to your server with the same fields, and open the returned checkoutUrl with EasyPay.open(). For the sandbox, create the session with your ek_test_ key: nothing changes in the browser.

The EasyPay REST API uses standard HTTP verbs, takes and returns JSON, and wraps successful responses in { success, message, data }. Authentication depends on the endpoint:

Checkout Sessions

QR Codes

Payment Links

Transactions

Fees

Webhooks

These are authenticated with your merchant session (Authorization: Bearer), not with the API key. The checkout callback is configured per session with callbackUrl — see Webhooks.

A checkout session asks one customer to pay you a fixed amount. Create it from your server with your API key, send the customer to its checkoutUrl — the EasyPay payment page — and fulfil the order when you receive the signed checkout.paid callback. A session can be paid until it expires, 30 minutes after its creation.

Checkout Flow

Create a Session

Request Headers

Session Parameters

Unknown fields are ignored. The expiry time is set by EasyPay — 30 minutes — and cannot be chosen per session.

curl -X POST https://easypay.emko.ink/api/v1/checkout/sessions \
  -H "X-API-Key: ek_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order #1234",
    "amount": 5000,
    "description": "2 x T-shirt",
    "orderId": "ORDER-1234",
    "returnUrl": "https://yoursite.com/orders/1234/return",
    "cancelUrl": "https://yoursite.com/cart",
    "callbackUrl": "https://yoursite.com/easypay/callback",
    "metadata": { "cart_id": "abc123" }
  }'

Response (201 Created)

{
  "success": true,
  "message": "Success",
  "data": {
    "id": "c6ef4a5f-1d0b-49a8-a1bb-a439897c13a4",
    "sessionToken": "d3628f0cb1c74e42ac93a508a5609d9c455802651a2647f4b94b77f1b12e2df2",
    "checkoutUrl": "https://easypay.emko.ink/checkout/d3628f0cb1c74e42ac93a508a5609d9c455802651a2647f4b94b77f1b12e2df2",
    "orderId": "ORDER-1234",
    "title": "Order #1234",
    "amount": 5000,
    "currency": "MRU",
    "description": "2 x T-shirt",
    "status": "OPEN",
    "returnUrl": "https://yoursite.com/orders/1234/return",
    "cancelUrl": "https://yoursite.com/cart",
    "merchantName": "My Shop",
    "userId": "2c0491ac-3769-43f5-95dd-071dedbb1930",
    "expiresAt": "2026-10-12T14:30:00.750849",
    "sandbox": true,
    "createdAt": "2026-10-12T14:00:00.750849"
  }
}

Errors

The Payment Page

Open checkoutUrl in the customer's browser — redirect, link or popup window. For a popup, the JavaScript SDK does it for you: EasyPay.open(checkoutUrl) opens the page and gives your page the result (see JavaScript SDK). Only the URL goes to the browser: the API key never reaches it.

The page shows your business name, the title, the description and the amount; the customer chooses a wallet and pays:

• from the EasyPay app — the payment is confirmed at once;
• without an EasyPay account — the customer confirms their phone number with an SMS code, and the payment stays pending until you approve it in your EasyPay merchant app (or the wallet confirms it). It can be approved after expiresAt: the session then becomes PAID all the same.

When the payment reaches its final status, the page reports it:

• opened with window.open from your page (as EasyPay.open() does), it posts { type: "easypay_checkout_complete", sessionToken, status, transactionId } to your window, status being paid or failed;
• otherwise, about two seconds later, it sends the customer to {returnUrl}?easypay_status=paid&session={sessionToken}&transactionId={id} (failed when the payment was rejected).

If the session has a cancelUrl, the page also shows « Retour à la boutique » (back to the shop) until the customer starts paying, and on the page of an expired or cancelled session. In a popup, the link posts the same message with status cancelled and transactionId null, then closes the popup; otherwise it sends the customer to {cancelUrl}?easypay_status=cancelled&session={sessionToken}. For an expired session, expired replaces cancelled. Leaving does not cancel the session: the customer can come back and pay until expiresAt.

These signals only drive your pages: anyone can type that URL, and a customer may close the page before a pending payment is approved. Fulfil the order on the checkout.paid callback, or after reading the session and finding PAID:

// returnUrl handler: trust the session you stored, not the query string
app.get("/orders/:id/return", async (req, res) => {
  const order = await findOrder(req.params.id);
  const response = await fetch("https://easypay.emko.ink/api/v1/checkout/sessions/" + order.sessionToken);
  const { data } = await response.json();
  res.render(response.ok && data.status === "PAID" ? "thank-you" : "payment-pending");
});

Read a Session

Public: no API key needed — it is what the payment page calls. Returns the same fields as the creation response, or 404 with "message": "Checkout session not found". The payment itself (transaction id, payment time) is not included: it comes with checkout.paid.

curl https://easypay.emko.ink/api/v1/checkout/sessions/d3628f0cb1c74e42ac93a508a5609d9c455802651a2647f4b94b77f1b12e2df2

Session Status Values

A session that was not paid reads EXPIRED as soon as expiresAt is past — from this endpoint, in the list below and on the payment page.

List Sessions

Your sessions with their current status, newest first, live and sandbox together whichever key you use — check sandbox. There is no filter: any other query parameter is ignored.

curl "https://easypay.emko.ink/api/v1/checkout/sessions?page=0&size=20" \
  -H "X-API-Key: ek_test_abc123def456"

{
  "success": true,
  "message": "Success",
  "data": {
    "content": [
      {
        "sessionToken": "d3628f0cb1c74e42ac93a508a5609d9c455802651a2647f4b94b77f1b12e2df2",
        "orderId": "ORDER-1234",
        "amount": 5000.00,
        "status": "PAID",
        "sandbox": true,
        "createdAt": "2026-10-12T14:00:00.750849"
        // … same fields as a single session
      }
    ],
    "totalElements": 42,
    "totalPages": 3,
    "number": 0,
    "size": 20,
    "numberOfElements": 20,
    "first": true,
    "last": false,
    "empty": false
    // … plus "pageable" and "sort" objects
  }
}

Cancel a Session

No body. Only an OPEN session of your account can be cancelled; nothing is sent to its callbackUrl. Otherwise: 400 with "message": "Only OPEN sessions can be cancelled" or "Session does not belong to this merchant", or 404.

curl -X POST https://easypay.emko.ink/api/v1/checkout/sessions/d3628f0cb1c74e42ac93a508a5609d9c455802651a2647f4b94b77f1b12e2df2/cancel \
  -H "X-API-Key: ek_test_abc123def456"

{
  "success": true,
  "message": "Checkout session cancelled",
  "data": null
}

The former paths /api/checkout/… still answer, with Deprecation and Sunset: Sun, 18 Apr 2027 headers: use /api/v1/checkout/….

EasyPay notifies your server with signed HTTP POST requests, through two independent mechanisms: the checkout callback, sent to the callbackUrl of a checkout session, and account webhooks, registered once for your merchant account. Fulfil orders from the checkout callback: it is the only one that carries your orderId.

How It Works

Both are signed the same way: X-EasyPay-Signature is the lowercase hexadecimal HMAC-SHA256 of the raw request body — no sha256= prefix, and no signature field inside the body. Compute it over the bytes you received, never over JSON you parsed and serialised again: key order, spacing or number formatting would change the result.

Allowed URLs

Both URLs must point to a public internet address. EasyPay refuses a URL whose host is, or resolves to, a loopback, private (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), carrier-grade NAT (100.64.0.0/10), link-local (169.254.0.0/16, fe80::/10), unique-local IPv6 (fc00::/7), multicast, unspecified or otherwise reserved address, and a URL that carries credentials (https://user:password@…). Registering such a URL — POST or PUT /api/v1/webhooks, or a checkout session with that callbackUrl — is refused with 400 and the code WEBHOOK_URL_INVALID; the message says why, for example Webhook URL is not allowed: its host resolves to a private network address.

The check runs again before every delivery, on the address the request is then sent to: if your host has started to resolve to such an address, the delivery is dropped: nothing is sent, and EasyPay does not try again. A host that does not resolve yet is accepted at registration. Redirects are not followed — a 3xx answer counts as a failed attempt — so register the final URL. To receive events on your own machine, use a tunnel that gives you a public HTTPS URL (see Testing & Sandbox).

Checkout Callback — checkout.paid

When a checkout session created with a callbackUrl becomes PAID, EasyPay sends one checkout.paid event to that URL. It happens right after a customer pays from the EasyPay app, or later, when you approve a pending payment made by a customer without an EasyPay account — possibly after the session's expiry time: honour it, the money was credited to you. The first attempt leaves within about 30 seconds (deliveries are processed every 30 seconds).

Nothing is sent when a session expires or is cancelled: poll GET /api/v1/checkout/sessions/{sessionToken} (public, no authentication) to close those orders.

Request

POST {callbackUrl}
Content-Type: application/json
User-Agent: EasyPay-Webhook/1.0
X-EasyPay-Event: checkout.paid
X-EasyPay-Signature: <lowercase hex HMAC-SHA256 of the raw body, keyed with your API key>
X-EasyPay-Sandbox: true            # only for sessions created with an ek_test_ key

Payload

{
  "event": "checkout.paid",
  "sessionToken": "9f2c1e0a…",
  "orderId": "ORDER-42",
  "amount": 4500,
  "currency": "MRU",
  "status": "PAID",
  "transactionId": "3e80e143-752c-4515-92f7-bdd88fecb512",
  "paidAt": "2026-09-09T14:03:12.417",
  "sandbox": false,
  "metadata": "{\"cart_id\":\"abc123\"}",
  "fee": 0,
  "netAmount": 4500,
  "feeBearer": "PAYER"
}

The payload is flat (no data envelope). Amounts are JSON numbers and may be written with decimals (4500.00).

Signature Verification

The key is the API key that created the session — there is no separate webhook secret for the checkout callback. Sessions created with your ek_test_ key are signed with it and carry X-EasyPay-Sandbox: true, which tells you which key to use. Compare in constant time, then parse the JSON.

const crypto = require("crypto");
const express = require("express");
const app = express();

// Keep the raw bytes: the signature covers the body exactly as EasyPay sent it.
app.post("/easypay/callback", express.raw({ type: "application/json" }), (req, res) => {
  const received = req.get("X-EasyPay-Signature") || "";
  const expected = crypto
    .createHmac("sha256", process.env.EASYPAY_API_KEY) // the key that created the session
    .update(req.body)                                   // Buffer — never JSON.stringify(req.body)
    .digest("hex");

  const valid = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event === "checkout.paid" && event.status === "PAID") {
    markOrderPaid(event.orderId, event.transactionId, event.netAmount); // idempotent on event.sessionToken
  }
  res.sendStatus(200);
});

Retry Policy

Answer with any 2xx within 15 seconds and do the slow work (emails, ERP sync) afterwards. A non-2xx answer, a connection error or no answer within 15 seconds counts as a failure and is retried:

Account Webhooks

Account webhooks report the payments you collect — QR code, NFC, payment link, checkout, card — plus invoicing and recurring-billing events. They complement the checkout callback; they don't replace it.

Register an endpoint with POST /api/v1/webhooks, authenticated with your merchant session — Authorization: Bearer <accessToken>, obtained with POST /api/v1/auth/login — not with the API key. Up to 5 HTTPS endpoints per account. Signing in from a script counts as a new device: the login is refused (409 SESSION_ACTIVE_ON_ANOTHER_DEVICE) while your EasyPay app is in use, and otherwise signs the app out.

curl -X POST https://easypay.emko.ink/api/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/easypay/webhooks",
    "events": "payment.success,payment.failed",
    "description": "Order system"
  }'

{
  "data": {
    "id": "8b0d6f8e-2f4a-4c55-9d0e-6a1f3c2b7e91",
    "url": "https://yoursite.com/easypay/webhooks",
    "events": "payment.success,payment.failed",
    "active": true,
    "description": "Order system",
    "createdAt": "2026-10-12T10:00:00.123",
    "updatedAt": "2026-10-12T10:00:00.123",
    "secret": "whsec_kM9pX2vQ…"
  },
  "message": "Webhook created. Save the secret — it will not be shown again."
}

Also available: GET /api/v1/webhooks (list — the secret is never shown again), PUT /api/v1/webhooks/{id} (send url again, plus events, description or active — false pauses deliveries) and DELETE /api/v1/webhooks/{id}.

Event Types

Webhook Payload Example

Every delivery carries the envelope { event, timestamp, data }, where timestamp is the server's local time (ISO-8601, no timezone) and the headers are the same as above, with the event name in X-EasyPay-Event. For payment.*:

{
  "event": "payment.success",
  "timestamp": "2026-10-12T10:15:30.120",
  "data": {
    "transactionId": "3e80e143-752c-4515-92f7-bdd88fecb512",
    "status": "SUCCESS",
    "amount": 4500,
    "currency": "MRU",
    "paymentReference": "QR-1a2b3c4d",
    "paymentMethod": "QR_CODE",
    "senderPhone": "+2223****34",
    "correlationId": "b7c1d2e3-4f5a-4b6c-8d9e-0f1a2b3c4d5e",
    "finalizedAt": "2026-10-12T10:15:29.874",
    "fee": 0,
    "netAmount": 4500,
    "feeBearer": "PAYER"
  }
}

invoice.* events carry invoiceId, invoiceNumber, status, totalAmount, currency and clientName, plus transactionId once paid and dueDate for invoice.overdue. subscription.* events use snake_case names — subscription_id, plan_id, plan_name, then subscriber_id, amount (a string), next_billing_date, transaction_id, billing_cycle, retry_count or cancelled_at depending on the event.

Verification and Delivery

Verify exactly as for the checkout callback, with the endpoint's whsec_… secret as the key, and answer any 2xx within 15 seconds. Each event is sent right after it happens. A failed delivery (non-2xx answer, connection error, no answer within 15 seconds) is retried with the same body, same timestamp included: 1 minute later, then 5 minutes after that — 3 attempts in total. Pausing the endpoint (active: false) or removing the event from its events cancels the pending retries.

After the third failure, or when a retry could not leave within an hour (EasyPay maintenance), the event is not sent again: reconcile with GET /api/v1/transactions (merchant session). The same event can arrive more than once — for example when your 2xx is lost on the way back: deduplicate on event + transactionId.

Accept EasyPay mobile money payments on your WordPress / WooCommerce store with our official plugin. No coding required.

Installation

Configuration

Supported Features

The easypay_payment module integrates EasyPay with Odoo for seamless invoice and POS payments.

Features

Installation

Configuration

All API errors return a consistent JSON structure. Use the code field for programmatic error handling and the message field for display.

Error Response Format

{
  "status": 400,
  "error": "Bad Request",
  "code": "INVALID_AMOUNT",
  "message": "Amount must be greater than 0",
  "details": {
    "field": "amount",
    "rejectedValue": -100,
    "constraint": "must be greater than 0"
  }
}

Common Error Codes

Handling Errors in Code

try {
  const response = await fetch("https://easypay.emko.ink/api/checkout/sessions", {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ amount: 5000 }),
  });

  if (!response.ok) {
    const error = await response.json();
    switch (error.code) {
      case "INVALID_API_KEY":
        // Re-authenticate or check key configuration
        break;
      case "RATE_LIMIT_EXCEEDED":
        // Wait and retry with exponential backoff
        break;
      case "DUPLICATE_REFERENCE":
        // Use a different reference or retrieve existing session
        break;
      default:
        console.error(`[${error.code}] ${error.message}`);
    }
    return;
  }

  const data = await response.json();
  // Success -- proceed with data
} catch (err) {
  // Network error
  console.error("Network error:", err);
}

Test your integration with your ek_test_ key: sandbox checkout sessions go through the same payment page as live ones, but no money moves.

Sandbox Environment

How the Sandbox Behaves

• The 100 – 500 000 MRU amount limits do not apply.
• The customer pays on the real payment page, from the EasyPay app or — without an EasyPay account — after confirming their phone number with a real SMS code: use a number that receives SMS. There are no test phone numbers.
• Every sandbox payment is confirmed at once, without an approval step and without debiting or crediting any wallet. Failures cannot be simulated through the API.
• The session becomes PAID and checkout.paid is sent with "sandbox": true and the X-EasyPay-Sandbox: true header.

Test Wallets

Any wallet offered by the payment page can be chosen in sandbox — none is debited:

Testing Webhooks Locally

To receive webhook events on your local machine during development, use a tunneling service and pass its HTTPS URL as the callbackUrl of your test checkout sessions, or register it as an account webhook:

# Using ngrok
ngrok http 3000

# Register your ngrok URL as an account webhook (merchant session token, not the API key)
curl -X POST https://easypay.emko.ink/api/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/api/easypay-webhook",
    "events": "payment.success,payment.failed"
  }'

Going Live Checklist