Dashboard setup
Everything the SDK needs from your YallaPay account, in the order you will need it. Ten minutes in the dashboard now saves a day of confusing errors later.
On this page
Checklist
When all five are done, the rest of the documentation just works.
- Account status shows Approved on your dashboard.
- Publishable and secret keys copied from Apps & Return URLs.
- A return target registered for each app (Android, iOS) and each website that will receive customers back.
- A webhook URL saved under Webhooks and confirmed with the Send test button.
- A separate sandbox account, with the same three steps repeated there.
1. Get your account approved
A merchant account can create sessions only once it has been verified. Complete KYC under Settings and wait for approval. Your dashboard shows one of these states:
| Incomplete | KYC has not been submitted. Sessions cannot be created. |
| Submitted | KYC is being reviewed by YallaPay. |
| Under Review | Approved by YallaPay and awaiting final activation by the payment provider. Usually short. Sessions are refused until it completes. |
| Approved | You can take payments. Everything below applies. |
| Rejected | Something in the submission could not be verified. The reason is shown on the dashboard; correct it and resubmit. |
Until the status is Approved, every call to create a session returns HTTP 403 with the error code merchant_not_approved and a message that names the state you are in. You can still build and test everything else on the sandbox, where approval is granted on request.
2. Copy your API keys
Open Apps & Return URLs. The two keys are at the top of the page, each with a Copy button.
| Key | Goes in | What it can do |
|---|---|---|
| pk_live_… | Your app: the configure call of the SDK. | Read the status of a session. Cannot create, cancel or refund anything. |
| sk_live_… | Your server: environment variable or secrets manager. | Create sessions, read full session details, and it is the key your webhooks are signed with. |
Both keys are 50 characters after the prefix. Sandbox keys look the same with pk_test_ and sk_test_ prefixes; a live key sent to the sandbox host is refused, and a test key sent to the live host is refused, each with a message that says which host to use instead.
Keep it in server configuration, never in source control, never in an app, never in a browser. If it is ever exposed, rotate it immediately (see below).
3. Register a return target
When the customer finishes paying, checkout sends them back to your app or website. Where it may send them is decided by a list you control. A session whose return_url does not match a registered, active target is refused with HTTP 422, so register your targets before creating sessions.
Under Apps & Return URLs choose Add return target. The form asks for:
| Platform | Android app, iOS app, or Website. Apps use a scheme, websites use a host. |
| Scheme apps | The custom URL scheme your app claims, such as myapp. Letters, digits, plus, dot and hyphen only; no ://. Payments return to myapp://yallapay/return. A scheme can belong to only one YallaPay account, so pick one unique to your brand rather than something generic. |
| Host websites | Your site, such as shop.example.com, with no scheme and no path. Subdomains of a registered host are accepted too. Return URLs for websites must be https; plain http is refused. |
| Label optional | A name for your own reference, such as "Android production". |
| App / bundle id optional | Your Android application id or iOS bundle identifier, such as com.example.shop. Recorded for your reference. |
Register one target per platform: an Android app and an iOS app can share the same scheme, but register it once for each so the list documents what is live. Targets can be disabled or removed at any time; sessions already created keep their return URL, so a customer mid-payment is never stranded.
The scheme you register here must be the one your app declares (manifest placeholder on Android, Info.plist on iOS) and the one you pass as the return URL when creating a session. If any of the three differs, the customer pays and your app never hears about it.
4. Set up your webhook endpoint
The webhook is how your server learns that a payment succeeded, independently of the customer's phone. Under Webhooks fill in:
| Store name | How this endpoint appears in your dashboard and reports. |
| Webhook URL | An https URL on your server that accepts a POST with a JSON body. It must respond quickly with any 2xx status. |
| Industry | Used for reporting. |
| Status | Active endpoints receive webhooks. Disable one to pause delivery without deleting it. |
Saving assigns the endpoint a store id. If you run several stores or apps under one account, create one endpoint per store and pass its store_id when creating a session; the webhook for that payment is then delivered to that endpoint. Without a store id, the most recently saved active endpoint receives everything.
Use Send test to receive a sample payload immediately. It is signed exactly like a real one and carries "test": true, so you can verify your signature check before any money moves.
There is no separate webhook secret to configure. The X-YallaPay-Signature header is an HMAC over the body using your secret key, which your server already has. The payload and verification steps are on the Webhooks & fulfilment page.
5. Create a sandbox account
The sandbox is a complete second YallaPay at https://sandbox.yallapay.net, with its own database, its own signup and its own keys. Nothing there is real: cards are test cards, and money never moves. Because it is separate, a query that forgets to filter test data can never put play money into a real balance.
- Sign up again on the sandbox host. Your live login does not exist there. Use the same email if you like; the accounts are unrelated.
- Ask for approval. Sandbox accounts are approved by YallaPay on request rather than through full KYC. Contact support with the email you signed up with.
- Repeat steps 2 to 4. Copy the
pk_test_andsk_test_keys, register the same return targets, and point a webhook at a test endpoint.
Test cards are listed on the sandbox dashboard under Apps & Return URLs, and on the Sandbox & go-live page.
Rotating keys
Keys can be regenerated from the dashboard. Rotating the secret key invalidates the old one immediately: sessions can no longer be created with it, and webhooks are signed with the new one from the next delivery onward. Plan a rotation as a deploy:
- Generate the new secret key and store it in your server configuration alongside the old one.
- Deploy your server so that it creates sessions with the new key and accepts webhooks signed by either key for a few minutes.
- Remove the old key from your configuration.
Rotating the publishable key requires shipping a new app release, since the old one is compiled into the binary. Old app versions keep working until the old key is retired, so retire it only once your install base has moved on.
Sharing keys with your team
- Give mobile developers only the publishable key. It is all the app needs, and it cannot be misused.
- Give backend developers the secret key through your secrets manager, never through chat or email.
- Give everyone a sandbox account of their own; sandbox keys are harmless to share.
Next: Server integration to create your first session.