Introduction #

Al-Saqi Payment Gateway

Integrate Pay by Link: authenticate from your server, create a hosted payment link, and verify the payment status before fulfilling the customer’s order.

Quick Start Authentication

The Al-Saqi Payment Gateway RESTful API uses JSON requests and responses. This guide covers Pay by Link: your application directs the customer to the Al-Saqi hosted page to enter card details, while your server creates the link and verifies the result. Keep credentials and access tokens on your server, and do not use the browser redirect alone as proof of payment.

How Integration Works #

A Pay by Link integration follows four steps.

The flow at a glance #

Create Token  ──▶  Generate Payment Link  ──▶  Cardholder pays (hosted page)  ──▶  Check Payment Status
   (auth)              (returns paymentLink)            (success / fail URL)              (final result)

API Environments #

Development and testing run on the sandbox. When moving to production, only the base URL and credentials change; endpoint paths and request formats are the same in both environments.

Test card

Authentication & Security #

Token-protected endpoints require a Bearer access token obtained from the Create Access Token endpoint. Send it in the Authorization header on every protected request:

Authorization: Bearer ACCESS_TOKEN_STRING

Security best practices #

• Send all requests over HTTPS.
• Keep the username, password and access token on the merchant's server only.
• The access token is valid for 24 hours by default; request a new one before it expires.
• Use a new RequestId for every payment.

API Overview #

The Pay By Link model generates a secure hosted payment link. The cardholder enters their card data on the Al-Saqi hosted page, keeping you out of PCI scope.

Create Access Token #

Creates a JWT access token for the client and returns its clientId. The token must be sent as a Bearer header on protected endpoints.

Request Body

curl -X POST https://pg-t2.alsaqi.net/api/Auth/CreateAccessToken \
  -H "Content-Type: application/json" \
  -d '{
    "UserName": "client_username",
    "Password": "client_password",
    "ExpireDuration": 1440
  }'

const res = await fetch("https://pg-t2.alsaqi.net/api/Auth/CreateAccessToken", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    UserName: "client_username",
    Password: "client_password",
    ExpireDuration: 1440
  })
});
const data = await res.json();
// store data.access_token and data.clientId
console.log(data.access_token, data.clientId);

import requests

res = requests.post(
    "https://pg-t2.alsaqi.net/api/Auth/CreateAccessToken",
    json={
        "UserName": "client_username",
        "Password": "client_password",
        "ExpireDuration": 1440,
    },
)
data = res.json()
print(data["access_token"], data["clientId"])

{
  "access_token": "ACCESS_TOKEN_STRING",
  "clientId": 29
}

Generate Payment Link #

Generates a hosted payment link for the client. Requires a Bearer token; the {client_id} must match the clientId embedded in the token.

URL Parameters

Request Body

curl -X POST https://pg-t2.alsaqi.net/api/Payment/generate-payment-link/1024 \
  -H "Authorization: Bearer ACCESS_TOKEN_STRING" \
  -H "Content-Type: application/json" \
  -d '{
    "RequestId": "REQ-987654321",
    "InvoiceId": "INV-00021",
    "amount": 25000,
    "Currency": "IQD",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail",
    "linkExpireMinutes": 60
  }'

const res = await fetch(
  `https://pg-t2.alsaqi.net/api/Payment/generate-payment-link/${clientId}`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      RequestId: "REQ-987654321",
      InvoiceId: "INV-00021",
      amount: 25000,
      Currency: "IQD",
      successUrl: "https://example.com/success",
      failUrl: "https://example.com/fail",
      linkExpireMinutes: 60
    })
  }
);
const { paymentLink } = await res.json();
// redirect the customer to paymentLink

import requests

res = requests.post(
    f"https://pg-t2.alsaqi.net/api/Payment/generate-payment-link/{client_id}",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "RequestId": "REQ-987654321",
        "InvoiceId": "INV-00021",
        "amount": 25000,
        "Currency": "IQD",
        "successUrl": "https://example.com/success",
        "failUrl": "https://example.com/fail",
        "linkExpireMinutes": 60,
    },
)
print(res.json()["paymentLink"])

{
  "status": true,
  "paymentId": "e6e6fdd0-15a3-4782-9d0d-d1996cda99fe",
  "requestId": "REQ-987654321",
  "invoiceId": "INV-00021",
  "expiry": "2026-06-05T12:51:52.77+03:00",
  "amount": 25000,
  "stanID": "672691",
  "paymentLink": "https://pg-t.alsaqi.net/e6e6fdd0-15a3-4782-9d0d-d1996cda99fe"
}

Check Payment Status #

Returns the current status of a payment. Requires a Bearer token. You may query by paymentId, RequestId, or InvoiceId.

The second endpoint, CheckPaymentStatusByRequestId, is meant for lookups by RequestId and returns the same response.

{ "PaymentId": "4e8185b2-8134-4bc7-aca4-59ee87a45910" }

{ "RequestId": "REQ-987654321" }

{ "InvoiceId": "INV-00021" }

Response Fields

Example Responses #

{
  "status": true,
  "linkStatus": 2,
  "message": "Approved",
  "paymentId": "170acac1-3eb9-498c-8623-845139eb204a",
  "requestId": "ZO-1780503160412-1020",
  "rrn": "000030614276",
  "cardMasked": "403208******2567",
  "cardHolderName": "GDGBDHFHFN",
  "expiry": "2026-06-17T16:32:40.49",
  "paidDate": "2026-06-03T19:12:52.863",
  "createDate": "2026-06-03T19:12:40.49",
  "totalAmount": 1,
  "respCode": null,
  "errorMessage": null
}

{
  "status": false,
  "linkStatus": 4,
  "message": "Declined",
  "paymentId": "fee05441-0c8c-414a-a756-b532629cb9d3",
  "requestId": "ZO-1779611550221-821",
  "invoiceId": "test-0000350",
  "rrn": "000030617015",
  "cardMasked": "403208******2567",
  "cardHolderName": "AHMED ALI",
  "expiry": "2026-06-07T08:52:30.257",
  "paidDate": "2026-05-24T11:35:11.933",
  "createDate": "2026-05-24T11:32:30.257",
  "totalAmount": 1,
  "respCode": "AB",
  "errorMessage": "رمز CVV2 غير صالح",
  "isReversal": false
}

Refunds & Reversals #

Manual refunds #

Refunds are not available through the API. To refund a completed payment, the merchant contacts Al-Saqi support and sends the paymentId and rrn.

Error Codes & Statuses #

Link Status Reference #

The linkStatus field on every status response maps to one of the following values.

Common processor response codes #

Postman Collection #

Download the collection with the button at the end of this section and import it into Postman. Enter userName and password in the Variables tab; copy the other values from the responses as shown in the table below.

Collection variables

Download Postman collection

Changelog & Updates #