How to read SADAD Pay API responses, and how to fix every error.
Every SADAD Pay API response has the same shape. This page explains how to read it, what each HTTP status code means, and how to fix each errorKey.
The response format
{
"isValid": true,
"errorKey": null,
"response": {
"invoiceId": "92968"
}
}
{
"isValid": false,
"errorKey": "CustomerNameRequired",
"response": null
}
| Field | Description |
|---|---|
isValid | true if the request worked, false if it did not |
errorKey | null on success. On failure, a code that says what went wrong, such as CustomerNameRequired. |
response | The result on success. Usually null on failure. |
Check
isValid, not only the HTTP statusMost validation errors come back with HTTP
200and"isValid": false. Always checkisValidanderrorKeyin the body, even when the HTTP status is200.
const body = await res.json();
if (!res.ok || !body.isValid) {
throw new Error(`SADAD Pay error: ${res.status} ${body.errorKey}`);
}
$body = json_decode($response, true);
if ($httpCode !== 200 || empty($body['isValid'])) {
throw new Exception('SADAD Pay error: ' . $httpCode . ' ' . ($body['errorKey'] ?? ''));
}
HTTP status codes
| Status | Meaning | What to do |
|---|---|---|
200 | The request reached SADAD Pay. Check isValid to see if it worked. | If isValid is false, fix the request using the errorKey |
400 | The request body is not valid JSON, or a field has the wrong type | Check the JSON and the field types. The body says which field is wrong. |
401 | The token is missing, wrong or expired | Generate a new Access Token. See API Keys & Authentication. |
403 | You are not allowed to do this, for example the invoice belongs to another account or environment | Check that you use the right keys for this environment, and the right ID |
404 | The URL is wrong | Check the endpoint path and the base URL |
500 | An error on the SADAD Pay side | Try again later. If it keeps happening, contact [email protected] with the request and the time. |
Error keys
Authentication
| errorKey | Cause | How to fix |
|---|---|---|
InvalidToken (401) | The Access Token has expired | Generate a new Access Token with your refresh token |
InvalidAccessToken (401) | The Access Token is missing or wrong | Send Authorization: Bearer {accessToken} |
UnauthorizedAccess (401) | The Authorization header is missing or wrong | Check the header format and the token |
UnauthorizedAccess (403) | The record does not exist or belongs to another account, or the feature is not enabled for you | Check the ID, the environment, and the keys you use |
Invoices
POST /api/Invoice/insert, PUT /api/Invoice/update, DELETE /api/Invoice/delete. See Hosted Payment Page.
| errorKey | Cause | How to fix |
|---|---|---|
AmountRequired | amount is missing or 0 | Send an amount greater than 0 |
CustomerNameRequired | customer_Name is missing | Send the customer's name |
InvalidCurrencyCode | currency_Code is missing or not supported | Send a supported currency code, such as KWD |
InvoiceAmountMustEqualsToTotalItemsAmount | amount is not the total of the items | Send amount = sum of quantity × amount |
InvoiceCannotBeUpdated | The invoice is already paid | Create a new invoice instead |
InvoiceCannotBeDeleted | The invoice is already paid | Refund it instead. See Refunds. |
Embedded Payment
POST /api/EmbeddedPayment/allow_domain and intiate_order_session. See Embedded Payment.
| errorKey | Cause | How to fix |
|---|---|---|
InvalidDomainName | The domain is not valid | Send the domain only, without https:// or a path |
DomainAlreadyExist | The domain is already registered | Nothing to do |
PaymentMethodRequired | paymentGatewayCode is missing | Send Knet, CCCSSA or ApplePay |
ReferenceNumberRequired | ref_Number is missing | Send your order number |
AmountRequired, CustomerNameRequired, InvalidCurrencyCode, InvoiceAmountMustEqualsToTotalItemsAmount | As for invoices | As for invoices |
Payment links and product links
See Invoicing & Payment Links and Product Links.
| errorKey | Endpoint | Cause | How to fix |
|---|---|---|---|
InvalidKey | createpaymentlinkinvoice | The payment link key does not exist | Check paymentLink_Key |
CustomerMobileRequired | createpaymentlinkinvoice | Returned when the key is wrong and no mobile number is sent | Check paymentLink_Key first |
InvalidAmount | createpaymentlinkinvoice | The amount does not match a fixed link, or is outside a variable link's range | Send an amount the link allows |
NameEnRequired / NameArRequired | Product/insert | The English or Arabic name is missing | Send both name_En and name_Ar |
PriceRequired | Product/insert | price is missing or 0 | Send a price greater than 0 |
CustomerMobileRequired | createproductlinkinvoice | customer_Mobile is missing | Send the customer's mobile number |
InvalidProductAmount | createproductlinkinvoice | An item's amount is not the product's price | Send each product's current price |
YouExceededAvailableQuantity | createproductlinkinvoice | The quantity is more than the stock left | Lower the quantity, or add stock |
InvoiceAmountMustEqualsToTotalItemsAmount | createproductlinkinvoice | totalAmount is not the sum of the items | Send the correct total |
Installments and subscriptions
See Installments and Subscriptions.
| errorKey | Endpoint | Cause | How to fix |
|---|---|---|---|
VendorIdRequired | InstallmentPlan/insert | vendor_Id is missing | Send your vendor ID |
TotalAmountRequired | InstallmentPlan/insert | total_Amount is missing or 0 | Send the total |
InstallmentScheduleRequired | InstallmentPlan/insert | schedules is missing | Send the full schedule |
InvalidInstallmentScheduleNumber | InstallmentPlan/insert | The number of Schedule items is not installment_Count | Send one item per payment |
CustomerEmailRequired | createinstallmentplanlinkinvoice | customer_Email is missing | Send the customer's email |
AmountCannotBeGreaterThanDueAmount | createinstallmentplanlinkinvoice | totalAmount is more than the amount due | Pay no more than the amount due |
InvalidKey | createSubscriptioninvoice | The key is a subscription link key, not a customer subscription key | Use the key from /subscription/payment/{key} |
Refunds
See Refunds.
| errorKey | Cause | How to fix |
|---|---|---|
InvalidRefundAmount | The amount is 0, or more than what is left to refund | Refund no more than amount - refunded_Amount |
null, with "refund_Id": 0 and "isValid": false | The invoice is not paid, or refund_Type is not valid | Refund only paid invoices, with DeductFromBalance or PayAmount |
Multi-supplier
| errorKey | Cause | How to fix |
|---|---|---|
SuppliersItemsRequired | An item has no supplierId | Send a supplierId with every item |
SupplierNotExistForThisVendor | A supplierId is not one of your Approved suppliers | Check the ID in Suppliers |
UnauthorizedAccess (403) | Supplier refunds are not enabled for your account | Email [email protected] |
Getting help
If you cannot fix an error, email [email protected] with:
- The endpoint and the environment (Sandbox or Live)
- The request body, without your keys or tokens
- The full response, including the HTTP status
- The date and time of the request

