Retrieve Payment Status — Payzah Payment Gateway API

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 for the base URLs and required authentication headers before making this request.

Request Parameters

string

required

The unique Track ID you submitted in the original payment initialization request. Alphanumeric, maximum 255 characters.

string

required

The Payzah Payment ID returned as PaymentID in the initialization response. Maximum 255 characters.

Sample Request

cURL

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"
  }'

Request Body

{
  "trackid": "1000",
  "payment_id": "2023020818520981564303"
}

Response Fields

Success Response

boolean

true when a matching payment record was found.

object

Contains the full details of the located payment.

Show data fields

string

Payzah’s internal reference code for this payment — corresponds to the PaymentID from the initialization response.

string

The Track ID you submitted during payment initialization.

string

Value of user-defined field 1 as submitted during initialization. Empty string if not provided.

string

Value of user-defined field 2. Empty string if not provided.

string

Value of user-defined field 3. Empty string if not provided.

string

Value of user-defined field 4. Empty string if not provided.

string

Value of user-defined field 5. Empty string if not provided.

string

The payment ID assigned by the K-Net network for this transaction.

string

The payment ID assigned by the payment processor. For K-Net transactions this matches knetPaymentId.

string

The unique transaction number generated by the payment network.

string

The tracking number assigned by the payment network, used for reconciliation with your bank or processor.

string

The date and time the payment was processed, in YYYY-MM-DD HH MM SS format.

string

The current status of the payment. See the table below for all possible values and their meanings.

Error Response

boolean

false when no matching record was found or an error occurred.

string

A human-readable description of the error.

number

A numeric error code. See the Response Codes reference for the full list.

Sample Responses

Success

{
  "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"
  }
}

Error

{
  "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.

Try It Live

Payment Initialization

Payment Status

Retrieve Payment Status — Payzah Payment Gateway API

Request Parameters

Sample Request

Response Fields

Success Response

Error Response

Sample Responses

Payment Status Values

​Request Parameters

​Sample Request

​Response Fields

​Success Response

​Error Response

​Sample Responses

​Payment Status Values

Request Parameters

Sample Request

Response Fields

Success Response

Error Response

Sample Responses

Payment Status Values