What the SDK is, and is not

The YallaPay SDK is a small library that presents a payment sheet inside your app and tells you, reliably, whether the customer paid. It is deliberately narrow:

• It presents checkout. Card entry, Apple Pay, Google Pay and 3-D Secure all happen on a YallaPay-hosted page shown as a sheet over your screen. Card numbers never enter your app, so your app stays out of PCI scope.
• It confirms the outcome. When the sheet closes, the SDK asks the YallaPay API what happened and returns one of three results: completed, cancelled, or failed. It never trusts the browser redirect on its own.
• It survives interruptions. If the operating system kills your app while the customer is paying, the next launch can recover the payment instead of losing it.
• It does not create payments. Creating a payment needs your secret key, and a secret key inside an app is public. Your own server creates the payment session; your app only presents it.

An integration is therefore two halves: a few lines on your server, and a few lines in your app. This documentation covers both, plus the dashboard settings that make them work.

Native or Flutter?

There are three SDKs. Pick the one that matches how your app is built.

All three SDKs share one API, one vocabulary and one set of results. Everything on this page applies to all of them.

How a payment works

Three things happen, in this order:

1. Your server   POST /api/v1/sessions      →  session_id
2. Your app      YallaPay.pay(session_id)   →  customer pays in the sheet
3. Your server   webhook arrives           →  you fulfil the order

In more detail, this is what passes between your app, your server and YallaPay for one payment:

Customer taps Pay in your app
  │
  ├─► Your app asks your server to start a payment
  │     └─► Your server calls POST /api/v1/sessions with the secret key
  │           └─► YallaPay answers with a session_id (cs_live_…)
  │
  ├─► Your app calls YallaPay.pay(session_id)
  │     ├─ SDK reads the session with the publishable key
  │     ├─ SDK opens the checkout sheet
  │     ├─ Customer pays (card, Apple Pay, Google Pay, 3-D Secure)
  │     ├─ Checkout returns to your app through your return URL
  │     └─ SDK re-reads the session, then returns Completed / Canceled / Failed
  │
  └─► YallaPay signs and POSTs a webhook to your server
        └─► Your server verifies the signature and fulfils the order

Two details matter more than they look:

• The SDK result is read back from the YallaPay API, not inferred from the redirect. A Completed result means the server agrees the session is paid.
• Even so, your app is the wrong place to ship goods from. Fulfil on the webhook, on your server, where nobody can tamper with the answer.

Your two keys

Find both under Apps & Return URLs in your dashboard.

On the sandbox the same two keys are issued with pk_test_ and sk_test_ prefixes. A key only works on the host that issued it.

What you need before you start

• A YallaPay merchant account that can take payments. Your account must be approved and active. Until then, creating a session returns merchant_not_approved.
• Your two API keys. Copied from Apps & Return URLs.
• A return target registered for your app. A URL scheme such as myapp for mobile apps, or a host for websites. Sessions with an unregistered return URL are refused.
• A webhook endpoint on your server. This is where you fulfil orders. Configure it once under Webhooks.
• A sandbox account for testing. Optional but strongly recommended. Sandbox is a separate deployment with its own signup, keys and test cards.

Each of these is explained step by step on the Dashboard setup page.

The 15-minute path

The shortest route from nothing to a completed test payment.

1. Register a return target Dashboard → Apps & Return URLs → Add return target. Platform: your app. Scheme: myapp. Copy the publishable and secret keys while you are there.
2. Create a session from your server

   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"
     }'

   The response carries a session_id. Send it to your app.
3. Install the SDK and pay Add the dependency, declare the myapp scheme, call configure once with the publishable key, then:

   // Android
   when (val result = YallaPay.pay(activity, sessionId)) {
       is PaymentResult.Completed -> order.markPaid(result.transactionId)
       is PaymentResult.Canceled  -> showCancelled()
       is PaymentResult.Failed    -> showError(result.error.message)
   }

   The iOS and Flutter calls are the same shape.
4. Handle the webhook Verify the X-YallaPay-Signature header, then mark the order paid. Your server is the source of truth.
5. Recover interrupted payments On every app launch, check PendingSessionStore and call sessionStatus for anything left there. Two lines, and the one step most integrations forget.

Every SDK returns the same three outcomes:

The security model

It helps to know why the pieces are shaped the way they are.

Where everything is