Embedded Payment

Show KNET, card and Apple Pay directly on your own checkout page, so your customer never leaves your site.

With Embedded Payment, the payment options appear inside your own checkout page. Your customer stays on your site to pay with KNET, card or Apple Pay, and SADAD Pay creates and processes the invoice in the background.

Embedded Payment needs a little more work than the Hosted Payment Page. Choose it when you want full control over the look of your checkout.

1. Register domain
One time · allow_domain
→
2. Create session
Each order · intiate_order_session
→
3. Show widget
KNET, card or Apple Pay script
→
4. Get the result
Redirect or callback
→
5. Verify payment
status = Paid

📘

Before you start

What your customer sees

Each payment method is a small widget that you place on your page. You choose which ones to show.

KNETCredit / debit card
A KNET button. When the customer clicks it, they go to the KNET page to enter their card and PIN, then come back to your site.A card form (name, card number, expiry, security code) shown inside your page. The customer pays without leaving.
1568

The KNET button on a sample checkout page

1568

The card form on a sample checkout page

Step 1: Register your domain

Before the widgets can load, register every domain that will show them. You only do this once per domain.

Send the domain to POST /api/EmbeddedPayment/allow_domain · API Reference

FieldTypeRequiredDescriptionExample
domainstringYesYour website domain, without https:// or a path. Register www.yourstore.com and yourstore.com separately if you use both."yourstore.com"
curl -X POST "https://apisandbox.sadadpay.net/api/EmbeddedPayment/allow_domain" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourstore.com" }'
{
  "isValid": true,
  "errorKey": null,
  "response": {
    "result": true
  }
}
{
  "isValid": false,
  "errorKey": "DomainAlreadyExist",
  "response": null
}

📘

Register in both environments

Sandbox and Live are separate. Register your domain in Sandbox for testing, and again in Live before you go live.

Step 2: Create a checkout session

For every order, create a checkout session before you show the widget. The session holds the order details, and SADAD Pay uses it to create the invoice when the customer pays.

Send the order to POST /api/EmbeddedPayment/intiate_order_session · API Reference

🚧

One session per payment method

A session is created for one payment method. If you show both KNET and card on the same page, create two sessions: one with Knet and one with CCCSSA.

Request fields

FieldTypeRequiredDescriptionExample
paymentGatewayCodestringYesThe payment method for this session. See the table below."Knet"
ref_NumberstringYesYour own order or reference number. Use it to match the invoice to your order."ORD-1001"
amountnumberYesThe order amount in the currency set in currency_Code. Must be greater than 0. If you send items, it must equal the total of the items.1.500
currency_CodestringYesKWD, USD, SAR, AED or QAR."KWD"
customer_NamestringYesThe customer's name."Ahmed Ali"
customer_MobilestringRecommendedThe customer's mobile number."99999999"
customer_EmailstringRecommendedThe customer's email address."[email protected]"
langstringNoen or ar."en"
itemsarrayNoLine items, each with name, quantity and amount (price of one unit).See example

Payment method codes

paymentGatewayCodePayment methodWidget
KnetKNETKNET button
CCCSSAVisa and MastercardCard form
ApplePayApple PayApple Pay button

📘

Card gateway code

CCCSSA is the standard card code. If the session returns PaymentMethodRequired or the card widget does not work, contact [email protected] to confirm the card code for your account.

Examples

curl -X POST "https://apisandbox.sadadpay.net/api/EmbeddedPayment/intiate_order_session" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentGatewayCode": "Knet",
    "ref_Number": "ORD-1001",
    "amount": 1.500,
    "currency_Code": "KWD",
    "customer_Name": "Ahmed Ali",
    "customer_Mobile": "99999999",
    "customer_Email": "[email protected]",
    "lang": "en"
  }'
curl -X POST "https://apisandbox.sadadpay.net/api/EmbeddedPayment/intiate_order_session" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentGatewayCode": "CCCSSA",
    "ref_Number": "ORD-1002",
    "amount": 5.000,
    "currency_Code": "KWD",
    "customer_Name": "Ahmed Ali",
    "customer_Email": "[email protected]",
    "items": [
      { "name": "Blue T-shirt", "quantity": 2, "amount": 1.500 },
      { "name": "Cap", "quantity": 1, "amount": 2.000 }
    ]
  }'

