POST /ws/paymentgateway/index — Transit Payment Page

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

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.

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.

string

required

The ISO 4217 numeric currency code (e.g. "414" for Kuwaiti Dinar). Maximum 3 characters.

string

required

The URL Payzah redirects the customer to after a successful payment. Maximum 255 characters.

string

required

The URL Payzah redirects the customer to if the payment fails or is cancelled. Maximum 255 characters.

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.

string

The language displayed on the Payzah payment page. Accepted values: "ENG" (English) or "ARA" (Arabic). Maximum 3 characters. Defaults to "ENG" when omitted.

number

K-Net faster checkout customer ID, if your customer has previously enrolled in K-Net’s fast-checkout program. Maximum 8 characters.

string

Customer’s full name, used for internal tracking and reconciliation. Maximum 255 characters.

string

Customer’s phone number, used for tracking. Maximum 255 characters.

string

Customer’s email address, used for tracking. Maximum 255 characters.

string

User-defined field 1. Store any custom data you need to associate with this transaction. No special characters. Maximum 255 characters.

string

User-defined field 2. No special characters. Maximum 255 characters.

string

User-defined field 3. No special characters. Maximum 255 characters.

string

User-defined field 4. No special characters. Maximum 255 characters.

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.

Show Multivendor & Deep-Linking Fields

number

Numeric identifier for the delivery company associated with this order.

number

The delivery cost amount to be applied to this transaction.

number

Defines how the platform commission is calculated:

1 — Fixed amount
2 — Percentage of transaction
3 — Mixed (fixed + percentage)

number

The percentage rate to apply when commission_type is 2 or 3.

number

The fixed commission amount to apply when commission_type is 1 or 3.

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

boolean

true when the payment session was created successfully.

object

Contains the URLs and identifiers needed to complete the payment flow.

Show data fields

string

The base URL of the Payzah payment action endpoint. Use transit_url (not this field) to redirect the customer for transit payments.

string

Payzah’s unique identifier for this payment session. Store this value — you will need it to query the payment status later.

string

The full URL of the hosted payment page for this session. Redirect your customer to this URL immediately after receiving the response.

string

Empty string for transit payments. This field is populated only for direct integration requests.

Error Response

boolean

false when the request failed.

string

A human-readable description of the error.

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.

Try It Live

Payment Initialization

Payment Status

POST /ws/paymentgateway/index — Transit Payment Page

Request Parameters

Multivendor / Deep-Linking Fields

Sample Request

Response Fields

Success Response

Error Response

Sample Responses

​Request Parameters

​Multivendor / Deep-Linking Fields

​Sample Request

​Response Fields

​Success Response

​Error Response

​Sample Responses

Request Parameters

Multivendor / Deep-Linking Fields

Sample Request

Response Fields

Success Response

Error Response

Sample Responses