Hosts and authentication

Every request is authenticated with a bearer token in the Authorization header. Keys are never read from the query string.

Authorization: Bearer sk_live_YOUR_SECRET_KEY

A secret key is accepted everywhere. A publishable key is accepted only on the read endpoint, and it sees a reduced view of the session. A key of the wrong environment is refused with a message naming the correct host.

Create a session

Call this from your server when the customer starts a payment. Send the amount and currency, a short description the customer will see, and your own order id so you can match the payment later.

curl -X POST "https://yallapay.net/api/v1/sessions" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-881-attempt-1" \
  -d '{
    "amount": 250.00,
    "currency": "AED",
    "purpose": "Order #881",
    "external_id": "881",
    "return_url": "myapp://yallapay/return"
  }'

<?php
$response = Http::withToken(env('YALLAPAY_SECRET_KEY'))
    ->withHeaders(['Idempotency-Key' => "order-{$order->id}-attempt-{$attempt}"])
    ->post('https://yallapay.net/api/v1/sessions', [
        'amount'      => 250.00,
        'currency'    => 'AED',
        'purpose'     => "Order #{$order->id}",
        'external_id' => (string) $order->id,
        'return_url'  => 'myapp://yallapay/return',
    ]);

if ($response->failed()) {
    $error = $response->json('error');   // ['code' => ..., 'message' => ..., 'param' => ...]
    throw new RuntimeException($error['message']);
}

$sessionId = $response->json('session_id');   // send this to the app

const res = await fetch('https://yallapay.net/api/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.YALLAPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${order.id}-attempt-${attempt}`,
  },
  body: JSON.stringify({
    amount: 250.0,
    currency: 'AED',
    purpose: `Order #${order.id}`,
    external_id: String(order.id),
    return_url: 'myapp://yallapay/return',
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);

const sessionId = body.session_id;   // send this to the app

import os, requests

res = requests.post(
    "https://yallapay.net/api/v1/sessions",
    headers={
        "Authorization": f"Bearer {os.environ['YALLAPAY_SECRET_KEY']}",
        "Idempotency-Key": f"order-{order.id}-attempt-{attempt}",
    },
    json={
        "amount": 250.00,
        "currency": "AED",
        "purpose": f"Order #{order.id}",
        "external_id": str(order.id),
        "return_url": "myapp://yallapay/return",
    },
    timeout=10,
)

body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

session_id = body["session_id"]   # send this to the app

A successful call returns HTTP 201 and the full session object:

{
  "session_id":     "cs_live_9fK3rM2pQ7xTb4Lw8nHv1sZc6Yd0JeAq",
  "status":         "open",
  "amount":         250,
  "currency":       "AED",
  "transaction_id": null,
  "payment_method": null,
  "checkout_url":   "https://yallapay.net/c/cs_live_9fK3rM2pQ7xTb4Lw8nHv1sZc6Yd0JeAq",
  "expires_at":     "2026-08-27T14:20:00+04:00",
  "external_id":    "881",
  "purpose":        "Order #881",
  "fee_payer":      "merchant",
  "return_url":     "myapp://yallapay/return",
  "net_amount":     null,
  "created_at":     "2026-08-27T13:20:00+04:00"
}

Send session_id to your app and store it against the order. The checkout_url is what the SDK opens; a website can open it directly.

Request fields

The session object

The same object comes back from both endpoints. With the secret key you see all of it; with the publishable key, only the first eight fields. The publishable view deliberately excludes merchant details, net amounts, fee splits and customer records, because it is read by code running on a customer's device.

Session lifecycle

              ┌──────────── customer pays ────────────► paid   (final)
              │
open ─────────┼──────────── payment declined ────────► failed (customer may retry while open)
              │
              └──────────── expires_at passes ──────────► expired (final)

• open — created and payable. The checkout URL works and the SDK can present it.
• paid — money moved. This is final: no later failure or expiry can downgrade it, and re-opening the checkout URL shows the receipt instead of the form.
• failed — the most recent attempt was declined. The session is still payable until it expires, so the customer can try another card.
• expired — the expiry passed with no successful payment. Create a new session for a new attempt.

One session is one payment of one amount. Do not reuse a session across orders, and do not change the order's total after creating it; create a new session instead.

Idempotency

Mobile networks retry. If your app's request to your server times out on the way back and the app tries again, you would create a second session for the same order unless something stops you. The Idempotency-Key header is that something.

• Send a key that is unique per attempt, such as order-881-attempt-1. Any string up to 255 characters.
• Repeating a request with the same key and the same body returns the original response, with the same status code and an extra header Idempotent-Replayed: true.
• Repeating a key with a different body is refused with HTTP 409 idempotency_conflict, because the two requests cannot both be honoured.
• Keys are remembered for 24 hours, per account and per endpoint. Only successful responses are stored, so a transient error does not pin itself to the key.

Read a session

Returns the session object. With the secret key, the full view; with the publishable key, the public view. The SDKs call this endpoint with the publishable key to decide the result they return to your app, and you can call it from your server to reconcile an order whose webhook you have not seen.

curl "https://yallapay.net/api/v1/sessions/cs_live_9fK3rM2pQ7xTb4Lw8nHv1sZc6Yd0JeAq" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

$session = Http::withToken(env('YALLAPAY_SECRET_KEY'))
    ->get("https://yallapay.net/api/v1/sessions/{$sessionId}")
    ->throw()
    ->json();

if ($session['status'] === 'paid') {
    $order->markPaid($session['transaction_id']);
}

const res = await fetch(`https://yallapay.net/api/v1/sessions/${sessionId}`, {
  headers: { Authorization: `Bearer ${process.env.YALLAPAY_SECRET_KEY}` },
});
const session = await res.json();

if (session.status === 'paid') await orders.markPaid(session.transaction_id);

session = requests.get(
    f"https://yallapay.net/api/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {os.environ['YALLAPAY_SECRET_KEY']}"},
    timeout=10,
).json()

if session["status"] == "paid":
    orders.mark_paid(session["transaction_id"])

Errors

Every error has the same shape. The param field is present only for validation errors, and names the offending field.

{
  "error": {
    "code":    "validation_error",
    "message": "The app scheme \"shop://\" is not registered for this account. Add it under Settings → Apps & return URLs.",
    "param":   "return_url"
  }
}

Rate limits

• Create a session: 60 requests per minute.
• Read a session: 120 requests per minute.

Both are generous for a checkout flow. If you poll a session from your server, poll at most every few seconds and stop once the status is final; better still, rely on the webhook and poll only as a fallback.

Recommended pattern

This is the shape of a server that works well with the SDKs. Each numbered piece is a small endpoint or job in your own codebase.

1. POST /orders/{id}/pay Authenticated by your own app login. Looks up the order, creates a YallaPay session with the order total, stores the session_id on the order, and returns it to the app. Uses order-{id}-attempt-{n} as the Idempotency-Key.
2. POST /webhooks/yallapay Verifies X-YallaPay-Signature, finds the order by external_id, and marks it paid if not already. Responds 200 quickly and does slow work (email, shipping) in a queue. See Webhooks & fulfilment.
3. GET /orders/{id} What the app polls after the SDK returns, to show the order as paid once your server has processed the webhook. If the webhook is late, this handler may read the session from YallaPay with the secret key and reconcile on the spot.
4. A reconciliation job Every few minutes, for orders that have a session but are not yet paid or expired, read the session and update the order. This catches the rare webhook that never arrived.

Next: the app side, for Android, iOS or Flutter.