Skip to main content
The transit initialization method sends your customer to a Payzah-hosted payment page that presents all available payment options — including Apple Pay. You submit your order details with payment_type set to "3", receive a transit_url in the response, and then redirect the customer to that URL. Payzah handles the payment method selection and card capture on its secure page before redirecting the customer back to your success_url or error_url. Endpoint: POST /ws/paymentgateway/index Refer to the API Overview for the base URLs and required authentication headers before making this request.

​
Request Parameters

​
trackid
string
required
Your unique identifier for this transaction. Alphanumeric only — no special characters. Maximum 255 characters. You will use this value later to look up the payment status.
​
amount
string
required
The transaction amount as a plain decimal number (e.g. "11.250"). Do not include currency symbols, commas, or any other formatting characters. Maximum 10 characters.
​
currency
string
required
The ISO 4217 numeric currency code (e.g. "414" for Kuwaiti Dinar). Maximum 3 characters.
​
success_url
string
required
The URL Payzah redirects the customer to after a successful payment. Maximum 255 characters.
​
error_url
string
required
The URL Payzah redirects the customer to if the payment fails or is cancelled. Maximum 255 characters.
​
payment_type
string
Set to "3" to use the hosted transit page, which includes all payment methods and Apple Pay. Omitting this field defaults to the transit flow on most accounts — explicitly passing "3" is recommended for clarity.
​
language
string
The language displayed on the Payzah payment page. Accepted values: "ENG" (English) or "ARA" (Arabic). Maximum 3 characters. Defaults to "ENG" when omitted.
​
kfast_id
number
K-Net faster checkout customer ID, if your customer has previously enrolled in K-Net’s fast-checkout program. Maximum 8 characters.
​
customer_name
string
Customer’s full name, used for internal tracking and reconciliation. Maximum 255 characters.
​
customer_phone
string
Customer’s phone number, used for tracking. Maximum 255 characters.
​
customer_email
string
Customer’s email address, used for tracking. Maximum 255 characters.
​
udf1
string
User-defined field 1. Store any custom data you need to associate with this transaction. No special characters. Maximum 255 characters.
​
udf2
string
User-defined field 2. No special characters. Maximum 255 characters.
​
udf3
string
User-defined field 3. No special characters. Maximum 255 characters.
​
udf4
string
User-defined field 4. No special characters. Maximum 255 characters.
​
udf5
string
User-defined field 5. No special characters. Maximum 255 characters.

​
Multivendor / Deep-Linking Fields

If your platform settles payments across multiple sub-merchants, include the fields below to specify delivery costs and commission rules. These fields are optional for standard single-vendor integrations.

​
Sample Request

cURL
curl --request POST \
  --url https://development.payzah.net/ws/paymentgateway/index \
  --header 'Content-Type: application/json' \
  --header "Authorization: $(echo -n 'your_private_key_here' | base64)" \
  --data '{
    "trackid": "ORDER-2001",
    "amount": "11.250",
    "currency": "414",
    "success_url": "https://yourstore.com/success",
    "error_url": "https://yourstore.com/error",
    "payment_type": "3",
    "language": "ENG",
    "customer_name": "Ahmed Al-Rashid",
    "customer_email": "[email protected]",
    "customer_phone": "96512345678"
  }'
Request Body
{
  "trackid": "ORDER-2001",
  "amount": "11.250",
  "currency": "414",
  "success_url": "https://yourstore.com/success",
  "error_url": "https://yourstore.com/error",
  "payment_type": "3",
  "language": "ENG",
  "customer_name": "Ahmed Al-Rashid",
  "customer_email": "[email protected]",
  "customer_phone": "96512345678"
}

​
Response Fields

​
Success Response

​
status
boolean
true when the payment session was created successfully.
​
data
object
Contains the URLs and identifiers needed to complete the payment flow.

​
Error Response

​
status
boolean
false when the request failed.
​
message
string
A human-readable description of the error.
​
code
string
A numeric error code. See the Response Codes reference for the full list.

​
Sample Responses

Success
{
  "status": true,
  "data": {
    "PaymentUrl": "https://development.payzah.net/pgaction",
    "PaymentID": "2019070115360420",
    "transit_url": "https://devgateway.trytajer.app?id=202409271806248183",
    "direct_url": ""
  }
}
Error
{
  "status": false,
  "message": "Invalid token passed. Please contact administrator",
  "code": "10014"
}
After a successful response, redirect your customer to the transit_url immediately. This URL is session-specific and expires — do not cache it or delay the redirect. Once the customer completes or abandons the payment, Payzah will redirect them to your success_url or error_url as specified in the request.