Skip to main content
POST

Overview

The Simulate Webhook endpoint allows you to test your webhook integration without creating real QR codes or processing actual transactions. It sends encrypted webhook notifications to your registered endpoint, exactly like real transaction webhooks.
Sandbox Only: This endpoint is only available in the sandbox environment for testing purposes. It’s not available in production.
The simulated webhook payloads sent to your endpoint are JWE-encrypted, identical to real transaction webhooks. See the Encryption Guide to understand how to decrypt incoming notifications.

Endpoint

Authentication

This endpoint requires HTTP Basic Authentication using your Secret Key.

Request

Headers

Body Parameters (Encrypted Payload)

The following parameters describe the payload that must be JWE-encrypted into the Token field. See the Encryption Guide for details on creating JWE tokens.
The raw QRPH payload used to simulate a transaction.
  • Example: "00020101021228820011ph.ppmi.p2m0111CUOBPHM2XXX03258eff02de-e172-4b0d-bc5b-3041288500100000705033015204601653036085406100.005802PH5912MAIN ACCOUNT6006MANILA630412C0"
The type of transaction event to simulate:
  • SUCCESS - Simulates a successful payment
  • MISSING_DESTINATION_ACCOUNT - Simulates a declined payment (missing destination account)
  • MISSING_PARTNER_REVENUE_ACCOUNT - Simulates a declined payment (missing partner revenue account)
  • UNSUPPORTED_TRANSFER_TYPE - Simulates a declined payment (unsupported transfer type)
Example: "SUCCESS"

Example Payloads (Before Encryption)

Response

Success Response

Status Code: 200 OK Returns confirmation that the simulated webhook was sent to your registered endpoint.
string
The unique identifier of the original transaction (i.e., the id returned from the Create Dynamic QR Ph response).Example: "a78efd32-de3b-4854-b599-11ae9f98f97e"

Response Example

Error Responses

Status Code: 400Causes:
  • Missing useCase field
  • Invalid useCase value
Response Example:
Solution:
  • Ensure useCase is one of: SUCCESS, MISSING_DESTINATION_ACCOUNT, MISSING_PARTNER_REVENUE_ACCOUNT, or UNSUPPORTED_TRANSFER_TYPE
  • Check spelling and capitalization
Status Code: 401Cause: Invalid or missing authentication credentialsSolution:
  • Verify your secret key is correct
  • Ensure Authorization header format: Basic {base64(secret_key:)}
Status Code: 404Cause: No enabled webhooks configuredResponse Example:
Solution:
  • Create at least one webhook using Create Webhook API
  • Ensure webhook status is ENABLED
  • Verify webhook actions include the simulated event type
Status Code: 500Cause: Unexpected server errorSolution:
  • Retry the request
  • If the issue persists, contact Modulus Labs support

Testing Workflow

1

Register Webhook

Create a webhook endpoint pointing to your test server:
2

Simulate Success Event

Send a successful payment webhook:
Check your webhook endpoint receives and processes the notification correctly.
3

Simulate Declined Event

Send a declined payment webhook:
Verify your endpoint handles payment failures gracefully.
4

Test Error Scenarios

Test your webhook error handling:
  • Return 5xx status to trigger retries
  • Delay response beyond 10 seconds to test timeouts
  • Verify idempotency by sending duplicate webhooks
5

Verify Decryption

Confirm your endpoint can decrypt JWE payloads successfully using your secret key.

Use Cases

Test your webhook handler during development:
Include webhook simulation in your test suite:
Test your JWE decryption logic:
Verify your webhook handler manages errors gracefully:
Demonstrate webhook functionality without real transactions:

Testing Checklist

1

Setup

  • Webhook endpoint is accessible
  • Webhook is registered and enabled
  • Webhook actions include QRPH_SUCCESS and QRPH_DECLINED
2

Test Successful Payment

  • Simulate SUCCESS webhook
  • Webhook received at endpoint
  • JWE payload decrypted successfully
  • Order marked as paid
  • Confirmation email sent
3

Test Declined Payment

  • Simulate declined webhook (e.g., MISSING_DESTINATION_ACCOUNT)
  • Webhook received at endpoint
  • Decline reason parsed correctly
  • Order marked as failed
  • Customer notified
4

Test Error Handling

  • Duplicate webhooks ignored (idempotency)
  • Invalid webhooks rejected
  • Timeout scenarios handled
  • Retry mechanism tested
5

Verify Logging

  • All webhooks logged
  • Processing results recorded
  • Errors captured

Best Practices

Test Both Scenarios

Always test both success and decline webhooks:

Use in CI/CD

Automate webhook testing in your deployment pipeline:

Monitor Test Results

Track webhook simulation outcomes:

Test with Delays

Allow time for webhook processing between tests:

Differences from Real Webhooks

Simulated webhooks behave identically to real webhooks except for the data content. Your webhook handler should process them the same way.

Troubleshooting

Symptom: Receive 404 error when calling Simulate APIPossible Causes:
  • No webhooks registered
  • All webhooks are disabled
  • Webhook actions don’t include the simulated event
Solutions:
Symptom: Simulate API returns success but webhook not receivedPossible Causes:
  • Webhook URL not accessible
  • Firewall blocking requests
  • Endpoint not listening
Solutions:
  • Test webhook URL accessibility externally
  • Check server logs for incoming requests
  • Verify endpoint is running and listening
  • Test with ngrok or similar during development
Symptom: Webhook received but cannot decrypt payloadPossible Causes:
  • Wrong secret key
  • JWE library issue
  • Incorrect algorithm configuration
Solutions:
Symptom: Receive multiple webhook deliveries for one simulationCause: Multiple enabled webhooks registeredExpected Behavior: The Simulate API sends notifications to all enabled webhooks that are configured for the simulated event.Verification:

Next Steps

Create Webhook

Register a webhook to test with simulations

Receiving Webhooks

Implement webhook processing logic

Payload Structure

Understand webhook payload format

Setup Guide

Complete webhook integration guide

Authorizations

Authorization
string
header
required

HTTP Basic Authentication using your Secret Key as the username and an empty password

Body

application/json
request
object
required

Response

Webhook simulation sent successfully

id
string

The unique identifier of the original transaction (i.e., the id returned from the Create Dynamic QR Ph response).