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

# Initialize a payment

> Creates a payment session and returns a URL to redirect your customer to.

The `payment_type` field determines which URL you get back:

| `payment_type` | Flow | Redirect using |
| --- | --- | --- |
| `1` | Direct to K-Net | `direct_url` |
| `2` | Direct to Credit Card | `direct_url` |
| `3` | Hosted Transit Page (includes Apple Pay) | `transit_url` |

Store the returned `PaymentID` — you need it to check the payment status and to issue refunds.




## OpenAPI

````yaml /openapi.yaml post /ws/paymentgateway/index
openapi: 3.1.0
info:
  title: Payzah Payment Gateway API
  version: 1.0.0
  description: >
    Accept K-Net, VISA, MasterCard, and Apple Pay payments in Kuwait.


    Every endpoint is a `POST` request with a JSON body. Authenticate by sending
    your

    Base64-encoded private key in the `Authorization` header.


    **All requests must be made server-side.** Never expose your private key in

    client-side code, mobile app binaries, or public repositories.


    ## Testing from these docs


    The interactive console below is pointed at the **test environment only**

    (`https://development.payzah.net`). Requests you send from this page create
    real

    sandbox transactions, but no real money moves.


    Use your **test** API key and the [sandbox test
    cards](/guides/test-credentials).

    Production endpoints are deliberately excluded here — switch your base URL
    to

    production only from your own server code, once your integration is fully
    validated.
  contact:
    name: Payzah Support
    email: Info@payzah.com
    url: https://payzah.com
  x-logo:
    altText: Payzah
servers:
  - url: https://development.payzah.net
    description: Test environment (sandbox)
security:
  - PrivateKeyAuth: []
tags:
  - name: Payments
    description: Create payment sessions and check their outcome.
  - name: Refunds
    description: Return funds to a customer for a completed transaction.
paths:
  /ws/paymentgateway/index:
    post:
      tags:
        - Payments
      summary: Initialize a payment
      description: >
        Creates a payment session and returns a URL to redirect your customer
        to.


        The `payment_type` field determines which URL you get back:


        | `payment_type` | Flow | Redirect using |

        | --- | --- | --- |

        | `1` | Direct to K-Net | `direct_url` |

        | `2` | Direct to Credit Card | `direct_url` |

        | `3` | Hosted Transit Page (includes Apple Pay) | `transit_url` |


        Store the returned `PaymentID` — you need it to check the payment status
        and to issue refunds.
      operationId: initializePayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitializeRequest'
            examples:
              transit:
                summary: Hosted Transit Page (all methods)
                value:
                  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'
              knet:
                summary: Direct to K-Net
                value:
                  trackid: ORDER-2002
                  amount: '11.250'
                  currency: '414'
                  success_url: https://yourstore.com/success
                  error_url: https://yourstore.com/error
                  payment_type: '1'
                  language: ENG
              card:
                summary: Direct to Credit Card
                value:
                  trackid: ORDER-2003
                  amount: '11.250'
                  currency: '414'
                  success_url: https://yourstore.com/success
                  error_url: https://yourstore.com/error
                  payment_type: '2'
                  language: ENG
      responses:
        '200':
          description: >
            Always returned with HTTP 200. Check the `status` field to determine
            success or failure.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InitializeSuccess'
                  - $ref: '#/components/schemas/ErrorResponse'
              examples:
                success:
                  summary: Success — transit
                  value:
                    status: true
                    data:
                      PaymentUrl: https://development.payzah.net/pgaction
                      PaymentID: '2019070115360420'
                      transit_url: https://devgateway.trytajer.app?id=202409271806248183
                      direct_url: ''
                error:
                  summary: Failure — invalid token
                  value:
                    status: false
                    message: Invalid token passed. Please contact administrator
                    code: '10014'