Response

{
  "isValid": true,
  "errorKey": null,
  "response": {
    "session_Id": "11782RHMLZ1hZoc4qUjr60XNl5cAi3nqVky0KqPM8xudAnugbLnxyML"
  }
}
{
  "isValid": false,
  "errorKey": "ReferenceNumberRequired",
  "response": null
}

Pass the session_Id to your checkout page. Create a new session for every payment attempt.

❗️

Keep your Access Token on your server

Create the session from your server, never from JavaScript in the browser. Only the session_Id should reach the customer's browser.

Step 3: Show the payment widget

Add the widget to your checkout page. Each payment method has:

  1. A placeholder div where the widget appears.
  2. The SADAD Pay script for that method.
  3. A short configuration script that passes the session_Id.

🚧

Use global variables

Declare session_id and options with var at the top level of the script, exactly as in the examples. The widget reads them as global variables, so it will not load if you declare them with let or const or inside a function.

📘

Sandbox or Live

The last parameter of Sadad.Configure selects the environment: true for Sandbox, false for Live. The script URLs are the same for both.

<p>Pay using:</p>
<div id="sadad-knet-element"></div>

<script src="https://sadadpay.net/embedded/knet/knet-process.min.js"></script>
<script>
  var session_id = "SESSION_ID_FROM_STEP_2";
  var options = {
    "buttonVisible": true,   // show the KNET button
    "buttonWidth": "80px",   // KNET button width
    "successURL": "https://yourstore.com/payment/success",
    "failedURL": "https://yourstore.com/payment/failed"
  };

  Sadad.Configure(session_id, options, true); // true = Sandbox, false = Live

  // Optional: send the customer to KNET straight away, without showing the button
  // Sadad.ProcessSession();

  // Called if the payment cannot be started
  var SadadOnError = function (error) {
    console.log(error);
  };
</script>
<p>Pay using:</p>
<div id="sadad-card-element"></div>

<script src="https://sadadpay.net/embedded/card/card-process.min.js"></script>
<script>
  var session_id = "SESSION_ID_FROM_STEP_2";
  var options = {
    "lang": "en",                        // en or ar
    "backgroundColor": "#ffffff",
    "fontFamily": "'Poppins', sans-serif",
    "fontSize": "13px",
    "fontColor": "#707070",
    "buttonBackgroudColor": "#2563eb",   // spelled "Backgroud" in the SDK
    "buttonFontColor": "#ffffff",
    "textBoxFontColor": "#333333",
    "textBoxBackgroundColor": "#ffffff",
    "textBoxBorderColor": "#cccccc"
  };

  Sadad.Configure(session_id, options, true); // true = Sandbox, false = Live

  // Called when the payment succeeds
  var SadadOnSuccess = function (result) {
    // Send result.invoice_id to your server and verify it (Step 5)
    console.log(result);
  };

  // Called when the payment fails
  var SadadOnError = function (error) {
    console.log(error);
  };
</script>
<div id="sadad-applepay-element" class="apple-pay-button apple-pay-button-text-buy" lang="en"></div>

<!-- Shown when Apple Pay is not available on the device or browser -->
<p style="display:none" id="sadad-applepay-error">Apple Pay is not available on this device.</p>

<script src="https://sadadpay.net/embedded/applepay/applepay-process.js"></script>
<script>
  var session_id = "SESSION_ID_FROM_STEP_2";
  var vendor_id = "YOUR_VENDOR_ID";
  var options = {
    "CompanyName": "Your Store",  // name shown on the Apple Pay sheet
    "Amount": 1.500,              // same amount as the session
    "buttonWidth": "80px"
  };

  Sadad.Configure(vendor_id, session_id, options, true); // true = Sandbox, false = Live

  var SadadSuccess = function () {
    console.log("payment completed");
  };

  var SadadOnError = function (error) {
    console.log(error);
  };
</script>

Card form style options

All style options are optional. Leave out any you do not need.

OptionWhat it changes
langForm language: en or ar
backgroundColorForm background
fontFamily, fontSize, fontColorLabel text
buttonBackgroudColor, buttonFontColorPay button
textBoxFontColor, textBoxBackgroundColor, textBoxBorderColorInput boxes

Apple Pay requirements

