# PayPal Notifications

# 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:

```json
{
  "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 <Anchor label="notification authentication" target="_blank" href="/docs/notification-authentication">notification authentication</Anchor> method. You should validate the notification body on every incoming request before updating your order or payment state.

Refer to the <Anchor label="BR-DGE Notification Authentication" target="_blank" href="/docs/notification-authentication">BR-DGE Notification Authentication</Anchor> 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.