Skip to main content
POST
How it works: Generate a unique QR code → Customer scans with banking app → Payment completed → Webhook notification sent

Authentication

This endpoint requires HTTP Basic Authentication using your Secret Key.

Encrypted Payload Structure

The Token field must contain a JWE-encrypted JSON payload with the following fields:
Activation Code assigned to your sub-merchant account by Modulus Labs.
  • Format: XXXX-XXXX-XXXX-XXXX (19 characters including hyphens)
  • Example: A9X4-B7P2-Q6Z8-M3L5
ISO 4217 currency code.
  • Length: Exactly 3 characters
  • Supported: PHP
  • Example: PHP
Payment amount in decimal format.
  • Min: 1.00 (₱1.00)
  • Max: 99999.99 (₱99,999.99)
  • Format: String with exactly 2 decimal places
  • Example: "500.00", "1234.56"
Pass amount as a string, not a number, to preserve decimal precision.
Your unique reference number for this transaction.
  • Min Length: 1 character
  • Max Length: 36 characters
  • Allowed: Alphanumeric characters and hyphens
  • Example: "ORDER-12345", "5e91bc6c-f7e2-4a39-ae0e-5e93985c94a4"
Use UUIDs for guaranteed uniqueness across transactions.

Example Payload (Before Encryption)

Decrypted Response

When you decrypt the response Token, you’ll get:

Using the QR Code

After receiving the qrBody, you need to convert it to an image that customers can scan:

Display in Web Application

Save as File

Best Practices

Use UUIDs

Use UUIDs for merchantReferenceNumber to ensure uniqueness

Validate Amount

Validate amount format and range before sending to API

Handle Errors

Implement proper error handling for all possible scenarios

Store Transaction ID

Save the returned id for reconciliation and support

Common Issues

Symptoms:
  • Cannot decrypt response token
  • “Invalid token” errors
Solutions:
  • Verify you’re using the correct Encryption Key
  • Check encryption algorithms match (A256KW, A256CBC-HS512)
  • Ensure no whitespace in keys
Symptoms:
  • API returns “Invalid amount” error
  • Request rejected with 400 status
Solutions:
  • Ensure amount is a string, not a number: "500.00" not 500
  • Always include 2 decimal places: "5.00" not "5"
  • Stay within min/max range (1.00 to 99999.99)
Symptoms:
  • Base64 decode fails
  • Invalid image format
Solutions:
  • Ensure full Base64 string was received (not truncated)
  • Check for proper Base64 padding
  • Verify you’re decoding as PNG format

Next Steps

Testing Guide

Learn how to test QR code generation and payment simulation

Webhooks

Set up webhooks to receive payment notifications

Error Handling

Handle errors gracefully in your application

Go Live

Deploy your integration to production

Authorizations

Authorization
string
header
required

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

Body

application/json
Token
string
required

JWE-encrypted token containing the payment payload. Algorithm: A256KW | Encryption: A256CBC-HS512. See the Encryption Guide for how to create this token.

Response

QR code generated successfully. Response contains an encrypted JWE token.

Token
string

JWE-encrypted response token. When decrypted, contains the transaction ID and QR code image.