Authorization: Bearer mpk_live_<key_id>.<secret>
Authorization: Bearer mpk_test_<key_id>.<secret>

• The key alone resolves your merchant account, integration and environment. An account identifier sent in a body is never used for authorisation.
• A live key is re-authorised on every request against your account's current permission to accept live payments; a test key is unaffected.
• The secret half is stored only as a SHA-256 hash and compared in constant time. It is shown once, at creation, and cannot be recovered.
• Call the API from your own server only. Never place a key in browser code.

• Send items only. A request that carries items together with amount_minor, price_id, product_id or a top-level quantity is refused with invalid_request.
• MIRRA computes the total as the sum of price_minor × quantity from its own approved price records. A total sent by your site or a browser is never used.
• Every price_id must belong to your account and this environment, and must be active and approved — otherwise price_not_found or price_not_active.
• One cart, one currency. Mixed currencies are refused with mixed_currencies_not_supported. There is no currency conversion in checkout creation.
• Between 1 and 50 distinct items per cart; each quantity is a whole number of at least 1. The same price_id twice in one cart is refused.
• Idempotency-Key is required: the same key with the same cart returns the original checkout; the same key with a different cart is refused with idempotency_key_reuse.
• One cart creates exactly one payment and one checkout_url — never one payment per product.

# Multi-product cart. MIRRA adds up its own approved prices.
curl -X POST "https://mirrapaysolution.com/api/public/v1/checkout/sessions" \
  -H "Authorization: Bearer $MIRRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-123" \
  -d '{"items":[{"price_id":"84df4deb-e50b-4040-bcab-5ead5a6d6cd3","quantity":4},{"price_id":"1f0b2c9e-2f4a-4c11-9d2e-77a1b3c4d5e6","quantity":2}],"reference":"ORDER-123","description":"Seafood order #123","customer_name":"John Smith","customer_email":"customer@example.com"}'

• This endpoint is catalogue-free: price_id, product_id and items are refused with invalid_request. Use POST /checkout/sessions when you want MIRRA to hold your products.
• Server-to-server only. A request carrying a browser Origin header is refused with server_to_server_required — your secret key must never reach browser code.
• Idempotency-Key is required. The same key with the same body returns the original payment; the same key with a different body is refused with idempotency_key_reuse.
• amount_minor is in minor units: 42300 means $423.00 USD. It must be a positive whole number.
• currency must be one of AED, USD, EUR, GBP.
• One call creates exactly one payment, one checkout session and one checkout_url. Retries never charge twice.
• The same route also serves the older sub-account API. mpk_live_/mpk_test_ keys are Merchant Integration API credentials and require checkout:create; msk_live_/msk_test_ keys are Sub-account API credentials and require payments:write. The two key families are separate systems and are not interchangeable.

# 42300 = $423.00 USD. Call from YOUR SERVER ONLY.
curl -X POST https://mirrapaysolution.com/api/public/v1/payments \
  -H "Authorization: Bearer $MIRRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-123" \
  -d '{"amount_minor": 42300, "currency": "USD", "description": "Seafood order #123", "reference": "ORDER-123", "customer_name": "John Smith", "customer_email": "john@example.com", "success_url": "https://seafoodpremium.world/payment/mirra/success", "cancel_url": "https://seafoodpremium.world/en/checkout"}'

{
  "data": {
    "id": "3c7b18d2-90ae-4a51-8f6c-1d2e3f405162",
    "object": "payment",
    "payment_request_id": "3c7b18d2-90ae-4a51-8f6c-1d2e3f405162",
    "status": "open",
    "amount_minor": 42300,
    "currency": "USD",
    "description": "Seafood order #123",
    "reference": "ORDER-123",
    "checkout_url": "https://mirrapaysolution.com/pay/9f2c…",
    "payment_reference": "MR-10241",
    "session_id": "b41d9c07-53ea-49c6-8f5b-2a0c9d7e1f34",
    "success_url": "https://seafoodpremium.world/payment/mirra/success",
    "cancel_url": "https://seafoodpremium.world/en/checkout",
    "livemode": true,
    "expires_at": "2026-01-14T10:31:22.104Z",
    "created_at": "2026-01-14T09:31:22.104Z"
  },
  "request_id": "req_…"
}

• data.id from POST /payments is the payment request id — it is NOT the webhook's data.payment_id. They are different objects.
• Correlate with reference, or with payment_request_id, which is present in both the creation response and the webhook payloads.
• reference is your own value and is not made globally unique across merchants by MIRRA.

