Payload

Overview

When a QR Ph transaction reaches a terminal state, Modulus delivers a webhook to the callbackUrl you registered. The delivery is an HTTPS POST with an encrypted body. You decrypt it with your Encryption Key to read the transaction details.

Delivery request

POST {your callbackUrl}
Content-Type: application/json
Activation-Code: {your activation code}

{ "Token": "<compact JWE>" }

The body is { "Token": "<JWE>" }. The Token is a compact JWE.
The Activation-Code header identifies which of your sub-merchant accounts the event belongs to.
Decrypt Token with your Encryption Key (alg A256KW, enc A256CBC-HS512), the same key used elsewhere in the QR Ph API. See Encryption & JWE Tokens for the decryption code.

There is no separate signature header. The JWE’s authenticated encryption protects integrity, but it does not prove freshness, so deduplicate as described below.

Decrypted payload

Field	Type	Description
`transactionId`	string	Modulus transaction number for this payment.
`transactionStatus`	string	One of `PENDING`, `REQUIRES_ACTION`, `SUCCESS`, `FAILED`.
`transactionType`	string	The transaction entry type.
`cardType`	string	The instrument type used, for example `QR_PH`.
`merchantReferenceNumber`	string	The reference you supplied when creating the QR (`merchantReferenceNumber`). Use this to match the payment to your order.
`amountDetails`	object	`{ amountPaid: { currency, value }, amountReceived: { currency, value } }`. Amounts are decimal strings.
`timeDetails`	object	`{ createdAt, updatedAt? }` timestamps.
`merchantDetails`	object	`{ merchantName, terminalName }`.
`webhookAction`	string (optional)	`QRPH_SUCCESS` or `QRPH_DECLINED`.
`receipt`	object (optional)	Present on successful payments: `{ receiptNumber, transactionId, authNumber, batchNumber }`. Note `receipt.transactionId` carries your merchant reference (`merchantReferenceNumber`), not the top-level Modulus `transactionId`.
`cancellationReason`	string (optional)	Present when the payment was cancelled.
`failedReason`	string (optional)	Present when the payment failed.

The webhook does not carry a referenceNumber that echoes your QR request. Correlate on merchantReferenceNumber. A referenceNumber only appears in error responses, where it is a newly generated support id unrelated to your reference.

Example (decrypted)

{
  "transactionId": "0ce32626-08cf-405c-adab-6d384a8871da",
  "transactionStatus": "SUCCESS",
  "transactionType": "QR_PH",
  "cardType": "QR_PH",
  "merchantReferenceNumber": "ORDER-2026-001",
  "amountDetails": {
    "amountPaid": { "currency": "PHP", "value": "1500.00" },
    "amountReceived": { "currency": "PHP", "value": "1500.00" }
  },
  "timeDetails": {
    "createdAt": "2026-01-29T10:30:00Z",
    "updatedAt": "2026-01-29T10:30:05Z"
  },
  "merchantDetails": { "merchantName": "Main Store", "terminalName": "Terminal 1" },
  "webhookAction": "QRPH_SUCCESS",
  "receipt": {
    "receiptNumber": "RCP-000123",
    "transactionId": "ORDER-2026-001",
    "authNumber": "A1B2C3",
    "batchNumber": "045"
  }
}

Acknowledging and retries

Return 200 or 201 to acknowledge. Only 200 and 201 acknowledge; a 202 or 204 does not. If your endpoint does not respond with 200 or 201, Modulus retries the same delivery up to 3 more times, about 15 minutes apart (4 attempts total).

Idempotency

There is no unique delivery or event id in the payload; retries reuse the same encrypted body. Deduplicate on the pair:

(transactionId, webhookAction)

Every attempt for the same event shares both values. See Receiving Webhooks for the acknowledge-then-process pattern.

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

Overview

Delivery request

Decrypted payload

Example (decrypted)

Acknowledging and retries

Idempotency

​Overview

​Delivery request

​Decrypted payload

​Example (decrypted)

​Acknowledging and retries

​Idempotency

Overview

Delivery request

Decrypted payload

Example (decrypted)

Acknowledging and retries

Idempotency