# Payment Alerts
source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/payment-alerts/index.md

## Overview {#overview}

Payment Alerts is a network-driven notification service that informs merchants when a payment declined for insufficient funds is likely to succeed if retried. The service delivers alerts in near real time, enabling smarter retries with higher success rates and no guesswork.

Payment Alerts send webhook notifications when a retry of a previously declined transaction is more likely to succeed.

Each webhook notification includes transaction details to help you identify the original transaction for retry. This capability can improve acceptance rates by helping you time retries more effectively.

This page is for merchants that use webhooks with the gateway, including gateway processing and non-processing merchants.
Note: Consider these service details when you plan your integration:

* MID-level monitoring webhooks are signed using JSON Web Signature (JWS). Validate the signature before you process a notification.
* If you do not see enablement options, contact your acquirer or account team.

## Prerequisites {#prerequisites}

Complete these prerequisites before you enable payment alerts:

* Complete onboarding on the relevant gateway instance for your processing model (processing or non-processing).
* Enable and configure webhook notifications for your merchant profile in the gateway.
* Enable Payment Alerts for your merchant account.
* Update the retry logic to act on the alerts.

Note: Refer to these guides for webhook setup and configuration:

* To enable webhook notifications, refer to the Mastercard Gateway Merchant Manager User Guide Enterprise in the Merchant Manager Portal.
* To configure webhook notifications, refer to the Mastercard Gateway Merchant Administration User Guide Enterprise in the Merchant Administration Portal.
* For webhook notification details, refer to [Webhook notifications](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/webhook-noti/index.md).

## MID-level monitoring using MID or CAIC ID and ICA number {#mid-level-monitoring-using-mid-or-caic-id-and-ica-number}

### Overview {#overview-1}

MID-level monitoring supports registration for payment alerts using the acquirer merchant ID (CAIC ID) and the ICA number.

### When to use MID-level monitoring {#when-to-use-mid-level-monitoring}

* You want to recover and optimize merchant-initiated transactions that the Mastercard Network declines for insufficient funds.
* You want notifications that apply across merchant instances or regions using scheme identifiers (CAIC ID and ICA number).

### Prerequisites {#prerequisites-1}

Complete these prerequisites before you enable MID-level monitoring:

* You are onboarded on the gateway, and your merchant details are processed through the Mastercard Network.
* Webhook notifications are enabled for your merchant profile in the gateway.

## Set up a merchant profile for MID-level monitoring {#set-up-a-merchant-profile-for-mid-level-monitoring}

Set up your merchant profile on the gateway and confirm that the scheme identifiers are configured correctly.

### Set up a merchant profile for merchants {#set-up-a-merchant-profile-for-merchants}

1. Create your merchant profile on the gateway under the optimizations capability MSO.
2. Configure these scheme identifiers for your merchant profile:
   * Acquirer merchant ID (CAIC ID)
   * ICA number

## Enable payment alerts for merchant MIDs in Merchant Manager {#enable-payment-alerts-for-merchant-mids-in-merchant-manager}

### Prerequisites {#prerequisites-2}

Account teams must enable Payment Alerts for the Merchant Service Organization (MSO). After that, the MSO can enable Payment alerts for merchants in **Merchant Manager** through **Merchant configuration**.

To enable payment alerts for a merchant, complete these steps:

1. Sign in to **Merchant Manager** as the MSO.
2. Select the merchant that you want to enable for Payment Alerts.
3. Locate the Payment Alerts section, and click **Configure**.
4. If the Notifications and Payment Alerts privilege is enabled, the system delivers webhook notifications for transactions, payment alerts, or both.
5. Download the CSV template. The file shows the current ICA + MID (CAIC) state for the merchant.
6. Update the CSV file. Add valid MID or CAIC pairs for the ICA. Use alphanumeric values for the MID or CAIC, and numeric values for the ICA.
7. Verify that the ICAs that you use are allowed at the MSO level.
8. Upload the updated CSV file.
9. Submit the file for validation. The system validates:
   * ICA format
   * MID format
   * ICA authorization at the MSO level
10. If validation errors display, correct them and upload the file again.
11. Download the file again to confirm the final saved state.

### CSV validation best practices {#csv-validation-best-practices}

* If the ICA is not defined in the MSO configuration, the upload fails.
* If the ICA or CAIC format is incorrect, validation errors display.
* Excel removes leading zeros, which leads to incorrect identifier values.
* If the unknown acquirer is not preset, the upload fails.
* If the **Notifications** privilege is missing, the upload or downstream UI is blocked.

Note: Excel might remove leading zeros from ICA values. Follow the CSV formatting guidance shown in the UI to preserve the values.

## Webhook notification content for MID-level monitoring {#webhook-notification-content-for-mid-level-monitoring}

For MID-level monitoring, the webhook payload is signed using JSON Web Signature (JWS). Validate the signature before you process the notification.

### Sample webhook notification {#sample-webhook-notification}

The webhook notification includes transaction details that help you identify the transaction, such as transaction time, original amount, transaction currency, and other identifiers. This example illustrates fields you can use to identify the transaction for retry.

```json
{
  "notificationId": "1",
  "acquirerInstitutionId": "123456",
  "acquirerMerchantId": "222222222222222",
  "financialNetworkProductCode": "MRG",
  "financialNetworkTransactionIdentifier": "9vfIQdqt",
  "financialNetworkTransmissionDate": "0801",
  "transactionTime": "2025-01-28T13:53:47.314Z",
  "transactionAmount": "123.45",
  "transactionCurrency": "USD",
  "notificationStatus": "RETRY_NOW",
  "cardBin": "5123456",
  "maskedPan": "************9000"
}
```

### Webhook notification fields {#webhook-notification-fields}

This table defines each field in the webhook notification.

| No. |                  Field                  | Specification |     Length     |                                               Definition                                                |
|-----|-----------------------------------------|---------------|----------------|---------------------------------------------------------------------------------------------------------|
| 1   | `notificationId`                        | type: string  | max: 30        | A unique identifier generated for this notification.                                                    |
| 2   | `acquirerInstitutionId`                 | type: string  | max: 30        | The identifier allocated to the acquirer by the financial network.                                      |
| 3   | `acquirerMerchantId`                    | type: string  | max: 30        | The identifier allocated to the merchant by the acquiring institution.                                  |
| 4   | `financialNetworkProductCode`           | type: string  | max: 3         | The program or service associated with the transaction.                                                 |
| 5   | `financialNetworkTransactionIdentifier` | type: string  | max: 9         | The financial network identifier for the insufficient funds declined transaction.                       |
| 6   | `financialNetworkTransmissionDate`      | type: string  | max: 4         | Transaction date in MMDD format.                                                                        |
| 7   | `transactionTime`                       | type: string  | max: 40        | Date and time the financial network processed the transaction in ISO 8601 format.                       |
| 8   | `transactionAmount`                     | type: string  | max: 30        | The amount for the insufficient funds declined transaction.                                             |
| 9   | `transactionCurrency`                   | type: string  | max: 3         | The currency for the transaction expressed as an ISO 4217 alpha code.                                   |
| 10  | `notificationStatus`                    | type: string  | max: 30        | The status of the notification. The value `RETRY_NOW` indicates the transaction is ready to be retried. |
| 11  | `cardBin`                               | type: string  | min: 6, max: 9 | Bank Identification Number (BIN) for the PAN used in the transaction.                                   |
| 12  | `maskedPan`                             | type: string  | max: 30        | PAN masked to show only the last four digits, for example, `************9000`.                          |