> ## 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 — Direct Integration

> Initialize a direct payment by specifying payment_type 1 for K-Net or 2 for Credit Card, and receive a direct redirect URL to send your customer to.

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](/api-reference/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 |

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

## 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 check
  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" required>
  The payment method to use directly:

  * `"1"` — K-Net
  * `"2"` — Credit Card
</ParamField>

<ParamField body="language" type="string">
  The language displayed on the 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 is enrolled in K-Net's
  fast-checkout program. Applicable when `payment_type` is `"1"`. 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 alongside 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 Requests

<Tabs>
  <Tab title="K-Net (payment_type=1)">
    ```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-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": "fatima@example.com"
      }'
    ```

    ```json Request Body theme={null}
    {
      "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": "fatima@example.com"
    }
    ```
  </Tab>

  <Tab title="Credit Card (payment_type=2)">
    ```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-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": "khalid@example.com"
      }'
    ```

    ```json Request Body theme={null}
    {
      "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": "khalid@example.com"
    }
    ```
  </Tab>
</Tabs>

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

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

    <ResponseField name="transit_url" type="string">
      Empty string for direct payments. Populated only when `payment_type` is
      `"3"` (transit flow).
    </ResponseField>

    <ResponseField name="direct_url" type="string">
      The full URL to redirect your customer to for direct K-Net or Credit Card
      payment. This URL is unique to the session.
    </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": "",
    "direct_url": "https://development.payzah.net/pgaction?PaymentID=202409271806248183"
  }
}
```

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