Transaction Response
Understanding the response parameters returned after a payment
After the customer completes (or fails) a payment on the Hosted Payment Page, they are redirected to your response_url via a GET request. The transaction result is appended as a URL-encoded query string.
This same redirect model is reused by WAPI Trusted Card charge flows, and a close variant is used by Trusted Card create flows. See Hosted Checkout Flows.
How It Works
https://example.com/response?status=success&transaction_id=SB-12-1-oid_123-20210616024001&total=12.05&...Parse the query string parameters on your response_url endpoint to determine the result and handle your application logic accordingly.
The redirect to response_url is the end of the hosted transaction lifecycle. The earlier Payment Request response only creates the checkout session; it does not confirm settlement. In some cases, WiPay may spend additional time reconciling an incomplete, pending, or expired checkout before issuing the final redirect. See Hosted Checkout Flows for the shared lifecycle.
Response Parameters
| Parameter | Description |
|---|---|
card | (Conditionally absent) Masked card reference. When present, it follows the branded masked format (VISA) ... 1234, exposing only the last 4 digits. |
currency | Customer-facing transaction currency returned in the response. It usually matches the original request, but WiPay can adjust it from processed transaction data when conversion or settlement rules apply. |
customer_address | (Conditionally absent) Customer address captured from the hosted flow or request data, usually in the format addr1, addr2, city, state zipcode, country. Most common on AVS-enabled transactions. |
customer_company | (Conditionally absent) Customer company value when available from the request or application-specific integration data. |
customer_email | (Conditionally absent) Customer email captured from the hosted flow or supplied in the original request. |
customer_name | Customer name captured from the hosted flow or request data. If no name is available, WiPay can fall back to a generic payment label such as CreditCard Payment. |
customer_phone | (Conditionally absent) Customer phone number captured from the hosted flow or request data. For AVS-enabled transactions, it may be normalized toward E.164. |
data | The original data submitted in the request. Note: WiPay's security modules may have altered or omitted this value. |
date | RFC 3339 date and time: YYYY-MM-DD hh:mm:ss (24-hour format). |
hash | (Conditionally absent) Response hash used for successful-transaction verification. Only present for status=success transactions. See Response Hash Verification below. |
message | Transaction summary in the format [<A>-R<B>]: <C>. See Message Format below. |
order_id | The order_id from the original request. Unchanged between request and response. |
status | Transaction result: success, failed, or error. |
total | Customer-facing total returned in the response. It usually reflects the original requested transaction context with the selected fee_structure, but WiPay can adjust it from processed transaction data when conversion or settlement rules apply. Do not use this field as the input for response-hash verification; use the original total you submitted in the request. |
transaction_id | WiPay's unique transaction identifier. See Transaction ID Format below. |
Response Hash Verification
The hash parameter allows you to verify the authenticity of a successful transaction. It is currently calculated as:
hash = md5(transaction_id + original_total + api_key)Where:
transaction_id— the WiPay transaction ID from the responseoriginal_total— the original transaction total supplied by the requester in the API request, formatted to exactly 2 decimal places (e.g.,10.00). Do not use the customer-facingtotalvalue returned in the response parameters.api_key— your WiPay account's API Key. Please do not expose your API Key in the public domain.
Critical:
- The
hashis only returned forstatus=successtransactions. - You must always re-calculate and compare the
hashon your server before fulfilling any order. - Since the Payments API request endpoint does not require authentication, response-hash verification is the essential security control that prevents spoofed payment confirmations.
- Your
api_keymust remain secret and must never be exposed in client-side code, browser-rendered markup, mobile app bundles, or any other public context. - If a malicious third party obtains the
api_key, they can generate matching hashes for forged payment responses, which makes the hash check effectively useless.
As an additional layer of security, you can also use the WAPI Transaction Retrieve endpoint to verify the transaction status directly with WiPay. This should complement the server-side response-hash check, not replace it.
Message Format
The message parameter commonly follows the format [<A>-R<B>]: <C>, but the exact values depend on the hosted checkout configuration behind the transaction.
| Component | Description |
|---|---|
<A> Approval or response code | Often a numeric status such as 1, 2, or 3, or an alphabetic status such as Y or N |
<B> Reason or processor response code | Numeric code that identifies the outcome in more detail |
<C> Reason description | Short description of the transaction result |
Some hosted checkout configurations do not expose AVS response details.
Transaction ID Format
The transaction_id commonly follows the format <1><2>-<3>-<4>-<5>.
| Component | Description |
|---|---|
<1> | SB- prefix for environment=sandbox transactions. Omitted for environment=live transactions. |
<2> | Random number between 1 and 99. |
<3> | Merchant's WiPay User ID. |
<4> | The order_id from the original request. |
<5> | Datetime string in YYYYMMDDhhmmss format. Note: hh is in 24-hour format. |
Example: SB-12-1-oid_123-aBc-20210616024001
Examples
Successful AVS Transaction
A TT platform transaction for 10.00 USD with customer_pay fee structure and AVS enabled:
| Parameter | Value |
|---|---|
card | (VISA) ... 1234 |
currency | USD |
customer_address | #1234 Crossbay Court, Westmoorings, Port Of Spain, Trinidad and Tobago |
customer_email | john.doe@example.com |
customer_name | John Doe |
customer_phone | 12462223333 |
data | "test" |
date | 2025-06-16 02:41:52 |
hash | 3d34d20260f7433ceee277e9ed9166a3 |
message | [1-R00]: Approved or completed successfully. |
order_id | oid_123-aBc |
status | success |
total | 12.05 |
transaction_id | SB-12-1-oid_123-aBc-20250616024001 |
Failed Transaction
A TT platform transaction for 10.00 USD with merchant_absorb fee structure. Invalid CVV provided:
| Parameter | Value |
|---|---|
card | (VISA) ... 1234 |
currency | USD |
customer_name | Forus Byus |
data | {"a":"b","c":"d"} |
date | 2025-06-16 15:58:54 |
message | [2-R211]: CVN is invalid. |
order_id | oid_123-aBc |
status | failed |
total | 10.00 |
transaction_id | 84-1-oid_123-aBc-20250616032823 |
Note that this failed non-AVS example does not include hash, customer_address, customer_email, or customer_phone.