# Payment Notifications

Fluxis can send a merchant email notification when a payment outcome is recorded for an account. Sales notifications are enabled by default. Set `sales_notifications_enabled` to `false` to stop them. While they are enabled, Fluxis sends to the account notification email, or to the organization owner email when that address is empty.

## Overview

When a payment reaches a final on-chain status, Fluxis records it as a transaction in your ledger (Hop 3 of the payment lifecycle) and then sends one email when sales notifications are enabled. Because the ledger step runs from a queue, the email can arrive a few seconds after the webhook with the final status. Completed and overpaid payments receive a **new sale** email; underpaid payments receive an **action required** email. Each email includes, when available:

- **Amount received** - the amount actually received, with the token symbol (e.g. `USDC`, `USDT`) and network (e.g. Polygon, Base)
- **Requested amount and difference** - the missing amount for underpaid payments, the extra amount for overpaid payments
- **Point of sale** and **account** names
- **Sale amount** - the reference (fiat) amount of the payment request, when it was created with one
- **Order reference** - the `external_id` set on the payment request
- **Payer address** and **transaction hash**
- **Payment ID** - the Fluxis payment request identifier for reconciliation
- A button that opens that transaction in the Fluxis Dashboard (for underpaid payments, the transaction on hold)

Rows with no data are left out of the email.

Notifications are sent for **completed**, **overpaid**, and **underpaid** payments. Only one email is sent per payment. Payments that are failed or still pending do not trigger an email.

::::note
This feature requires the Fluxis transactional email service to be enabled for your environment. Contact support if emails are not arriving.
::::

## Configure via the API

Use your organization-level API credentials to read or write the notification email and the sales-notification switch for an account. Both fields are optional on update: omit a field to leave it unchanged.

### Get the current setting

```bash
GET /v1/account/notification-email/{accountId}
```

Response:

```json
{
  "data": {
    "notification_email": "payments@your-store.com",
    "sales_notifications_enabled": true
  }
}
```

Returns `null` for `notification_email` when no address is configured. `sales_notifications_enabled` is `true` when the account has no stored switch.

### Set or update the settings

```bash
PUT /v1/account/notification-email/{accountId}
Content-Type: application/json

{
  "notification_email": "payments@your-store.com",
  "sales_notifications_enabled": true
}
```

Send only the field you want to change. Omitting `notification_email`, including an empty body `{}`, leaves the stored address unchanged. Omitting `sales_notifications_enabled`, or sending `null`, leaves the switch unchanged.

To stop merchant sale emails without changing the address:

```json
{
  "sales_notifications_enabled": false
}
```

Set it back to `true` to resume them. While the switch is on, an empty address still receives mail at the organization owner email.

To clear the address, send `null` or an empty string. Clearing the address does not turn sales notifications off:

```json
{
  "notification_email": null
}
```

The address is validated as a standard RFC 5322 email address. An invalid address returns HTTP `400`.

This switch affects merchant sale emails only (completed, overpaid, and underpaid). It does not affect collaborator invitation emails or two-factor authentication emails.

## Configure via the Dashboard

Dashboard users with the **Owner** or **Admin** role can manage the notification email and the sales-notification switch under **Accounts** in the Fluxis Dashboard. The dashboard endpoints use the same JSON body as the public API.

| Action | Endpoint |
| ------ | -------- |
| Get | `GET /dashboard/accounts/notification-email/{accountID}` |
| Set | `PUT /dashboard/accounts/notification-email/{accountID}` |

## One email per account

- A single optional email address is supported per account. It is not a list.
- The setting belongs to the account, not to a specific Point of Sale.
- All final-status payments for that account, from any Point of Sale, trigger a notification to the same address while sales notifications are enabled.

## Underpaid payments

When the received amount is less than the expected amount, the payment status is set to `underpaid`. The email is marked **Action required** and shows the requested amount, the received amount and the missing amount. Underpaid payments are held and do not settle automatically: open the payment from the email button, review the transaction in the Fluxis Dashboard, and choose whether to accept it as paid or refund it.

## Troubleshooting

| Issue | What to check |
| ----- | ------------- |
| No email received | Check that `sales_notifications_enabled` is true, and that either `notification_email` or the organization owner email is set; check spam folder |
| Invalid address error | The address must be a valid RFC 5322 email |
| No email for failed or pending payment | Expected - only `completed`, `overpaid`, and `underpaid` trigger emails |

## Related

- [Webhooks](/docs/developers/webhooks) - real-time HTTP notifications for payment status changes
- [Webhook Events](/docs/developers/webhook-events) - full list of webhook event types