Skip to main content

​
Overview

Webhooks let Modulus notify your server the moment a QR Ph transaction reaches a terminal state, so you do not have to poll for status. Each delivery is an encrypted POST to a callback URL you register.
Webhooks are required for QR Ph. Without them you have no reliable way to learn whether a payment succeeded or failed.

Quickstart

Register a callback URL and send a test event

Receiving Webhooks

Decrypt, acknowledge, deduplicate, and process

Webhook Payload

Every field in the decrypted payload

API Reference

Manage webhooks (create, list, update, delete, simulate)

​
API Endpoint

Sandbox base URL:
Authenticate management calls with HTTP Basic auth using your Secret Key (same scheme as the QR API). See Authentication.

​
How it works

1

Register a callback URL

Register your HTTPS endpoint and the action you want with the management API. One webhook fires on one action.
2

A customer pays

The customer scans your Dynamic QR Ph and completes payment in their bank app.
3

Modulus delivers the event

Modulus POSTs an encrypted { "Token": "<JWE>" } to your callback URL, with an Activation-Code header for the sub-merchant.
4

You decrypt and process

Decrypt with your Encryption Key, deduplicate on (transactionId, webhookAction), return 200/201, then process. If you do not acknowledge, Modulus retries up to 3 more times about 15 minutes apart (4 attempts total). See Receiving Webhooks.

​
Events

Register the action you need - one webhook per action, or one each to receive both.