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

# How Payzah Processes Payments: End-to-End Flow

> Understand the complete 5-step payment lifecycle — from your customer clicking pay to receiving a success or error redirect from Payzah.

Every transaction processed through Payzah follows the same five-step lifecycle, regardless of whether you use the Transit Payment Page or Direct Integration. Understanding this flow helps you build a reliable checkout experience and troubleshoot issues quickly.

57726c6bace917f85a7d179197ca803a09b835da

<Steps>
  <Step title="Customer Initiates Checkout">
    Your customer browses your website or app, adds items to their cart, and fills in any required details. At checkout, they select **Payzah** as their payment method and click the pay button.

    <Tip>
      Present Payzah prominently alongside supported payment logos (K-Net, VISA, MasterCard, Apple Pay) so customers know which methods are available before they reach the final step.
    </Tip>
  </Step>

  <Step title="You Send a Payment Initialization Request">
    After your customer clicks pay, your server collects the necessary payment details and sends a `POST` request to Payzah's initialization endpoint. This step is the same whether you are using Transit or Direct Integration.

    **Endpoints**

    | Environment | URL                                                        |
    | ----------- | ---------------------------------------------------------- |
    | Test        | `https://development.payzah.net/ws/paymentgateway/index`   |
    | Production  | `https://payzah.net/production770/ws/paymentgateway/index` |

    **Required headers**

    | Header          | Value                            |
    | --------------- | -------------------------------- |
    | `Content-Type`  | `application/json`               |
    | `Authorization` | Your private key, Base64-encoded |

    Your request body must include the transaction amount, a unique `trackid`, your `success_url`, your `error_url`, the currency code, and the `payment_type` that matches your integration method.

    <Warning>
      Never expose your private key in client-side code, JavaScript bundles, or mobile app binaries. Always send the initialization request from your **server**, not the browser or device.
    </Warning>
  </Step>

  <Step title="Payzah Processes Your Request">
    Payzah validates your request and responds in one of two ways:

    **Successful response** — Payzah issues an approval and returns a JSON object containing a `PaymentID` and redirect URLs (`transit_url` or `direct_url` depending on your `payment_type`).

    **Rejected response** — Payzah returns an error message and error code. Common reasons include an invalid private key, a missing required field, or a duplicate `trackid`.

    <Note>
      Your `trackid` must be unique per transaction. Reusing a `trackid` from a previous request will cause the initialization to be rejected.
    </Note>
  </Step>

  <Step title="You Redirect Your Customer">
    Once you receive a successful initialization response, immediately redirect your customer to the appropriate payment URL from the response body.

    The redirect destination depends on your integration type:

    | Integration              | Redirect destination                                                                                                 |
    | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
    | **Transit Payment Page** | Payzah's branded hosted page, which then routes to the customer's chosen provider (K-Net, Credit Card, or Apple Pay) |
    | **Direct Integration**   | The payment provider's page directly (K-Net or Credit Card), skipping the Payzah-hosted intermediate page            |

    <Tip>
      For the Transit Payment Page, use the `transit_url` field from the response. For Direct Integration, use the `direct_url` field. Only one of these fields will be populated depending on the `payment_type` you sent.
    </Tip>
  </Step>

  <Step title="Payzah Returns the Transaction Result">
    After the customer completes (or abandons) payment on the provider's page, Payzah processes the final transaction result and redirects your customer back to your site.

    * **Success** → customer is redirected to your `success_url` with transaction details appended as query parameters
    * **Failure or cancellation** → customer is redirected to your `error_url` with an error status

    At your `success_url` and `error_url` endpoints, read and store the returned parameters — including `payzahReferenceCode`, `paymentStatus`, and `transactionNumber` — to update your order records accordingly.

    <Note>
      Always verify the `paymentStatus` value server-side before fulfilling an order. A redirect to `success_url` alone is not sufficient confirmation; the status must be `CAPTURED`.
    </Note>
  </Step>
</Steps>

## Payment Status Reference

When Payzah redirects your customer back to your `success_url` or `error_url`, the `paymentStatus` field will contain one of the following values:

| Status           | Meaning                                                       |
| ---------------- | ------------------------------------------------------------- |
| `CAPTURED`       | Payment was authorised and funds captured successfully        |
| `VOIDED`         | A previously authorised transaction was voided before capture |
| `NOT CAPTURED`   | Authorisation was approved but capture did not complete       |
| `CANCELED`       | The customer cancelled the payment on the provider's page     |
| `DENIED BY RISK` | The transaction was blocked by risk management rules          |
| `HOST TIMEOUT`   | The payment gateway did not respond in time; treat as unknown |

<Warning>
  If you receive a `HOST TIMEOUT` status, do not automatically mark the order as failed. Query your records against the `payzahReferenceCode` or `transactionNumber` to confirm the actual outcome before taking action.
</Warning>