API reference

Getting started, in three steps

1. 01

   Get an account and a key

   From your dashboard → API keys. The key is shown once, at the moment it is issued, so keep it somewhere safe.

2. 02

   Fetch the catalogue

   Browse the denominations on offer and your own price for each, then store the SKUs of the ones you sell.

3. 03

   Place an order

   Send the SKU and the quantity with an idempotency header. Your wallet is charged and the order comes back pending until the code is issued.

curl https://mena-pin.com/v1/balance \
  -H "Authorization: Bearer mp_live_YOUR_KEY"

Authentication

Every request carries your key in the Authorization header. Keys begin with mp_live_, and every one of them spends your real balance and delivers real codes — there is no separate test environment.

Authorization: Bearer mp_live_YOUR_KEY

No double buying

Networks drop, a customer clicks twice, and jobs are retried. Send an Idempotency-Key header of your own, with a value unique to you, on every create request. Sending it again with the same value hands you back the very same first order — not a second order, not a second charge, and not a second code.

Idempotency-Key: order-invoice-84213

How amounts are represented

Every amount comes back as an object with three fields. Use minor_units in your arithmetic — a whole number of the currency's smallest unit — and show amount to the user. Never compute on the decimal value.

{
  "amount": "0.83",
  "minor_units": 83,
  "currency": "USD"
}

Rate limits

The ceiling is counted per key, and the X-RateLimit-Limit and X-RateLimit-Remaining headers come back with every response. Going over it answers 429.

The default ceiling is 60 requests a minute per key. If a higher one has been agreed for your account then that is the one that applies, and it appears in X-RateLimit-Limit on your first response.

Refunds

Refunds are fully automatic: there is no endpoint for one and no request to be made for one. An order that cannot be filled has its whole value returned to your wallet by the system itself, its status becomes refunded, the order.refunded event reaches you on your webhook if you are subscribed to it, and the movement appears in your wallet statement as a single entry with its date and the order number. So nothing stays debited for an order that was not delivered, and you are never asked to claim it.

Webhooks

Instead of you asking the API over and over for news, we send a signed POST request to an address on your own server whenever something happens on your account. The addresses are managed from the dashboard, and each of them has a signing key of its own.

The shape of the payload

id is the same across every attempt to deliver one event — store it and ignore any event you have already handled. data carries the order in exactly the shape the API returns it in.

{
  "id": "01K2H8QF3M4N5P6Q7R8S9T0V1W",
  "event": "order.delivered",
  "created_at": "2026-08-10T09:14:22+00:00",
  "data": {
    "number": "01K2H8Q...",
    "status": "delivered",
    "quantity": 1,
    "total": { "amount": "9.00", "minor_units": 900, "currency": "USD" },
    "package": { "sku": "PUBG-660", "name": "660 UC" },
    "delivered_at": "2026-08-10T09:14:22+00:00"
  }
}

A code is never sent in a notification. The notification goes to an address you chose and passes through whatever proxies and logs stand between us. A code is the goods themselves, so it is read from GET /v1/orders/{number} over a connection authenticated with your own key.

Verifying the signature

Every request carries an X-MenaPin-Signature header, shaped t=<unix>,v1=<hex>. The signed value is "{t}.{raw_body}", with HMAC-SHA256 and your endpoint's key. Verify the raw body before any parsing or reordering, and reject a timestamp older than 300 seconds.

The old prefix is still sent. The product carried a different name for a while, and during it the four fields arrived under the X-Doabletech- prefix. Both prefixes are sent together with exactly the same values — nothing changed on the wire — so whatever you wrote in either period still works as it stands. X-MenaPin- is the current one; the other is deprecated and will be removed later — move your verification across in your own time.

$payload   = file_get_contents('php://input');
$header    = $_SERVER['HTTP_X_MENAPIN_SIGNATURE'] ?? '';
$secret    = getenv('WEBHOOK_SECRET');

parse_str(strtr($header, ',', '&'), $parts);
$timestamp = (int) ($parts['t'] ?? 0);
$expected  = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (! hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(400);   // bad signature
    exit;
}

if (abs(time() - $timestamp) > 300) {
    http_response_code(400);   // too old
    exit;
}

$event = json_decode($payload, true);
// handle $event['id'] exactly once, then:
http_response_code(200);

Answering, and retries

• Answer 2xx the moment it reaches you, and defer any long processing. Our timeout is 10 seconds.
• On failure we retry up to 5 times, 10 seconds, 1 minute, 5 minutes, 30 minutes apart.
• A 4xx answer means a deliberate refusal, so we do not repeat it — except for 408 and 429.
• After 15 consecutive failures the endpoint is switched off and we send you an alert. Missed events are not replayed automatically once it is switched back on.
• The address must be https and on a public network — we do not send to an internal address.

Errors

Every error comes back in the same shape, with a stable code in code that your program can branch on, and an Arabic message fit to be shown.

{
  "error": {
    "code": "insufficient_balance",
    "message": "الرصيد لا يكفي لإتمام هذه العملية."
  }
}

Alongside those, 400 bad_request can come back for a body that is structurally invalid, and 405 method_not_allowed for a method the path does not accept. Both are mistakes in how the request was built rather than anything about the state of your account.

Nothing stays debited for an order that was not delivered. The debit happens together with the creation of the order, in one operation under a lock, and if the order cannot be filled its whole value is returned to your wallet and the return is written into the statement as a single movement.