• Calculate the order total in your own trusted backend from your own authoritative data, then send that locked amount. Never forward a total that a browser could edit.
• Your website must call your own backend, and your backend calls MIRRA. A request carrying a browser Origin header is refused with server_to_server_required.
• Idempotency-Key is required in dynamic mode: a retried cart submission returns the original checkout instead of charging twice.
• quantity must be omitted or exactly 1 — the amount you send is already the order total.
• currency must be one of the currencies MIRRA can charge today: AED, USD, EUR, GBP.
• Redirect the customer to data.checkout_url. The payer never sees an editable amount field.
• A return to your success URL is not proof of payment. Confirm from the signed webhook or by reading the session back.

curl "https://mirrapaysolution.com/api/public/v1/products?limit=50" \
  -H "Authorization: Bearer $MIRRA_API_KEY"

{
  "data": [
    {
      "object": "product",
      "price_id": "84df4deb-e50b-4040-bcab-5ead5a6d6cd3",
      "product_id": null,
      "name": "Bamboo Lobster — 1 kg",
      "description": "Fresh, packed on ice.",
      "image_url": "https://cdn.example/lobster.jpg",
      "price_minor": 5000,
      "currency": "USD",
      "sku": "LOBSTER-1KG",
      "active": true,
      "available": true,
      "created_at": "2026-09-15T09:04:11.204Z",
      "updated_at": "2026-09-15T09:04:11.204Z"
    }
  ],
  "has_more": false,
  "livemode": true,
  "request_id": "8f2a…"
}

# Dynamic cart total — call this from your server, never from a browser.
curl -X POST "https://mirrapaysolution.com/api/public/v1/checkout/sessions" \
  -H "Authorization: Bearer $MIRRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-123" \
  -d '{
  "amount_minor": 42300,
  "currency": "USD",
  "description": "Seafood order #123",
  "reference": "ORDER-123",
  "customer_name": "Nuel Jo",
  "customer_email": "customer@example.com"
}'

# Fixed MIRRA price instead of a cart total:
curl -X POST "https://mirrapaysolution.com/api/public/v1/checkout/sessions" \
  -H "Authorization: Bearer $MIRRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-123" \
  -d '{
  "price_id": "1f9c2b64-1d3e-4a91-b0c8-9e4a12345678",
  "quantity": 1,
  "reference": "ORDER-123"
}'

{
  "data": {
    "id": "7c0f9a52-4a1d-4a0e-9b1a-2f6d5e8c1234",
    "object": "checkout.session",
    "status": "open",
    "amount_minor": 42300,
    "currency": "USD",
    "quantity": 1,
    "description": "Seafood order #123",
    "reference": "ORDER-123",
    "payment_id": "b8e1…",
    "payment_reference": "MR-0440EAF284",
    "checkout_url": "https://mirrapaysolution.com/pay/abc123",
    "success_url": "https://shop.example/payment/success",
    "cancel_url": "https://shop.example/payment/cancel",
    "livemode": true,
    "expires_at": "2026-09-16T11:12:04.881Z",
    "created_at": "2026-09-16T10:12:04.881Z"
  },
  "request_id": "8f2a…"
}

curl "https://mirrapaysolution.com/api/public/v1/checkout/sessions/7c0f9a52-4a1d-4a0e-9b1a-2f6d5e8c1234" \
  -H "Authorization: Bearer $MIRRA_API_KEY"

{
  "data": {
    "id": "7c0f9a52-4a1d-4a0e-9b1a-2f6d5e8c1234",
    "object": "checkout.session",
    "status": "completed",
    "amount_minor": 42300,
    "currency": "USD",
    "quantity": 1,
    "description": "Seafood order #123",
    "reference": "ORDER-123",
    "customer_email": "customer@example.com",
    "payment_reference": "MR-0440EAF284",
    "paid_at": "2026-09-16T10:15:22.104Z",
    "checkout_url": "https://mirrapaysolution.com/pay/abc123",
    "livemode": true,
    "expires_at": "2026-09-16T11:12:04.881Z",
    "completed_at": "2026-09-16T10:15:22.104Z",
    "created_at": "2026-09-16T10:12:04.881Z"
  },
  "request_id": "8f2a…"
}

# 42300 = $423.00 USD. Call from YOUR SERVER ONLY.
curl -X POST https://mirrapaysolution.com/api/public/v1/payments \
  -H "Authorization: Bearer $MIRRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ORDER-123" \
  -d '{"amount_minor": 42300, "currency": "USD", "description": "Seafood order #123", "reference": "ORDER-123", "customer_name": "John Smith", "customer_email": "john@example.com", "success_url": "https://seafoodpremium.world/payment/mirra/success", "cancel_url": "https://seafoodpremium.world/en/checkout"}'

