Skip to main content

​
1. Get sandbox access

Your lite account manager configures your test connector and sandbox credentials from the backoffice. Ask for this first, because it is the only step you cannot complete yourself.
Then:
  1. Go to Settings > Developers and enable Test Mode.
  2. Go to API Keys and select Create API Key.
  3. Select the permissions you need. Make sure the payment permissions are enabled.
  4. Create the key and store it on your server.
Your API key is a server-side secret. Do not put it in browser code, mobile apps, or version control.

​
2. Set up routing and a channel

Routing. Go to Routing > Profiles, create a profile, add a rule pointing at your test connector, then set the profile to Active and make it the default. Channel. Go to Settings > Acceptance and add a new e-commerce channel. Configure the payment methods you want to accept and, if you are using Payment Links or Hosted Checkout, the checkout styling. If you are using the Web SDK, only the payment-method configuration is required. Copy the channel ID. You pass it as channel_id when you create a session or a payment. A payment method that is not enabled on the channel will not appear at checkout, whatever your code sends.

​
3. Create the payment

Creating a payment returns immediately with an accepted response. The payment is processed asynchronously, so the response to that call is not the outcome.

​
4. Handle authentication

Card payments may require 3D Secure. mada e-commerce payments require it. In every case the customer can abandon the challenge. Do not treat a customer who stops halfway as a decline. Resolve it at step 5.

​
5. Confirm the result on your server

You need both of these. Neither is sufficient alone. Webhooks. Configure an endpoint and subscribe to the events you need. Your endpoint must tolerate retries, duplicate deliveries, and events arriving out of order. Server-side retrieval. Retrieve the payment by its ID, by order ID, or retrieve the checkout session. Use include=instrument,operations to expand the instrument and operations in the response. You can also list payments with pagination and filters.
Do not fulfill an order based on what the browser reported. Customers close tabs, networks drop, and client-side code fails. Your server is the only place the outcome is reliable.

​
6. Manage payments after processing

​
7. Verify your business

Verification is what unlocks live payments. It is fully digital. Your details are checked against government records, so there are no documents to upload.

​
Who completes it

The person completing verification must be listed as a manager on your commercial registration and hold the authority to open bank accounts on behalf of the business. If they are not, someone who does hold that authority needs to complete it instead.

​
What you need

  • A business mobile number. Use the number on your account or add a different one. Either way it is confirmed by a one-time password, and it must be registered to the national ID of the person completing verification.
  • Your commercial registration number. Ten digits, starting with 7. It must be active and must not already be registered with lite.
  • The authorized person’s national ID. Ten digits, starting with 1 or 2. The first digit sets whether dates are entered as Hijri or Gregorian.
  • Nafath verification. The authorized person completes this themselves. If it fails, you can retry.
  • Business details. A contact email, your number of employees, and your annual turnover.
  • Merchant category codes. Choose at least one from the codes matching the business activities on your commercial registration.
  • Ownership details. If your ownership is already recorded with the Ministry of Commerce, you will not be asked for it. Otherwise you enter each owner’s name, national ID or Iqama, date of birth, and ownership percentage. Total ownership cannot exceed 100 percent. Owners that are companies are entered with their own commercial registration number.
You will also be asked to confirm whether any owner is a politically exposed person. Most verifications complete without anyone contacting you. Some need a closer look, and we get in touch when that happens. If we need something we could not retrieve, you can send it with a short message and up to five attachments.

​
8. Test before you switch

Confirm your integration handles all of the following in Test Mode. Test cards has the card numbers.
  • A successful payment, end to end
  • A declined payment
  • A 3D Secure challenge completed
  • A 3D Secure challenge abandoned by the customer
  • The customer closing the page after submitting but before the result appears
  • A duplicate request
  • An incomplete or invalid request
  • A webhook received, verified, and handled twice without double-processing
  • A payment retrieved server-side after processing
  • A capture, a partial capture, a refund, and a void
Handle every error group, not only declines. API errors lists every code lite returns. Pay attention to what you show the customer: a declined card and a malformed request should not produce the same message.

​
9. Go live

Nothing carries over from Test Mode. On your side
  • Create live API keys and remove test keys from your production configuration
  • Register your live webhook endpoint and confirm it receives events
  • Confirm no API key appears in your source code or version control
  • Confirm your logs do not store card data or personal information
Verify with a real transaction
  • Run one low-value payment end to end
  • Retrieve it server-side and confirm the state matches
  • Confirm the webhook arrived at your live endpoint
  • Refund it and confirm the refund webhook arrived
  • Confirm it appears correctly in your settlement window