Webhooks - Modulus Labs API

Overview

When a payment is completed on a payment link, Modulus delivers a webhook event to your configured endpoint. Events are delivered via HTTPS POST with a JSON body and are retried with exponential backoff on failure.

Webhook endpoint configuration is managed through your Modulus dashboard or by contacting your account manager.

Event types

Event	Triggered when
`payment.succeeded`	A customer successfully completed a payment
`payment.declined`	A customer’s payment was declined by the card issuer
`payment.failed`	A payment failed due to a processing error
`payment.expired`	A payment link expired before any successful payment

Payload

{
  "event_type": "payment.succeeded",
  "payment_link_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_attempt_id": "660e8400-e29b-41d4-a716-446655440000",
  "amount": 150000,
  "currency": "PHP",
  "status": "SUCCEEDED",
  "card_brand": "VISA",
  "card_last_four": "4242",
  "merchant_branch_name": "SM City Angeles - Branch 1",
  "created_at": "2026-06-18T15:00:00Z"
}

Field	Type	Description
`event_type`	string	One of the event types above.
`payment_link_id`	string	The payment link (UUID) the event belongs to. Match this to the `id` you stored at creation.
`payment_attempt_id`	string	Unique identifier (UUID) for this payment attempt.
`amount`	integer	Amount in the smallest currency unit (centavos for PHP).
`currency`	string	ISO 4217 currency code.
`status`	string	Outcome of the payment attempt.
`card_brand`	string	Card network used (e.g., `VISA`).
`card_last_four`	string	Last four digits of the card.
`merchant_branch_name`	string	Display name of the branch.
`created_at`	string	ISO 8601 timestamp of the event.

Reconciling payments

Match incoming events to your records using the payment_link_id, then look up the link with Retrieve a Payment Link to read the order_reference and metadata you set at creation.

Respond with a 2xx status as soon as you receive an event. Acknowledge first, then process asynchronously — slow responses count as failures and trigger retries.