# 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`.                          |

## Recommended paths {#recommended-paths}

Select the path that matches your role and integration requirements.

|                                 If you are a...                                  |                        Then focus on...                        |
|----------------------------------------------------------------------------------|----------------------------------------------------------------|
| **Enterprise merchant**, a large merchant integrating directly with Gateway APIs | Receives alerts and retries declined transactions.             |
| **Payment service provider**, a PSP, aggregator, or payment facilitator          | Enables and manages alerts for merchants across the platform.  |
| **Software vendor**, an ISV embedding payment flows into platforms               | Builds alerting and retry logic as part of merchant solutions. |
| **Acquirer**, a bank or acquiring institution that enables merchants             | Provides enablement for processing and identifiers only.       |

## API reference {#api-reference}

Payment Alerts are generated for these API operations:

* [Initiate Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication): Request returning which payer authentication mechanism (for example, EMV 3-D Secure authentication version 2, EMV 3-D Secure authentication version 1, RuPay PaySecure) the gateway recommends you use for this order.
* [Authenticate Payer](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication): The system sends this notification after the Authenticate Payer operation completes. It includes details of the authentication operation only and does not provide information about the outcome of the financial transaction. Authentication Payer does not support `order.notificationUrl` in JSON payload, but the system sends a webhook on the URL that you set up in the Initiate Authentication request.
* [Authorization](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [Pay](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Authorization or Pay transaction operation completes. It includes the outcome of the financial transaction processing.
* [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Capture transaction operation completes. It includes the outcome of the financial transaction processing. Standalone Capture is also supported.
* [Refund](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Refund transaction operation completes. It includes the outcome of the financial transaction processing. Standalone Refund is also supported.
* [Update Authorization](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Update Authorization transaction operation completes. It includes the outcome of the financial transaction processing.
* [Void](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Void transaction operation completes. It includes the outcome of the financial transaction processing.
* [Verify](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Verify transaction operation completes. It includes the outcome of the financial transaction processing.
* [Referral](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Referral transaction operation completes. It includes the outcome of the financial transaction processing.
* [Disbursement](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction): The system sends a notification after the Referral transaction operation completes. It includes the outcome of the financial transaction processing.
* [Initiate Browser Payment](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment): The system sends a notification after the IBP transaction operation completes. It includes the outcome of the financial transaction processing.
* [Confirm Browser Payment](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment): The system sends a notification after the CBP transaction operation completes. It includes the outcome of the financial transaction processing.   

For a complete list of supported APIs, see [API Reference](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/index.md).

## Versions {#versions}

These versions apply to Payment Alerts.

|       If you need...       |                        Then...                         |
|----------------------------|--------------------------------------------------------|
| **To integrate to an API** | Enable this functionality through the Merchant Portal. |