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

# POST /ws/paymentgateway/index — Transit Payment Page

> Initialize a payment on Payzah's hosted transit page, which supports all payment methods including Apple Pay, and receive a redirect URL for your customer.

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](/api-reference/overview) for the base URLs and required authentication headers before making this request.

## Request Parameters

<ParamField body="trackid" type="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.
</ParamField>

<ParamField body="amount" type="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.
</ParamField>

<ParamField body="currency" type="string" required>
  The ISO 4217 numeric currency code (e.g. `"414"` for Kuwaiti Dinar). Maximum
  3 characters.
</ParamField>

<ParamField body="success_url" type="string" required>
  The URL Payzah redirects the customer to after a successful payment. Maximum
  255 characters.
</ParamField>

<ParamField body="error_url" type="string" required>
  The URL Payzah redirects the customer to if the payment fails or is cancelled.
  Maximum 255 characters.
</ParamField>

<ParamField body="payment_type" type="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.
</ParamField>

<ParamField body="language" type="string">
  The language displayed on the Payzah payment page. Accepted values: `"ENG"`
  (English) or `"ARA"` (Arabic). Maximum 3 characters. Defaults to `"ENG"` when
  omitted.
</ParamField>

<ParamField body="kfast_id" type="number">
  K-Net faster checkout customer ID, if your customer has previously enrolled
  in K-Net's fast-checkout program. Maximum 8 characters.
</ParamField>

<ParamField body="customer_name" type="string">
  Customer's full name, used for internal tracking and reconciliation. Maximum
  255 characters.
</ParamField>

<ParamField body="customer_phone" type="string">
  Customer's phone number, used for tracking. Maximum 255 characters.
</ParamField>

<ParamField body="customer_email" type="string">
  Customer's email address, used for tracking. Maximum 255 characters.
</ParamField>

<ParamField body="udf1" type="string">
  User-defined field 1. Store any custom data you need to associate with this
  transaction. No special characters. Maximum 255 characters.
</ParamField>

<ParamField body="udf2" type="string">
  User-defined field 2. No special characters. Maximum 255 characters.
</ParamField>

<ParamField body="udf3" type="string">
  User-defined field 3. No special characters. Maximum 255 characters.
</ParamField>

<ParamField body="udf4" type="string">
  User-defined field 4. No special characters. Maximum 255 characters.
</ParamField>

<ParamField body="udf5" type="string">
  User-defined field 5. No special characters. Maximum 255 characters.
</ParamField>

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

<Expandable title="Multivendor & Deep-Linking Fields">
  <ParamField body="delivery_company" type="number">
    Numeric identifier for the delivery company associated with this order.
  </ParamField>

  <ParamField body="delivery_cost" type="number">
    The delivery cost amount to be applied to this transaction.
  </ParamField>

  <ParamField body="commission_type" type="number">
    Defines how the platform commission is calculated:

    * `1` — Fixed amount
    * `2` — Percentage of transaction
    * `3` — Mixed (fixed + percentage)
  </ParamField>

  <ParamField body="commission_percent" type="number">
    The percentage rate to apply when `commission_type` is `2` or `3`.
  </ParamField>

  <ParamField body="commission_fixed" type="number">
    The fixed commission amount to apply when `commission_type` is `1` or `3`.
  </ParamField>
</Expandable>

## Sample Request

```bash cURL theme={null}
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": "ahmed@example.com",
    "customer_phone": "96512345678"
  }'
```

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

## Response Fields

### Success Response

<ResponseField name="status" type="boolean">
  `true` when the payment session was created successfully.
</ResponseField>

<ResponseField name="data" type="object">
  Contains the URLs and identifiers needed to complete the payment flow.

  <Expandable title="data fields">
    <ResponseField name="PaymentUrl" type="string">
      The base URL of the Payzah payment action endpoint. Use `transit_url`
      (not this field) to redirect the customer for transit payments.
    </ResponseField>

    <ResponseField name="PaymentID" type="string">
      Payzah's unique identifier for this payment session. Store this value —
      you will need it to query the payment status later.
    </ResponseField>

    <ResponseField name="transit_url" type="string">
      The full URL of the hosted payment page for this session. Redirect your
      customer to this URL immediately after receiving the response.
    </ResponseField>

    <ResponseField name="direct_url" type="string">
      Empty string for transit payments. This field is populated only for
      direct integration requests.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Response

<ResponseField name="status" type="boolean">
  `false` when the request failed.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable description of the error.
</ResponseField>

<ResponseField name="code" type="string">
  A numeric error code. See the [Response Codes](/api-reference/response-codes)
  reference for the full list.
</ResponseField>

## Sample Responses

```json Success theme={null}
{
  "status": true,
  "data": {
    "PaymentUrl": "https://development.payzah.net/pgaction",
    "PaymentID": "2019070115360420",
    "transit_url": "https://devgateway.trytajer.app?id=202409271806248183",
    "direct_url": ""
  }
}
```

```json Error theme={null}
{
  "status": false,
  "message": "Invalid token passed. Please contact administrator",
  "code": "10014"
}
```

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