> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payzah.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Payzah's Transit Payment Page (Fast Setup)

> Set up Payzah's hosted Transit Payment Page to accept K-Net, VISA, MasterCard, and Apple Pay — all from a single branded checkout page Payzah maintains.

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

<Steps>
  <Step title="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)` |

    <Warning>
      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
    </Warning>

    Below is a complete sample initialization request body:

    <CodeGroup>
      ```json Request Body theme={null}
      {
        "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": "ahmed@example.com",
        "customer_phone": "96512345678",
        "udf1": "order-ref-001"
      }
      ```

      ```php PHP theme={null}
      <?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' => 'ahmed@example.com',
          'customer_phone' => '96512345678',
          '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);
      ```

      ```javascript Node.js theme={null}
      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: 'ahmed@example.com',
        customer_phone: '96512345678',
        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();
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    ```json Success Response theme={null}
    {
      "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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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 PHP Redirect theme={null}
    <?php

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

    ```javascript Express.js Redirect theme={null}
    if (result.status === true) {
      res.redirect(result.data.transit_url);
    }
    ```

    <Tip>
      Save the `PaymentID` to your order records before redirecting, so you can match it to the callback Payzah sends when the customer completes payment.
    </Tip>
  </Step>

  <Step title="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 |
  </Step>
</Steps>

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

<Note>
  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](/guides/direct-integration) instead.
</Note>