Troubleshoot Your Payzah Integration: Errors and Fixes

Most integration problems fall into a small number of recurring patterns. This page is organised by symptom — start with what you are seeing, then follow the fix. For the complete list of codes, see the Response Codes reference.

Before troubleshooting anything, confirm you are hitting the environment you think you are. Pointing test credentials at production endpoints — or the reverse — is the single most common cause of unexplained failures.

Diagnose by Symptom

Authentication and Setup

Symptom	Likely cause	Fix
Every request returns code `10014`	Private key is not Base64-encoded, or has trailing whitespace	Encode with `base64_encode($privateKey)`. Trim the key string — a stray newline from a copied `.env` value will break it
Requests worked in test, fail in production	Using the test key against production endpoints	Test and production keys are different. Store both, select by environment
Code `10013` on every call	Body is being sent as form data, not JSON	Set `Content-Type: application/json` and serialise the body with `json_encode` / `JSON.stringify`
Code `10015` when using `payment_type=2`	Account not enabled for direct Credit Card	Use `payment_type=3` (transit page, includes cards) or contact Payzah support to enable the permission

Payment Initialization

Symptom	Likely cause	Fix
Code `10001`	`trackid` contains special characters	Use alphanumeric only. Strip hyphens, slashes, and spaces if your order IDs contain them
Code `10002` or `10004`	`trackid` or `amount` missing	Check field names are lowercase and exactly as documented. A typo silently becomes a missing field
Code `10003`	`amount` is malformed	Send a plain decimal string, e.g. `"11.250"`. No currency symbols, commas, or spaces
Code `10005` / `10006`	`success_url` or `error_url` missing	Both are mandatory on every initialization request, even if they point to the same handler
Codes `10007`–`10011`	A `udf1`–`udf5` field contains special characters	Sanitise UDF values before sending. These fields are alphanumeric only
`transit_url` is empty	You sent `payment_type` `1` or `2`	Direct integration populates `direct_url` instead. Read the correct field for your `payment_type`
`direct_url` is empty	You sent `payment_type` `3`	Transit integration populates `transit_url`. See the comparison table

Status Checks and Refunds

Symptom	Likely cause	Fix
Code `10012` on status check	`trackid` and `payment_id` do not match a real transaction	Both must come from the same transaction. `payment_id` is the `PaymentID` from the initialization response, not your own order ID
Code `10012` on refund	`trackid` and `refrence_code` do not match a successful payment	Confirm the original transaction is `CAPTURED` first. Refunds against voided or uncaptured payments will not be found
Refund returns `status: false` but HTTP 200	Treating the HTTP status as the result	Always read the `status` field. A `200` with `status: false` means nothing was refunded
Refund rejected with a valid reference	Field name misspelled as `reference_code`	The field is `refrence_code` — note the spelling
Customer charged but your order never updated	Customer closed the tab before the redirect fired	Do not rely on the redirect alone. Poll the status endpoint for any order left pending

What to Do for Each Payment Status

A redirect to your success_url does not confirm payment. Always read paymentStatus and act accordingly.

Status	Fulfil the order?	Action
`CAPTURED`	Yes	Funds are secured. Fulfil and mark the order paid
`NOT CAPTURED`	No	Authorised but not captured. Investigate before acting — do not ship
`VOIDED`	No	No funds were taken. Notify the customer and allow a retry
`CANCELED`	No	Customer abandoned checkout. Allow a retry; no action needed
`DENIED BY RISK`	No	Blocked by risk controls. Do not retry automatically — direct the customer to support
`HOST TIMEOUT`	No	Outcome unknown. Hold the order and confirm manually before refunding or fulfilling

HOST TIMEOUT is the most dangerous status to mishandle. Never auto-refund and never auto-fulfil on a timeout — confirm the real outcome in your processor portal or with Payzah support first.

Still Stuck?

When contacting Payzah support, include the following so the issue can be traced without reproducing it:

The trackid and PaymentID for the affected transaction
The full raw response body, including the code and message fields
The environment (test or production) and the exact endpoint URL you called
The approximate timestamp of the request

Never include your private key, card numbers, or customer payment details in a support ticket. Payzah will never ask for your private key.

Get Started

Plugins & Platforms

Custom Integration Guide

Testing & Go-Live

Resources

Troubleshoot Your Payzah Integration: Errors and Fixes

Diagnose by Symptom

Authentication and Setup

Payment Initialization

Status Checks and Refunds

What to Do for Each Payment Status

Still Stuck?

​Diagnose by Symptom

​Authentication and Setup

​Payment Initialization

​Status Checks and Refunds

​What to Do for Each Payment Status

​Still Stuck?

Diagnose by Symptom

Authentication and Setup

Payment Initialization

Status Checks and Refunds

What to Do for Each Payment Status

Still Stuck?