{
  "data": {
    "id": "b41e7d02-8a4c-4c39-9a5f-2a1c7d9e4f10",
    "object": "payment",
    "status": "open",
    "amount_minor": 42300,
    "currency": "USD",
    "description": "Seafood order #123",
    "reference": "ORDER-123",
    "checkout_url": "https://mirrapaysolution.com/pay/abc123",
    "payment_reference": "MR-0440EAF284",
    "session_id": "7c0f9a52-4a1d-4a0e-9b1a-2f6d5e8c1234",
    "livemode": true,
    "expires_at": "2026-09-16T11:12:04.881Z",
    "created_at": "2026-09-16T10:12:04.881Z"
  },
  "request_id": "8f2a…"
}

{
  "error": { "code": "invalid_request" },
  "request_id": "8f2a…"
}

Errors carry a stable machine code and nothing else. Database messages, stack traces and infrastructure details are never returned.

Every response body — success or error — carries a unique request_id. Quote it when contacting support.

Rate-limit response headers are not returned yet. Handle HTTP 429 and retry with backoff.

• A return is never proof of payment. Read the payment or wait for the signed event before you release goods, credit an account or send a licence.
• MIRRA appends mirra_payment_id to your success and cancel URLs, so your page knows which payment to check.
• Both URLs must be absolute and https, at most 512 characters, and must start with one of the website addresses you registered for the same environment. Local addresses such as http://localhost:3000 are allowed in test only.
• If you send no URL, the default recorded for that environment is used. If there is no default either, the customer stays on the MIRRA receipt page.
• Once a payment is created its return URLs are fixed and cannot be changed, so a later request cannot redirect an existing payment somewhere else.

// Your success page — verify before you fulfil.
app.get("/payment/success", async (req, res) => {
  const id = req.query.mirra_payment_id; // appended by MIRRA on return
  if (!id) return res.status(400).send("missing payment reference");

  const check = await fetch(`https://mirrapaysolution.com/api/public/v1/payments/${id}`, {
    headers: { Authorization: `Bearer ${process.env.MIRRA_API_KEY}` },
  });
  const payload = await check.json();

  // Only a succeeded payment reported by MIRRA may release the order.
  if (payload.data?.payment_status === "succeeded") {
    await fulfilOrder(payload.data.reference);
    return res.render("thank-you");
  }
  res.render("payment-pending");
});

Failed deliveries are retried up to 6 times with increasing delays. Every attempt repeats the same Mirra-Event-Id value, so de-duplicate on it and treat repeats as the same event.

Signed payload

<timestamp>.<raw_request_body>

Algorithm

HMAC-SHA256, hex encoded

Replay tolerance

300 seconds

• Verify the signature over the RAW request body before parsing it.
• Reject deliveries whose timestamp is outside the tolerance window to defeat replay.
• Compare signatures in constant time.
• Never accept an event because of the sending IP address.
• Treat Mirra-Event-Id as the de-duplication key: the same event id may arrive more than once.
• Respond 2xx quickly and process asynchronously.

// Verify every delivery before trusting it.
import crypto from "node:crypto";

