Payzah API Error Codes and Payment Status Reference

When a Payzah API request fails, the response includes a status: false flag alongside a code field and a human-readable message. Understanding these codes lets you build precise error handling — surfacing the right message to the customer, triggering the right fallback in your system, and knowing when to call support. Below you will find a complete listing of all error codes and all possible payment status values.

Log the raw code and message values from every failed API response in your server-side logs. When debugging integration issues, these codes allow Payzah support to pinpoint the problem quickly without needing to reproduce the request.

Error Codes

The following error codes may appear in the code field of any error response.

Code	Description
`10000`	A general error occurred while performing the action. Retry the request; if the problem persists, contact Payzah support.
`10001`	The `trackid` value contains invalid characters or is otherwise malformed. Ensure it is alphanumeric with no special characters.
`10002`	The `trackid` field is missing from the request body.
`10003`	The `amount` value is improperly formatted. Ensure it is a plain decimal number with no symbols or commas.
`10004`	The `amount` field is missing from the request body.
`10005`	The `success_url` field is missing from the request body.
`10006`	The `error_url` field is missing from the request body.
`10007`	The `udf1` value contains invalid characters. Remove any special characters.
`10008`	The `udf2` value contains invalid characters. Remove any special characters.
`10009`	The `udf3` value contains invalid characters. Remove any special characters.
`10010`	The `udf4` value contains invalid characters. Remove any special characters.
`10011`	The `udf5` value contains invalid characters. Remove any special characters.
`10012`	No payment record was found for the `trackid` and `payment_id` combination provided to the status check endpoint. Verify both values match the original initialization request and response.
`10013`	The request body is empty or missing. Ensure you are sending a valid JSON body with `Content-Type: application/json`.
`10014`	The `Authorization` header contains an invalid token. Verify you are Base64-encoding your private key correctly and that the key itself is valid.
`10015`	Your account does not have permission to use Credit Card direct integration (`payment_type=2`). Contact Payzah support to enable this feature.

Handling the Most Common Errors

Certain error codes come up frequently during integration. Here is how to address each one: 10014 — Invalid token This means the Authorization header value does not match a valid account key. Double-check that you are Base64-encoding the key correctly and that you are using the right key for the environment (test vs. production). In PHP, use base64_encode($privateKey) with no extra whitespace in the key string. 10015 — No credit card permission Your account is not enabled for direct Credit Card payments. Either switch to payment_type=1 (K-Net) or payment_type=3 (transit, which includes credit card on the hosted page), or contact Payzah support to request the credit card permission for your account. 10002 — Missing Track ID and 10004 — Missing amount These validation errors mean a required field was not included in the request body. Review your request construction to confirm that trackid and amount are always present and correctly named (lowercase, no extra characters). 10013 — Post data missing Your request body did not reach the API or arrived empty. Confirm that your HTTP client is setting Content-Type: application/json and is serializing the body as a JSON string, not as form data.

Payment Status Values

The paymentStatus field returned by the Payment Status endpoint 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 not yet captured. Depending on your account settings, capture may need to be triggered separately.
`VOIDED`	The payment was voided or cancelled after authorization. No funds were captured and none will be settled.
`CANCELED`	The customer cancelled the payment before it was completed.
`DENIED BY RISK`	Payzah’s risk management system blocked this payment. No funds were collected. Do not retry automatically — investigate before attempting a new transaction.
`HOST TIMEOUT`	The payment host did not respond within the allowed time. The final outcome is uncertain. Check your bank or processor portal to confirm whether funds were collected before taking any action.

Try It Live

Payment Initialization

Payment Status

Payzah API Error Codes and Payment Status Reference

Error Codes

Handling the Most Common Errors

Payment Status Values

​Error Codes

​Handling the Most Common Errors

​Payment Status Values

Error Codes

Handling the Most Common Errors

Payment Status Values