Integrate Payzah's Transit Payment Page (Fast Setup)

The Transit Payment Page is Payzah’s fully hosted checkout experience. After you send a single initialization request, Payzah redirects your customer to a branded payment page that supports K-Net, VISA, MasterCard, and Apple Pay — all in one place. Payzah handles the UI, security, and ongoing maintenance, so you can go live quickly without building a custom payment interface.

How Transit Integration Works

Send the Initialization Request with payment_type 3

From your server, send a POST request to the Payzah initialization endpoint with payment_type set to "3". This single value covers all supported payment methods, including Apple Pay.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 be kept secret at all times. Never include it in front-end JavaScript, mobile app code, or any client-accessible resource. Always make this request from your backend server.Testing Private Key : 57726c6bace917f85a7d179197ca803a09b835da

Below is a complete sample initialization request body:

{
  "trackid": "ORDER-20240927-00123",
  "amount": "11.250",
  "success_url": "https://yourstore.com/payment/success",
  "error_url": "https://yourstore.com/payment/error",
  "currency": "414",
  "language": "ENG",
  "payment_type": "3",
  "customer_name": "Ahmed Adam",
  "customer_email": "[email protected]",
  "customer_phone": "92345678",
  "udf1": "order-ref-001"
}

<?php

$privateKey = 'YOUR_PRIVATE_KEY';
$endpoint   = 'https://development.payzah.net/ws/paymentgateway/index';

$payload = [
    'trackid'        => 'ORDER-20240927-00123',
    'amount'         => '11.250',
    'success_url'    => 'https://yourstore.com/payment/success',
    'error_url'      => 'https://yourstore.com/payment/error',
    'currency'       => '414',
    'language'       => 'ENG',
    'payment_type'   => '3',
    'customer_name'  => 'Ahmed Al-Salem',
    'customer_email' => '[email protected]',
    'customer_phone' => '92345678',
    'udf1'           => 'order-ref-001',
];

$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: ' . base64_encode($privateKey),
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

const https = require('https');

const privateKey = 'YOUR_PRIVATE_KEY';
const payload = JSON.stringify({
  trackid:        'ORDER-20240927-00123',
  amount:         '11.250',
  success_url:    'https://yourstore.com/payment/success',
  error_url:      'https://yourstore.com/payment/error',
  currency:       '414',
  language:       'ENG',
  payment_type:   '3',
  customer_name:  'Ahmed Al-Salem',
  customer_email: '[email protected]',
  customer_phone: '92345678',
  udf1:           'order-ref-001',
});

const options = {
  hostname: 'development.payzah.net',
  path:     '/ws/paymentgateway/index',
  method:   'POST',
  headers: {
    'Content-Type':  'application/json',
    'Authorization': Buffer.from(privateKey).toString('base64'),
  },
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => {
    const result = JSON.parse(data);
    // Use result.data.transit_url to redirect the customer
  });
});

req.write(payload);
req.end();

Read the transit_url from the Response

When your initialization request succeeds, Payzah returns a JSON response with status: true. The transit_url field contains the URL you will redirect your customer to. The direct_url field will be empty for Transit integrations.

Success Response

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

Extract and store the transit_url and PaymentID values. You will need PaymentID to correlate Payzah’s callback with your order records.

If status is false, do not redirect the customer. Log the error response, surface a friendly message to your customer, and allow them to retry or choose another payment method.

Redirect Your Customer to the Transit URL

Immediately redirect your customer’s browser to the transit_url value returned in the previous step. Payzah’s hosted payment page will load and present all available payment options — K-Net, VISA, MasterCard, and Apple Pay — in a single branded interface.

PHP Redirect

<?php

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

Express.js Redirect

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

Save the PaymentID to your order records before redirecting, so you can match it to the callback Payzah sends when the customer completes payment.

Handle the Success and Error Redirects

After your customer completes or abandons payment, Payzah redirects them back to either your success_url or error_url. These URLs receive the transaction result as query parameters.Key parameters returned to your URLs

Parameter	Description
`payzahReferenceCode`	Payzah’s unique reference for this transaction
`trackId`	The `trackid` you sent in the initialization request
`knetPaymentId`	Unique ID assigned by the payment gateway
`transactionNumber`	Unique transaction identifier
`trackingNumber`	Track ID echoed from your request
`paymentDate`	Date the payment was processed
`paymentStatus`	Final transaction status (see below)
`udf1`–`udf5`	Any user-defined fields you included in the request

At your success_url, verify that paymentStatus equals CAPTURED before fulfilling the order. Do not rely solely on the redirect to success_url as confirmation.Possible paymentStatus values

Status	Meaning
`CAPTURED`	Funds captured — safe to fulfil the order
`VOIDED`	Transaction was voided before capture
`NOT CAPTURED`	Authorised but not captured
`CANCELED`	Customer cancelled on the payment page
`DENIED BY RISK`	Blocked by risk rules
`HOST TIMEOUT`	Gateway timed out — confirm status before acting

Why Use the Transit Payment Page?

The Transit Payment Page is the recommended integration path for most merchants because Payzah manages the full payment interface on your behalf.

Feature	Detail
Single `payment_type`	Use `"3"` for all methods — K-Net, VISA, MasterCard, and Apple Pay
Branded experience	The page displays your merchant logo automatically
Payzah-managed security	PCI DSS compliance, TLS, and fraud controls handled by Payzah
No UI maintenance	Payment method updates and UI improvements are applied by Payzah

If you need to send customers directly to a specific payment provider’s page without the intermediate Payzah-hosted step, see the Direct Integration guide instead.

Get Started

Plugins & Platforms

Custom Integration Guide

Testing & Go-Live

Resources

Integrate Payzah's Transit Payment Page (Fast Setup)

How Transit Integration Works

Why Use the Transit Payment Page?

​How Transit Integration Works

​Why Use the Transit Payment Page?

How Transit Integration Works

Why Use the Transit Payment Page?