Customer Initiates Checkout
Your customer browses your website or app, adds items to their cart, and fills in any required details. At checkout, they select Payzah as their payment method and click the pay button.
You Send a Payment Initialization Request
After your customer clicks pay, your server collects the necessary payment details and sends a
Required headers
Your request body must include the transaction amount, a unique
POST request to Payzah’s initialization endpoint. This step is the same whether you are using Transit or Direct Integration.Endpoints| Environment | URL |
|---|---|
| Test | https://development.payzah.net/ws/paymentgateway/index |
| Production | https://payzah.net/production770/ws/paymentgateway/index |
| Header | Value |
|---|---|
Content-Type | application/json |
Authorization | Your private key, Base64-encoded |
trackid, your success_url, your error_url, the currency code, and the payment_type that matches your integration method.Payzah Processes Your Request
Payzah validates your request and responds in one of two ways:Successful response — Payzah issues an approval and returns a JSON object containing a
PaymentID and redirect URLs (transit_url or direct_url depending on your payment_type).Rejected response — Payzah returns an error message and error code. Common reasons include an invalid private key, a missing required field, or a duplicate trackid.Your
trackid must be unique per transaction. Reusing a trackid from a previous request will cause the initialization to be rejected.You Redirect Your Customer
Once you receive a successful initialization response, immediately redirect your customer to the appropriate payment URL from the response body.The redirect destination depends on your integration type:
| Integration | Redirect destination |
|---|---|
| Transit Payment Page | Payzah’s branded hosted page, which then routes to the customer’s chosen provider (K-Net, Credit Card, or Apple Pay) |
| Direct Integration | The payment provider’s page directly (K-Net or Credit Card), skipping the Payzah-hosted intermediate page |
Payzah Returns the Transaction Result
After the customer completes (or abandons) payment on the provider’s page, Payzah processes the final transaction result and redirects your customer back to your site.
- Success → customer is redirected to your
success_urlwith transaction details appended as query parameters - Failure or cancellation → customer is redirected to your
error_urlwith an error status
success_url and error_url endpoints, read and store the returned parameters — including payzahReferenceCode, paymentStatus, and transactionNumber — to update your order records accordingly.Always verify the
paymentStatus value server-side before fulfilling an order. A redirect to success_url alone is not sufficient confirmation; the status must be CAPTURED.Payment Status Reference
When Payzah redirects your customer back to yoursuccess_url or error_url, the paymentStatus field will contain one of the following values:
| Status | Meaning |
|---|---|
CAPTURED | Payment was authorised and funds captured successfully |
VOIDED | A previously authorised transaction was voided before capture |
NOT CAPTURED | Authorisation was approved but capture did not complete |
CANCELED | The customer cancelled the payment on the provider’s page |
DENIED BY RISK | The transaction was blocked by risk management rules |
HOST TIMEOUT | The payment gateway did not respond in time; treat as unknown |