components:
  schemas:
    InitializeRequest:
      type: object
      required:
        - trackid
        - amount
        - currency
        - success_url
        - error_url
      properties:
        trackid:
          type: string
          maxLength: 255
          description: >-
            Your unique identifier for this transaction. Alphanumeric only — no
            special characters. Must never be reused.
          example: ORDER-2001
        amount:
          type: string
          maxLength: 10
          description: >-
            Transaction amount as a plain decimal string. No currency symbols,
            commas, or spaces.
          example: '11.250'
        currency:
          type: string
          maxLength: 3
          description: ISO 4217 numeric currency code. Use `414` for Kuwaiti Dinar.
          example: '414'
        success_url:
          type: string
          maxLength: 255
          description: URL Payzah redirects the customer to after a successful payment.
          example: https://yourstore.com/success
        error_url:
          type: string
          maxLength: 255
          description: >-
            URL Payzah redirects the customer to if payment fails or is
            cancelled.
          example: https://yourstore.com/error
        payment_type:
          type: string
          enum:
            - '1'
            - '2'
            - '3'
          description: >
            Which checkout experience to use.

            `1` = direct to K-Net, `2` = direct to Credit Card, `3` = hosted
            Transit Page (includes Apple Pay).
          example: '3'
        language:
          type: string
          enum:
            - ENG
            - ARA
          description: Language shown on the Payzah payment page. Defaults to `ENG`.
          example: ENG
        kfast_id:
          type: number
          description: >-
            K-Net faster checkout customer ID, if the customer has enrolled in
            K-Net fast checkout.
        customer_name:
          type: string
          maxLength: 255
          description: Customer's full name, for tracking and reconciliation.
          example: Ahmed Al-Rashid
        customer_phone:
          type: string
          maxLength: 255
          description: Customer's phone number, for tracking.
          example: '96512345678'
        customer_email:
          type: string
          maxLength: 255
          description: Customer's email address, for tracking.
          example: ahmed@example.com
        udf1:
          type: string
          maxLength: 255
          description: User-defined field 1. No special characters.
        udf2:
          type: string
          maxLength: 255
          description: User-defined field 2. No special characters.
        udf3:
          type: string
          maxLength: 255
          description: User-defined field 3. No special characters.
        udf4:
          type: string
          maxLength: 255
          description: User-defined field 4. No special characters.
        udf5:
          type: string
          maxLength: 255
          description: User-defined field 5. No special characters.
        delivery_company:
          type: number
          description: >-
            Multivendor only — numeric identifier for the delivery company on
            this order.
        delivery_cost:
          type: number
          description: Multivendor only — delivery cost applied to this transaction.
        commission_type:
          type: number
          enum:
            - 1
            - 2
            - 3
          description: Multivendor only — `1` fixed amount, `2` percentage, `3` mixed.
        commission_percent:
          type: number
          description: >-
            Multivendor only — percentage rate, used when `commission_type` is
            `2` or `3`.
        commission_fixed:
          type: number
          description: >-
            Multivendor only — fixed amount, used when `commission_type` is `1`
            or `3`.
    InitializeSuccess:
      type: object
      properties:
        status:
          type: boolean
          const: true
          description: '`true` when the payment session was created successfully.'
          example: true
        data:
          type: object
          properties:
            PaymentUrl:
              type: string
              description: >-
                Base URL of the Payzah payment action endpoint. Do not redirect
                here — use `transit_url` or `direct_url`.
            PaymentID:
              type: string
              description: >-
                Payzah's unique identifier for this payment session. Store this
                — it is required for status checks and refunds.
            transit_url:
              type: string
              description: >-
                Hosted payment page URL. Populated when `payment_type` is `3`;
                empty otherwise. Redirect immediately — the URL is
                session-specific and expires.
            direct_url:
              type: string
              description: >-
                Direct payment provider URL. Populated when `payment_type` is
                `1` or `2`; empty otherwise.
    ErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          const: false
          description: '`false` when the request failed. Always check this field.'
          example: false
        message:
          type: string
          description: Human-readable description of the error.
          example: No Record found for the provided details
        code:
          description: >
            Numeric error code. See the Response Codes reference for the full
            list of codes 10000–10015.


            Commonly returned values:


            | Code | Meaning |

            | --- | --- |

            | `10001` | `trackid` contains invalid characters |

            | `10002` | `trackid` missing |

            | `10003` | `amount` malformed |

            | `10004` | `amount` missing |

            | `10005` | `success_url` missing |

            | `10006` | `error_url` missing |

            | `10012` | No record found for the provided details |

            | `10013` | Request body empty or not JSON |

            | `10014` | Invalid Authorization token |

            | `10015` | Account not permitted to use Credit Card direct
            integration |
          oneOf:
            - type: string
            - type: integer
          example: 10012
  securitySchemes:
    PrivateKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Your private key, Base64-encoded.


        Encode the key before sending it — for example
        `base64_encode($privateKey)` in PHP or

        `Buffer.from(privateKey).toString('base64')` in Node.js. Paste the
        **already-encoded**

        value here when testing from these docs.


        **Use your test key here.** This console only calls the sandbox
        environment,

        so a production key will not authenticate.

````