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

# Retrieve Payment Status — Payzah Payment Gateway API

> Look up the status of a transaction after the customer is redirected back to your site, using the original track ID and the Payzah Payment ID.

After Payzah redirects your customer back to your `success_url` or `error_url`, you should verify the transaction's outcome server-side before fulfilling an order or showing a confirmation screen. This endpoint lets you query a payment's current status by supplying the `trackid` you generated during initialization and the `PaymentID` that Payzah returned in the initialization response. Never rely solely on the redirect URL parameters to confirm payment — always confirm with this endpoint.

**Endpoint:** `POST /ws/paymentgateway/get-payment-details`

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>
  The unique Track ID you submitted in the original payment initialization
  request. Alphanumeric, maximum 255 characters.
</ParamField>

<ParamField body="payment_id" type="string" required>
  The Payzah Payment ID returned as `PaymentID` in the initialization response.
  Maximum 255 characters.
</ParamField>

## Sample Request

```bash cURL theme={null}
curl --request POST \
  --url https://development.payzah.net/ws/paymentgateway/get-payment-details \
  --header 'Content-Type: application/json' \
  --header "Authorization: $(echo -n 'your_private_key_here' | base64)" \
  --data '{
    "trackid": "1000",
    "payment_id": "2023020818520981564303"
  }'
```

```json Request Body theme={null}
{
  "trackid": "1000",
  "payment_id": "2023020818520981564303"
}
```

## Response Fields

### Success Response

<ResponseField name="status" type="boolean">
  `true` when a matching payment record was found.
</ResponseField>

<ResponseField name="data" type="object">
  Contains the full details of the located payment.

  <Expandable title="data fields">
    <ResponseField name="payzahRefrenceCode" type="string">
      Payzah's internal reference code for this payment — corresponds to the
      `PaymentID` from the initialization response.
    </ResponseField>

    <ResponseField name="trackId" type="string">
      The Track ID you submitted during payment initialization.
    </ResponseField>

    <ResponseField name="UDF1" type="string">
      Value of user-defined field 1 as submitted during initialization. Empty
      string if not provided.
    </ResponseField>

    <ResponseField name="UDF2" type="string">
      Value of user-defined field 2. Empty string if not provided.
    </ResponseField>

    <ResponseField name="UDF3" type="string">
      Value of user-defined field 3. Empty string if not provided.
    </ResponseField>

    <ResponseField name="UDF4" type="string">
      Value of user-defined field 4. Empty string if not provided.
    </ResponseField>

    <ResponseField name="UDF5" type="string">
      Value of user-defined field 5. Empty string if not provided.
    </ResponseField>

    <ResponseField name="knetPaymentId" type="string">
      The payment ID assigned by the K-Net network for this transaction.
    </ResponseField>

    <ResponseField name="paymentId" type="string">
      The payment ID assigned by the payment processor. For K-Net transactions
      this matches `knetPaymentId`.
    </ResponseField>

    <ResponseField name="transactionNumber" type="string">
      The unique transaction number generated by the payment network.
    </ResponseField>

    <ResponseField name="trackingNumber" type="string">
      The tracking number assigned by the payment network, used for
      reconciliation with your bank or processor.
    </ResponseField>

    <ResponseField name="paymentDate" type="string">
      The date and time the payment was processed, in `YYYY-MM-DD HH MM SS`
      format.
    </ResponseField>

    <ResponseField name="paymentStatus" type="string">
      The current status of the payment. See the table below for all possible
      values and their meanings.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Response

<ResponseField name="status" type="boolean">
  `false` when no matching record was found or an error occurred.
</ResponseField>

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

<ResponseField name="code" type="number">
  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": {
    "payzahRefrenceCode": "2023020818520981564303",
    "trackId": "1000",
    "UDF1": "",
    "UDF2": "",
    "UDF3": "",
    "UDF4": "",
    "UDF5": "",
    "knetPaymentId": "100202303935749373",
    "paymentId": "100202303935749373",
    "transactionNumber": "202303935759799",
    "trackingNumber": "12992052519157",
    "paymentDate": "2023-02-08 18 52 09",
    "paymentStatus": "NOT CAPTURED"
  }
}
```

```json Error theme={null}
{
  "status": false,
  "message": "No Record found for the provided details",
  "code": 10012
}
```

## Payment Status Values

The `paymentStatus` field in the success response will contain one of the following values:

| Status           | Description                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CAPTURED`       | The payment was successfully authorized and captured. Funds are secured and will be settled to your account.                                                             |
| `NOT CAPTURED`   | The payment was authorized but capture has not yet occurred. You may need to initiate capture separately depending on your account configuration.                        |
| `VOIDED`         | The payment was voided or cancelled after authorization. No funds were captured.                                                                                         |
| `CANCELED`       | The customer cancelled the payment before completion.                                                                                                                    |
| `DENIED BY RISK` | The payment was blocked by Payzah's risk management system. No funds were collected.                                                                                     |
| `HOST TIMEOUT`   | The payment host did not respond in time. The transaction outcome is uncertain — contact Payzah support or check your bank portal to confirm the result before retrying. |