POST /ws/paymentgateway/index — Direct Integration

The direct integration method gives you explicit control over which payment method the customer sees. Instead of landing on a Payzah-hosted selection page, the customer is taken straight to the K-Net or Credit Card flow — eliminating an extra step in your checkout. You specify the payment method via the payment_type field, and the response contains a direct_url that you use to redirect the customer. Endpoint: POST /ws/paymentgateway/index Refer to the API Overview for the base URLs and required authentication headers before making this request.

Payment Type Values

`payment_type`	Payment Method
`"1"`	Direct K-Net — routes the customer to the K-Net payment portal
`"2"`	Direct Credit Card — routes the customer to the credit card entry form

Credit Card direct integration requires the credit card permission to be enabled on your Payzah account. If it is not enabled, the API returns error code 10015. Contact Payzah support to enable this feature.

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 check 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

required

The payment method to use directly:

"1" — K-Net
"2" — Credit Card

string

The language displayed on the 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 is enrolled in K-Net’s fast-checkout program. Applicable when payment_type is "1". 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. Optional — you may omit the field entirely or send an empty value.If you do send a value, it must satisfy all of the following, or the request will be rejected:

Rule	Detail
Length	Between 8 and 15 digits
First digit	Must not be `0`
Characters	Digits only — no `+`, `-`, spaces, or brackets

Valid: 96512345678, 12345678Invalid: +96512345678, 965-1234-5678, 0965123456, 1234567

string

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

string

User-defined field 1. Store any custom data you need alongside 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 Requests

K-Net (payment_type=1)
Credit Card (payment_type=2)

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-3001",
    "amount": "5.500",
    "currency": "414",
    "success_url": "https://yourstore.com/success",
    "error_url": "https://yourstore.com/error",
    "payment_type": "1",
    "language": "ENG",
    "customer_name": "Fatima Al-Sabah",
    "customer_email": "[email protected]"
  }'

Request Body

{
  "trackid": "ORDER-3001",
  "amount": "5.500",
  "currency": "414",
  "success_url": "https://yourstore.com/success",
  "error_url": "https://yourstore.com/error",
  "payment_type": "1",
  "language": "ENG",
  "customer_name": "Fatima Al-Sabah",
  "customer_email": "[email protected]"
}

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-3002",
    "amount": "22.000",
    "currency": "414",
    "success_url": "https://yourstore.com/success",
    "error_url": "https://yourstore.com/error",
    "payment_type": "2",
    "language": "ENG",
    "customer_name": "Khalid Al-Mutairi",
    "customer_email": "[email protected]"
  }'

Request Body

{
  "trackid": "ORDER-3002",
  "amount": "22.000",
  "currency": "414",
  "success_url": "https://yourstore.com/success",
  "error_url": "https://yourstore.com/error",
  "payment_type": "2",
  "language": "ENG",
  "customer_name": "Khalid Al-Mutairi",
  "customer_email": "[email protected]"
}

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 direct_url (not this field) to redirect the customer for direct payments.

string

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

string

Empty string for direct payments. Populated only when payment_type is "3" (transit flow).

string

The full URL to redirect your customer to for direct K-Net or Credit Card payment. This URL is unique to the session.

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": "",
    "direct_url": "https://development.payzah.net/pgaction?PaymentID=202409271806248183"
  }
}

Error

{
  "status": false,
  "message": "Invalid token passed. Please contact administrator",
  "code": "10014"
}

After a successful response, redirect your customer to the direct_url immediately. This URL is session-specific and expires — do not cache it or delay the redirect. Payzah will redirect the customer to your success_url or error_url once the payment is complete or if it fails.

Try It Live

Payment Initialization

Payment Status

POST /ws/paymentgateway/index — Direct Integration

Payment Type Values

Request Parameters

Multivendor / Deep-Linking Fields

Sample Requests

Response Fields

Success Response

Error Response

Sample Responses

​Payment Type Values

​Request Parameters

​Multivendor / Deep-Linking Fields

​Sample Requests

​Response Fields

​Success Response

​Error Response

​Sample Responses

Payment Type Values

Request Parameters

Multivendor / Deep-Linking Fields

Sample Requests

Response Fields

Success Response

Error Response

Sample Responses