Webhook Specification

Shared rules for Payment / Refund / Payout / Exchange notifications.

Common rules

Rule	Requirement
Transport	HTTPS callback URL
Timeout	Respond within 3 seconds
Failure handling	Slow or non-success responses are treated as delivery failure
Idempotency	Handle duplicate deliveries safely
Signature	Verify request signature / Digest using platform rules

Recommended envelope

{
  "eventId": "evt_xxx",
  "eventType": "PAYMENT.SUCCEEDED",
  "createdAt": "2026-08-08T12:00:00Z",
  "data": {}
}

Partner webhook envelope

{
  "eventId": "evt_xxx",
  "eventType": "PAYMENT.SUCCEEDED",
  "partnerId": "P10001",
  "merchantId": "M20001",
  "data": {
    "paymentId": "PAY10001",
    "merchantOrderNo": "ORDER10001",
    "amount": 100.00,
    "currency": "BRL",
    "status": "SUCCEEDED"
  }
}

Partner platforms should route events by merchantId to downstream merchants.

Endpoint-specific webhook pages remain under Merchant API Collection / Payout / Exchange.