PayPal Notifications

BR-DGE sends notifications to your server for key PayPal payment events. This allows you to keep your system in sync with the outcome of transactions without having to poll the API.

Supported Event Types

Event	Trigger
`checkout.order.completed`	A PayPal order has been completed
`checkout.order.approved`	A customer has approved a PayPal order
`payment.capture.completed`	A payment capture was successful
`payment.capture.denied`	A payment capture was denied
`payment.capture.refunded`	A payment was refunded
`payment.capture.reversed`	A payment was reversed
`payment.authorization.created`	A payment authorization was created
`payment.authorization.voided`	A payment authorization was voided

Notification Structure

All BR-DGE PayPal notifications follow this structure:

{
  "type": "payment",
  "id": "...",
  "merchantAccountId": "...",
  "code": "1000",
  "status": "...",
  "message": {
    "webhookEvent": "payment.capture.completed"
  },
  "psp": {
    "name": "PayPal-Direct",
    "transactionId": "..."
  },
  "hashCode": "..."
}

Key Fields

Field	Description
`type`	Always `payment` for PayPal notifications
`id`	BR-DGE notification identifier
`merchantAccountId`	Your BR-DGE merchant account ID
`code`	BR-DGE response code (e.g. `1000` for success)
`status`	The current payment status
`message.webhookEvent`	The specific PayPal event that triggered this notification
`psp.name`	Always `PayPal-Direct`
`psp.transactionId`	PayPal's transaction reference
`hashCode`	Used to authenticate the notification

Authentication

BR-DGE PayPal notifications use the standard BR-DGE notification authentication method. You should validate the notification body on every incoming request before updating your order or payment state.

Refer to the BR-DGE Notification Authentication guide for full implementation details.

🚧
Always Validate Notifications
Never update payment or order state based on an unauthenticated notification. Always verify the notification first to confirm the request originated from BR-DGE.