Webhooks

This endpoint listens for incoming webhook events from external systems or services.
It is used to receive transaction status updates related to payment requests initiated by merchants.

When a transaction is processed, the external system sends one or more webhook notifications to the Server URL that was provided when creating the payment request.

📬 Using Webhooks

Webhooks are delivered via HTTP POST requests containing a JSON payload.
Each payload includes details about the transaction and its current status.

🧱 Payload Structure

Field	Required	Description
`transactionid`	✅	Unique identifier for the transaction (assigned by the gateway).
`trackid`	✅	Merchant’s own transaction reference ID.
`result`	✅	Status of the transaction (`Processing`, `Successful`, or `Not Successful`).
`responsecode`	✅	Code indicating the outcome (e.g., `0` = success).
`transactiondate`	✅	Date and time of the event (ISO or UTC format).
`currencycode`	✅	Transaction currency (e.g., `PHP`).
`amount`	✅	Transaction amount.
`cardtype`	✅	Payment method (e.g., `PHQR`).
`action`	✅	Always `"PURCHASE"` for the new flow.
`merchantcode`	✅	Merchant code assigned by the gateway.
`responsedescription`	✅	Descriptive message of the transaction result.
Other fields		Additional metadata (e.g., `cardholder`, `descriptor`, `extendedresponse`, etc.).

⚙️ Callback Flow

In the new PURCHASE flow, there are two webhook callbacks per transaction:

1️⃣ QR Success — Transaction Initiated

This is sent when the QR code has been successfully scanned and payment initiation is detected.
The transaction is still in progress at this stage.

{
  "transactionid": "2220083",
  "transactiondate": "2025-10-10 13:00:28Z",
  "cardholder": "INSTAPAY",
  "merchantcustomerid": null,
  "trackid": "supporttest",
  "currencycode": "PHP",
  "amount": "200.00",
  "card": "200000xxxxxx0008",
  "exp_year": "00",
  "exp_month": "12",
  "cardtype": "PHQR",
  "action": "PURCHASE",
  "result": "Processing",
  "authcode": "",
  "responsecode": "9",
  "error_code_tag": "",
  "udf1": null,
  "udf2": null,
  "udf3": null,
  "udf4": null,
  "udf5": null,
  "avs": "",
  "extendedresponse": "GET Deeplink - True-00-Success-Success",
  "descriptor": "paypay",
  "message": null,
  "merchantcode": "PAYPHQR001",
  "responsedescription": "Request in progress"
}

2️⃣ Transaction Completed — Final Status

Once the transaction is finalized, another webhook is sent indicating success or failure.

✅ Successful Example

{
  "transactionid": "2220083",
  "transactiondate": "2025-10-10 13:00:28Z",
  "cardholder": "INSTAPAY",
  "merchantcustomerid": null,
  "trackid": "supporttest",
  "currencycode": "PHP",
  "amount": "200.00",
  "card": "200000xxxxxx0008",
  "exp_year": "00",
  "exp_month": "12",
  "cardtype": "PHQR",
  "action": "PURCHASE",
  "result": "Successful",
  "authcode": "",
  "responsecode": "0",
  "error_code_tag": null,
  "udf1": null,
  "udf2": null,
  "udf3": null,
  "udf4": null,
  "udf5": null,
  "avs": "",
  "extendedresponse": "SweepForCollection - True - Success. VCN swept and closed. - ",
  "descriptor": "paypay",
  "message": null,
  "merchantcode": "PAYPHQR001",
  "responsedescription": "Approved or completed available successfully"
}

❌ Failed Example

{
  "transactionid": "2220083",
  "transactiondate": "2025-10-10 13:00:28Z",
  "cardholder": "INSTAPAY",
  "merchantcustomerid": null,
  "trackid": "supporttest",
  "currencycode": "PHP",
  "amount": "200.00",
  "card": "200000xxxxxx0008",
  "exp_year": "00",
  "exp_month": "12",
  "cardtype": "PHQR",
  "action": "PURCHASE",
  "result": "Not Successful",
  "authcode": "",
  "responsecode": "6",
  "error_code_tag": null,
  "udf1": null,
  "udf2": null,
  "udf3": null,
  "udf4": null,
  "udf5": null,
  "avs": "",
  "extendedresponse": "SweepForCollection - False",
  "descriptor": "paypay",
  "message": null,
  "merchantcode": "PAYPHQR001",
  "responsedescription": "Error transaction"
}

🧩 Merchant System Handling

Merchants should:

Listen for both callbacks (Processing → Successful/Not Successful).
Identify the transaction using the trackid or transactionid.
Update transaction status in their system accordingly:
- Processing → Awaiting confirmation
- Successful → Payment completed
- Not Successful → Payment failed