Skip to main content
A well-built payment integration is more than just working code — it is a foundation of trust between you, your customers, and your payment provider. Following the practices below helps you resolve disputes quickly, prevent fraud, maintain audit trails, and ensure your integration holds up reliably in production. Work through each item before you go live and revisit them periodically as your platform evolves.
Your private API key grants full access to your Payzah account. Never commit it to source control, expose it in client-side code, or share it in logs. If your key is ever compromised, contact Payzah immediately at [email protected] or +965 22410760 to rotate it before any unauthorized transactions can occur.

​
Best Practices

Comprehensive logging is your first line of defense when investigating a failed transaction or resolving a customer dispute. You should log:
  • All request parameters before they are assigned or sent, so you can catch data-formatting bugs early.
  • Every request your server sends to Payzah, including headers, payload, and timestamp.
  • Every response received from Payzah, including HTTP status codes and full response bodies.
Structured logging (e.g., JSON lines) makes it far easier to query and correlate events across a transaction’s lifecycle.
Never skip User Acceptance Testing before moving to production. Your UAT suite should exercise every integration point, including:
  • Successful payment flows for each supported payment method (K-Net, Visa, MasterCard).
  • Declined and expired card scenarios.
  • Cancelled or abandoned sessions.
  • Payment status-check polling, including edge cases where a status is not immediately available.
Only promote your integration to the production endpoints after every UAT scenario passes consistently. See Test Credentials for the sandbox cards and URLs you need.
Transaction logs contain sensitive financial data and must be protected accordingly. Store logs in an access-controlled system with encryption at rest. Retain them for a period that satisfies your local regulatory requirements and internal audit policies. Secure logs are invaluable during chargeback disputes — they provide a timestamped, tamper-evident record of exactly what was sent and received.
Always pass the customer’s IP address in your payment requests. Payzah uses this information for fraud detection and provides richer tracking data in your transaction reports. Capturing the IP at the point of checkout (rather than using your server’s IP) ensures the data is meaningful and accurate.
Every transaction you initiate must have a unique trackid. Reusing a track ID across multiple transactions can cause look-up collisions and make it impossible to reliably map a Payzah response back to the correct order in your system. Generate track IDs using a UUID or a similarly collision-resistant method, and store the mapping between your internal order ID and the trackid in your database.
The trackid and all User-Defined Fields (UDFs) must contain only alphanumeric characters. Special characters (e.g., &, =, #, spaces) can break URL encoding or cause request parsing failures on the Payzah gateway. Validate and sanitize these fields before every request, and enforce the constraint at the input layer so invalid values never reach your payment code.
If your private key is ever exposed — whether through a repository leak, an accidental log entry, or a security incident — treat it as compromised immediately. Do not wait to confirm misuse before acting. Contact Payzah at [email protected] or call +965 22410760 to request an immediate key rotation. Update all environments with the new key and audit your logs for any unauthorized activity during the window of exposure.
Your test and production API keys must never be mixed. Using a test key in production will cause all live transactions to fail; using a production key in your test environment risks accidental real charges. Store each key in environment-specific configuration (e.g., .env.test and .env.production) and use your deployment pipeline to inject the correct value per environment automatically. Periodically audit your configuration to confirm no cross-environment key usage exists.