Integrate Payzah Using Direct Payment Method Links

Direct Integration gives you precise control over which payment method your customer uses. Instead of routing through Payzah’s hosted Transit Payment Page, Payzah returns a direct_url that sends your customer straight to the chosen payment provider — K-Net or Credit Card — without an intermediate step. Choose this integration method when you want to present payment options in your own UI and route customers based on their selection.

When to Use Direct Integration

Use Direct Integration when:

You have a custom-designed checkout that already shows K-Net and Credit Card as separate buttons
You want to eliminate the intermediate Payzah-hosted page from the redirect chain
You need independent control over which payment methods are available at specific points in your flow

Direct Integration does not support Apple Pay. If you need Apple Pay, use the Transit Payment Page with payment_type: "3" instead.

How Direct Integration Works

Choose the Correct payment_type for Your Method

Direct Integration uses two distinct payment_type values — one for K-Net and one for Credit Card. Select the value that matches the payment method your customer chose on your checkout page.

Payment method	`payment_type` value
K-Net	`"1"`
Credit Card (VISA / MasterCard)	`"2"`

You must set this value dynamically based on your customer’s selection before you send the initialization request.

Send the Initialization Request

From your server, send a POST request to the Payzah initialization endpoint with the appropriate payment_type. The request structure is identical to the Transit integration — only the payment_type value changes.Endpoints

Environment	URL
Test	`https://development.payzah.net/ws/paymentgateway/index`
Production	`https://payzah.net/production770/ws/paymentgateway/index`

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`base64_encode($privateKey)`

Your private key must never appear in client-side code, front-end JavaScript, or mobile app binaries. Always make this request from your backend server.

The tabs below show sample request bodies for each payment method:

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

{
  "trackid": "ORDER-20240927-00456",
  "amount": "11.250",
  "success_url": "https://yourstore.com/payment/success",
  "error_url": "https://yourstore.com/payment/error",
  "currency": "414",
  "language": "ENG",
  "payment_type": "1",
  "customer_name": "Fatima Al-Rashidi",
  "customer_email": "[email protected]",
  "customer_phone": "96598765432",
  "udf1": "order-ref-002"
}

{
  "trackid": "ORDER-20240927-00789",
  "amount": "11.250",
  "success_url": "https://yourstore.com/payment/success",
  "error_url": "https://yourstore.com/payment/error",
  "currency": "414",
  "language": "ENG",
  "payment_type": "2",
  "customer_name": "Khalid Al-Mutairi",
  "customer_email": "[email protected]",
  "customer_phone": "96555544433",
  "udf1": "order-ref-003"
}

Read the direct_url from the Response

A successful initialization response returns status: true with a populated direct_url field. The transit_url field will be empty — this is the opposite of what you see with Transit Integration.

Success Response

{
  "status": true,
  "data": {
    "PaymentUrl": "https://development.payzah.net/pgaction",
    "PaymentID": "2019070115360420",
    "transit_url": "",
    "direct_url": "https://development.payzah.net/pgaction?PaymentID=202409271806248183"
  }
}

The direct_url already contains the PaymentID as a query parameter, pointing directly to the payment provider’s page. Store the PaymentID value from data.PaymentID before redirecting, so you can reconcile the callback with your order.

If status is false, do not redirect the customer. Display a user-friendly error, log the response details, and allow them to retry. Never redirect to a URL from a failed response.

Comparing Transit and Direct response URLs

Field	Transit (payment_type 3)	Direct (payment_type 1 or 2)
`transit_url`	Populated — redirect here	Empty
`direct_url`	Empty	Populated — redirect here

Redirect Your Customer to the direct_url

Redirect your customer’s browser to the direct_url returned in the response. They will land directly on the K-Net or Credit Card payment provider’s page.

PHP Redirect

<?php

if ($result['status'] === true) {
    $directUrl = $result['data']['direct_url'];
    header('Location: ' . $directUrl);
    exit;
}

Express.js Redirect

if (result.status === true) {
  res.redirect(result.data.direct_url);
}

The redirect URL follows this pattern:

https://development.payzah.net/pgaction?PaymentID=2019070115360420

In production, the domain changes but the path and query string format remain the same. Always use the direct_url value from the response rather than constructing the URL manually.

Handle the Success and Error Redirects

Once your customer completes or abandons payment on the provider’s page, Payzah redirects them back to your success_url or error_url with the transaction result appended as query parameters.Payment response fields

Field	Description
`payzahReferenceCode`	Payzah’s unique reference ID for this transaction
`trackId`	The `trackid` value you sent in the initialization request
`knetPaymentId`	Unique ID assigned by the payment gateway (K-Net or card network)
`transactionNumber`	Unique identifier for this specific transaction
`trackingNumber`	Track ID echoed back from your original request
`paymentDate`	Date on which the payment was processed
`paymentStatus`	Final outcome of the transaction (see table below)
`udf1`–`udf5`	Any user-defined fields you included in the initialization request

paymentStatus values

Status	Meaning	Recommended action
`CAPTURED`	Funds captured successfully	Fulfil the order
`VOIDED`	Transaction voided before capture	Do not fulfil; notify customer
`NOT CAPTURED`	Authorised but capture incomplete	Investigate before acting
`CANCELED`	Customer cancelled on provider’s page	Allow customer to retry
`DENIED BY RISK`	Blocked by fraud/risk controls	Do not fulfil; ask customer to contact support
`HOST TIMEOUT`	Gateway timed out — outcome unknown	Hold the order and confirm status manually

Only fulfil an order when paymentStatus is CAPTURED. A redirect to your success_url without a CAPTURED status does not confirm that funds were collected.

Request Field Reference

Use this table when constructing your initialization request body for Direct Integration.

Field	Type	Max length	Mandatory	Description
`trackid`	Alphanumeric	255	Yes	Unique ID per transaction — must not be reused
`amount`	Numeric	10	Yes	Transaction amount, e.g. `11.250`
`success_url`	Alphanumeric	255	Yes	Your URL for successful payment callbacks
`error_url`	Alphanumeric	255	Yes	Your URL for failed or cancelled payment callbacks
`currency`	Numeric	3	Yes	ISO 4217 numeric code, e.g. `414` for KWD
`payment_type`	Fixed	1	No*	`"1"` for K-Net, `"2"` for Credit Card
`language`	Alpha	3	No	`ENG` or `ARA`
`kfast_id`	Numeric	8	No	K-Net faster checkout identifier
`customer_name`	Alphanumeric	255	No	Customer’s full name
`customer_phone`	Alphanumeric	255	No	Customer’s phone number
`customer_email`	Alphanumeric	255	No	Customer’s email address
`udf1`–`udf5`	Alphanumeric	255	No	Additional fields for your own reference

Although payment_type is technically optional, you should always supply it explicitly ("1" for K-Net or "2" for Credit Card) when using Direct Integration to ensure the correct provider page is returned in direct_url.

​When to Use Direct Integration

​How Direct Integration Works

​Request Field Reference

When to Use Direct Integration

How Direct Integration Works

Request Field Reference