function verify(rawBody, timestamp, signature, secret) {
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(signature, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

{
  "id": "evt_<payment_id>_payment_succeeded",
  "type": "payment.succeeded",
  "created_at": "2026-01-14T09:31:22.104Z",
  "livemode": true,
  "data": {
    "payment_id": "8f0c1f3a-2b44-4d90-9a1f-7c2d5e6f8a11",
    "payment_request_id": "3c7b18d2-90ae-4a51-8f6c-1d2e3f405162",
    "reference": "ORDER-123",
    "gross_amount": 42300,
    "fee_amount": 4230,
    "additional_fee_amount": 0,
    "net_amount": 38070,
    "currency": "USD",
    "payment_status": "succeeded",
    "settlement_status": "available"
  }
}

{
  "id": "evt_<payment_id>_payment_failed",
  "type": "payment.failed",
  "created_at": "2026-01-14T09:33:02.881Z",
  "livemode": true,
  "data": {
    "payment_id": "8f0c1f3a-2b44-4d90-9a1f-7c2d5e6f8a11",
    "payment_request_id": "3c7b18d2-90ae-4a51-8f6c-1d2e3f405162",
    "reference": "ORDER-123",
    "gross_amount": 42300,
    "fee_amount": 0,
    "additional_fee_amount": 0,
    "net_amount": 0,
    "currency": "USD",
    "payment_status": "failed",
    "settlement_status": "none"
  }
}

{
  "id": "evt_<session_id>_checkout_session_completed",
  "type": "checkout.session.completed",
  "created_at": "2026-01-14T09:31:22.310Z",
  "livemode": true,
  "data": {
    "session_id": "b41d9c07-53ea-49c6-8f5b-2a0c9d7e1f34",
    "payment_id": "8f0c1f3a-2b44-4d90-9a1f-7c2d5e6f8a11",
    "payment_request_id": "3c7b18d2-90ae-4a51-8f6c-1d2e3f405162",
    "reference": "ORDER-123",
    "amount_minor": 42300,
    "currency": "USD"
  }
}

Authorization: Bearer msk_live_<key_id>.<secret>
Authorization: Bearer msk_test_<key_id>.<secret>

• A key resolves the account on its own. Any account identifier sent in a body or query string is ignored for authorisation, so one key can never read another merchant's data.
• A live key rejects requests made against test credentials and the reverse, so the two environments can never be mixed by accident.
• The secret half of a key is stored only as a SHA-256 hash and compared in constant time. It is shown once, at creation, and cannot be recovered afterwards.

curl -X POST "https://mirrapaysolution.com/api/public/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8891-attempt-1" \
  -d '{
  "amount_minor": 10000,
  "currency": "USD",
  "description": "Advanced course",
  "reference": "order-8891",
  "success_url": "https://shop.example/payment/success",
  "cancel_url": "https://shop.example/payment/cancel"
}'

{
  "data": {
    "id": "MR-0440EAF284",
    "reference": "order-8891",
    "status": "open",
    "amount_minor": 42100,
    "currency": "USD",
    "description": "Advanced course",
    "checkout_url": "https://mirrapaysolution.com/pay/abc123",
    "payment_id": null,
    "gross_amount": 42100,
    "fee_amount": null,
    "additional_fee_amount": null,
    "net_amount": null,
    "payment_status": "open",
    "settlement_status": "not_settled",
    "fee_bps": 900,
    "created_at": "2026-09-06T10:12:04.881Z",
    "updated_at": "2026-09-06T10:12:04.881Z",
    "livemode": true
  },
  "request_id": "8f2a…"
}

curl "https://mirrapaysolution.com/api/public/v1/payments?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "MR-0440EAF284",
      "reference": "order-8891",
      "status": "succeeded",
      "amount_minor": 42100,
      "description": "Advanced course",
      "currency": "USD",
      "checkout_url": "https://mirrapaysolution.com/pay/abc123",
      "gross_amount": 42100,
      "fee_amount": 3789,
      "additional_fee_amount": 0,
      "net_amount": 38311,
      "payment_status": "succeeded",
      "settlement_status": "pending",
      "fee_bps": 900,
      "created_at": "2026-09-06T10:12:04.881Z",
      "updated_at": "2026-09-06T10:13:22.104Z",
      "succeeded_at": "2026-09-06T10:13:22.104Z",
      "livemode": true
    }
  ],
  "has_more": false,
  "request_id": "8f2a…"
}

curl "https://mirrapaysolution.com/api/public/v1/payments/MR-10241" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "id": "MR-0440EAF284",
    "reference": "order-8891",
    "status": "succeeded",
    "amount_minor": 42100,
    "description": "Advanced course",
    "currency": "USD",
    "checkout_url": "https://mirrapaysolution.com/pay/abc123",
    "payment_id": "3f1c…",
    "gross_amount": 42100,
    "fee_amount": 3789,
    "additional_fee_amount": 0,
    "net_amount": 38311,
    "payment_status": "succeeded",
    "settlement_status": "pending",
    "created_at": "2026-09-06T10:12:04.881Z",
    "updated_at": "2026-09-06T10:13:22.104Z",
    "succeeded_at": "2026-09-06T10:13:22.104Z",
    "livemode": true
  },
  "request_id": "8f2a…"
}

• Call the API from your server only. A secret key in browser code, a mobile app or a public repository is compromised the moment it ships.
• Keep secrets in server environment variables. Never in HTML, JavaScript bundles, analytics events or browser storage.
• Use test credentials while you build and switch to live credentials only when you are ready to take real money.
• Rotate a key by creating a new one, deploying it, then revoking the old one. Revocation takes effect immediately.
• Treat every amount as authoritative only after MIRRA reports the payment as succeeded — never after a browser redirect alone.
• Log the request_id of failed calls. It is the fastest route to a support answer.
• Send requests over HTTPS only.

Include the request_id from the failing response, the endpoint, and the time of the call. Write to support@mirrapaysolution.com.