🚧

Apple Pay needs extra setup

  • Your domain must be registered and verified with Apple before you start. This is done through an Apple Developer account: create an Apple Pay Merchant ID, upload Apple's domain verification file to your website, then verify the domain in your Apple Developer account.
  • The Apple Pay button only appears on devices and browsers that support Apple Pay, such as Safari on an iPhone, iPad or Mac with Apple Pay set up. Elsewhere, the sadad-applepay-error message is shown instead.
  • vendor_id is your SADAD Pay vendor ID. Contact [email protected] if you do not know it.

Step 4: Get the payment result

How you receive the result depends on the payment method.

KNET: redirect to your URL

After the customer pays on the KNET page, SADAD Pay sends them back to the successURL or failedURL you set in options. The invoice ID is added as the invoice_id parameter.

https://yourstore.com/payment/success?invoice_id=71461

Read invoice_id on your server and continue to Step 5.

Card: JavaScript callback

The customer stays on your page. When the payment succeeds, the widget calls your SadadOnSuccess function. Read result.invoice_id, send it to your server, and continue to Step 5. If the payment fails, SadadOnError is called instead.

Apple Pay: JavaScript callback

When the payment completes, the widget calls your SadadSuccess function. If it fails, SadadOnError is called. This callback does not return an invoice ID, so use the webhook to learn which invoice was paid, then continue to Step 5.

📘

The invoice is created when the customer pays

SADAD Pay creates the invoice from the session at payment time. It is a normal invoice: you can see it in the portal under Invoices, and it carries your ref_Number and items.

🚧

The result on the page is not proof of payment

The redirect URL and the JavaScript callback both run in the customer's browser, so they can be changed. Always continue to Step 5 and verify the payment from your server.

Step 5: Verify the payment

From your server, call GET /api/Invoice/getbyid?id={invoice_id} and check the status field before you complete the order. This is the same check as in the Hosted Payment Page.

StatusMeaningWhat to do
PaidPaid successfullyComplete the order
UnpaidNot paid, or the payment failedDo not complete the order
CanceledThe invoice was cancelledDo not complete the order
RefundedThe payment was refundedCancel or reverse the order

Also check that ref_Number and amount match your order.

❗️

Never skip verification

SADAD Pay is not responsible for orders completed without verifying that the invoice status is Paid.

👍

Use webhooks too

If the customer closes the browser before the result reaches your page, the webhook still tells your server that the invoice was paid. See Webhooks.

Test your integration

  1. Register your test domain in Sandbox (Step 1).
  2. Create a session with "paymentGatewayCode": "Knet" (Step 2).
  3. Load your page with Sadad.Configure(session_id, options, true).
  4. Pay with the KNET test card from Test Cards.
  5. Check that your server verifies the invoice as Paid (Step 5).

Repeat with CCCSSA and a test card to check the card form.

Common errors

All errors are returned with HTTP 200 and "isValid": false. Always check isValid.

errorKeyEndpointCauseHow to fix
InvalidDomainNameallow_domainThe domain is not validSend only the domain, such as yourstore.com, without https:// or a path
DomainAlreadyExistallow_domainThe domain is already registeredNothing to do. You can use it.
ReferenceNumberRequiredintiate_order_sessionref_Number is missingSend your order reference
PaymentMethodRequiredintiate_order_sessionpaymentGatewayCode is missingSend Knet, CCCSSA or ApplePay
AmountRequiredintiate_order_sessionamount is missing or 0Send an amount greater than 0
CustomerNameRequiredintiate_order_sessioncustomer_Name is missingSend the customer's name
InvalidCurrencyCodeintiate_order_sessioncurrency_Code is missing or not supportedSend KWD, USD, SAR, AED or QAR
InvoiceAmountMustEqualsToTotalItemsAmountintiate_order_sessionamount does not equal the total of the itemsMake amount equal the sum of quantity × amount
UnauthorizedAccess (HTTP 401)AllThe Access Token is missing, wrong or expiredGenerate a new Access Token

Widget does not appear? Check that:

  • The domain of the page is registered (Step 1) in the same environment.
  • session_id and options are declared with var at the top level.
  • The last parameter of Sadad.Configure matches the environment (true for Sandbox).
  • The session was created for the same payment method as the widget.

Next steps