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