Pre-Chargeback Alerts

Pre-chargeback alerts notify you when a cardholder raises an issue with their issuer, giving you a window to resolve it before it escalates to a formal chargeback. This helps keep your chargeback ratio low and avoids potential issues with card networks like Visa and Mastercard.

Alert Types

There are two alert networks, each associated with different card schemes:

• Verifi RDR (Rapid Dispute Resolution) — primarily covers Visa transactions. When an alert arrives, Evervault automatically processes a refund on your behalf before a chargeback is filed. No manual action is required from you. You can optionally configure an amount rule per merchant to control which Verifi alerts are refunded.
• Ethoca Alerts — covers Mastercard, and some American Express and Discover transactions. Unlike Verifi RDR, Ethoca Alerts require you to take an action — such as issuing a refund through your PSP — and then update the alert via the API.

You can enrol a merchant in one or both networks at the same time.

How it works

Pre-chargeback alerts are configured per merchant through the Merchants API. You enable them by including a preChargebackAlerts object when creating or updating a merchant. When Evervault receives an alert from one of the networks, it creates an alert record that you can retrieve and respond to via the API. You can also subscribe to webhooks to receive alert and enrolment status notifications in real time.

Enable alerts for a merchant

You enable pre-chargeback alerts by including a preChargebackAlerts object when creating or updating a merchant. At least one of ethocaAlert or verifiRdr must be provided.

For a new merchant

Include preChargebackAlerts in the body of POST /payments/merchants:

1curl -X POST 'https://api.evervault.com/payments/merchants' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "name": "Example Store",
6    "website": "https://example.com",
7    "categoryCode": "5411",
8    "business": {
9      "legalName": "Example Store Ltd",
10      "address": {
11        "line1": "123 Main Street",
12        "city": "Dublin",
13        "postalCode": "D01 AB12",
14        "country": "IE"
15      }
16    },
17    "preChargebackAlerts": {
18      "ethocaAlert": {
19        "descriptors": [
20          { "descriptor": "EXAMPLE STORE", "match_type": "STARTS_WITH" }
21        ]
22      },
23      "verifiRdr": {
24        "bin": "424242",
25        "caid": "1234567890123456"
26      }
27    }
28  }'

For Ethoca, each descriptor entry matches the statement descriptor that appears on the cardholder's statement. The match_type can be STARTS_WITH or EXACT_MATCH. Each descriptor must be 1–100 printable ASCII characters, and you can supply at most 50 descriptors per enrolment. At least one descriptor is required when enrolling in Ethoca Alerts — an empty descriptors array is rejected with a 400 error. Descriptors determine which transactions trigger alerts; omitting ethocaAlert entirely enrols the merchant in Verifi RDR only (if configured), not in Ethoca.

For Verifi RDR, to match transactions you must provide either both a bin and caid (card acceptor ID), or a list of arns (acquirer reference numbers). bin and caid must always be supplied together. bin must be 6–11 digits, caid must be exactly 16 alphanumeric characters, and each arn must be exactly 23 digits. You can supply at most 50 ARNs.

For an existing merchant

Use PATCH /payments/merchants/{merchant_id} and include a preChargebackAlerts object with at least one of ethocaAlert or verifiRdr. The enabled field is optional and defaults to true.

1curl -X PATCH 'https://api.evervault.com/payments/merchants/{merchant_id}' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "preChargebackAlerts": {
6      "ethocaAlert": {
7        "descriptors": [
8          { "descriptor": "EXAMPLE STORE", "match_type": "EXACT_MATCH" }
9        ]
10      }
11    }
12  }'

The merchant's preChargebackAlerts field in the response shows the enrolment status:

1{
2  "id": "{merchant_id}",
3  "name": "Example Store",
4  ...
5  "preChargebackAlerts": {
6    "enrolments": [
7      {
8        "type": "ETHOCA_ALERT",
9        "status": "PENDING",
10        "ethocaAlert": {
11          "descriptors": [
12            { "descriptor": "EXAMPLE STORE", "match_type": "EXACT_MATCH", "status": "PENDING" }
13          ]
14        }
15      }
16    ]
17  }
18}

Enrolment statuses

The enrolments[].status field on a merchant can be one of:

Retrieve alerts

List alerts

GET /payments/pre-chargeback-alerts/alerts returns a paginated list of alerts for your app.

Supported query parameters:

• status — filter by ACTION_REQUIRED, RESOLVED, or INVALID.
• merchantId — filter by Evervault merchant ID.
• alertReceivedAtGte — return alerts received on or after this ISO 8601 timestamp (inclusive).
• alertReceivedAtLte — return alerts received on or before this ISO 8601 timestamp (inclusive). Must be greater than or equal to alertReceivedAtGte when both are provided.
• sort — sort order: -alert_received_at (newest first, default), alert_received_at (oldest first), -action_required_deadline, or action_required_deadline. Alerts without an action_required_deadline sort last when ascending (action_required_deadline) and first when descending (-action_required_deadline), as if their deadline were infinitely far in the future.
• limit — number of results per page, between 1 and 1000.
• offset — pagination offset.

Unknown query parameters are rejected with a 400.

1curl 'https://api.evervault.com/payments/pre-chargeback-alerts/alerts?status=ACTION_REQUIRED&merchantId={merchant_id}' \
2  -u '<app_id>:<api_key>'

The response is a paginated object with an items array and a count:

1{
2  "items": [ ... ],
3  "count": 1
4}

Get a single alert

1curl 'https://api.evervault.com/payments/pre-chargeback-alerts/alerts/{chargeback_alert_id}' \
2  -u '<app_id>:<api_key>'

Respond to an alert

Verifi RDR

Verifi RDR alerts are resolved automatically. They arrive with a status of RESOLVED or INVALID and do not require any action from you. The transaction_refund_outcome field reflects the outcome.

If the merchant has refund rules configured, Evervault evaluates the disputed amount against those rules before processing the refund. Alerts that do not match are not refunded and are not charged. Merchants without any rules continue to have all Verifi alerts refunded by default.

Ethoca Alerts

For Ethoca alerts in ACTION_REQUIRED status, take action with your PSP first — for example, issuing a refund. The transaction_statement_descriptor and transaction_acquirer_reference_number fields are useful to share with your PSP to identify the transaction.

Once you have taken action, update the alert via PATCH /payments/pre-chargeback-alerts/alerts/{alert_id}. Both fields are optional: action notifies Ethoca of the action you took on your PSP and is what prevents the chargeback from proceeding — omitting it means Ethoca is not notified. note is purely informational and is stored for your own records only; it is not sent to Ethoca. note may be up to 1000 characters and must not contain control characters.

Valid action values:

• REFUND — you have refunded the customer.
• CANCEL — you have cancelled or dismissed the alert.
• REFUND_AND_CANCEL — you have both refunded the customer and cancelled the subscription or order.
• ACCEPT_DISPUTE — you are accepting the chargeback (equivalent to dismissing the alert without taking action).

1curl -X PATCH 'https://api.evervault.com/payments/pre-chargeback-alerts/alerts/{chargeback_alert_id}' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "action": "REFUND",
6    "note": "Refund issued via PSP before deadline"
7  }'

Once actioned, the alert moves to RESOLVED status. Alerts that are already RESOLVED cannot be actioned again. Pay close attention to action_required_deadline — if you do not act before this ISO 8601 timestamp, the chargeback proceeds regardless.

Verifi RDR refund rules

Refund rules let you control which Verifi RDR alerts Evervault automatically refunds. Rules only affect Verifi RDR alert processing — they don't change how Ethoca alerts are resolved, even if the merchant is enrolled in both networks.

By default, when a merchant has no rules configured, all incoming Verifi alerts are refunded. Once you create one or more rules, Evervault evaluates the disputed transaction amount against those rules. If the amount matches, the alert is refunded as usual. If it does not match, the alert is not refunded — and because Verifi alerts are only charged when a refund is processed, non-matching alerts aren't billed either.

The rule object

1{
2  "id": "{rule_id}",
3  "type": "AMOUNT",
4  "outcome": "REFUND",
5  "parameters": {
6    "operator": "LESS_THAN_OR_EQUAL",
7    "currency_code": "USD",
8    "amount_in_cents": 5000
9  },
10  "created_at": "2025-02-11T10:30:00Z"
11}

• type — currently AMOUNT (the only supported rule type).
• outcome — the action taken when the rule matches. Currently always REFUND.
• parameters.operator — one of GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, EQUAL, or NOT_EQUAL.
• parameters.currency_code — must be USD. Only USD transaction amounts are supported for rule evaluation. If you want to set a threshold in another currency, convert it to USD yourself and pass the equivalent amount in cents with currency_code set to USD.
• parameters.amount_in_cents — the threshold amount in cents against which the disputed amount is compared. Must be a positive integer.
• created_at — ISO 8601 timestamp (UTC), consistent with the alert object's created_at.

Create a rule

POST /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules

The merchant must already be enrolled in Verifi RDR — rules only govern Verifi auto-refunds, so creating a rule for a merchant enrolled only in Ethoca is rejected with a 400. Both type and all parameters fields are required. Returns 201 with the created rule.

1curl -X POST 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "type": "AMOUNT",
6    "parameters": {
7      "operator": "LESS_THAN_OR_EQUAL",
8      "currency_code": "USD",
9      "amount_in_cents": 5000
10    }
11  }'

This example refunds Verifi alerts where the disputed amount is $50.00 USD or less. Alerts above that threshold are not refunded.

Update a rule

PATCH /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}

A rule's type cannot be changed — only its parameters. parameters is replaced, not merged, so send the complete object (operator, currency_code, amount_in_cents); a partial or empty object is rejected with 400. Omitting parameters entirely is a no-op — the rule is returned unchanged. Returns 200 with the updated rule, or 404 if the rule does not exist or does not belong to that merchant.

1curl -X PATCH 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "parameters": {
6      "operator": "LESS_THAN_OR_EQUAL",
7      "currency_code": "USD",
8      "amount_in_cents": 10000
9    }
10  }'

List rules

GET /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules

Returns a JSON array of rules for the merchant.

A merchant has at most one rule, so this array contains zero or one item.

Unlike the alerts list, the response is a bare array, not wrapped in an { items, count } object.

1curl 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules' \
2  -u '<app_id>:<api_key>'

Get a rule

GET /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}

Returns 404 if the rule does not exist or does not belong to that merchant.

1curl 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}' \
2  -u '<app_id>:<api_key>'

Delete a rule

DELETE /payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}

Deleting a rule restores the default behaviour: all Verifi alerts for that merchant are refunded. Returns 204 No Content on success. Returns 404 if the rule does not exist or has already been deleted — delete is not idempotent, so retrying a successful delete won't return 204.

1curl -X DELETE 'https://api.evervault.com/payments/pre-chargeback-alerts/merchants/{merchant_id}/rules/{rule_id}' \
2  -u '<app_id>:<api_key>'

Webhooks

Rather than polling the API, you can subscribe to webhook events to be notified in real time. Pre-chargeback alerts supports two event types:

• payments.pre-chargeback-alert.received — fired when Evervault receives a new alert for your app.
• payments.pre-chargeback-enrolment-status.updated — fired when an enrolment's status changes (for example, PENDING → ACTIVE).

See the Webhooks documentation for full setup instructions, including how to secure and register your endpoint. Register your endpoint in the Dashboard under Settings > Webhooks and subscribe to the events you need.

Alert received

Event type: payments.pre-chargeback-alert.received

Fired whenever Evervault receives a new alert for your app. Each delivery is a POST request with a JSON body shaped as a standard webhook event object:

1{
2  "id": "{event_id}",
3  "type": "payments.pre-chargeback-alert.received",
4  "data": {
5    ...alert object...
6  },
7  "createdAt": "2025-02-11T10:30:00Z"
8}

The data field contains the full alert object. Here is an example handler that processes both pre-chargeback alert webhook events:

1app.post("/evervault", (req, res) => {
2  const event = req.body;
3
4  switch (event.type) {
5    case "payments.pre-chargeback-alert.received": {
6      const alert = event.data;
7
8      if (
9        alert.alert_type === "ETHOCA_ALERT" &&
10        alert.status === "ACTION_REQUIRED"
11      ) {
12        // Resolve with your PSP, then PATCH the alert via the Evervault API
13      }
14      break;
15    }
16    case "payments.pre-chargeback-enrolment-status.updated": {
17      const configuration = event.data;
18
19      if (configuration.status === "ACTIVE") {
20        // Enrolment is live — the merchant can now receive alerts
21      } else if (configuration.status === "ACTION_REQUIRED") {
22        // Enrolment needs attention (usually an Ethoca descriptor issue)
23      }
24      break;
25    }
26  }
27
28  res.status(200).send({ success: true });
29});

Enrolment configuration updated

Event type: payments.pre-chargeback-enrolment-status.updated

Fired when an enrolment's status changes after the initial create or update call — for example when a network activates the enrolment or flags a descriptor for review. This is the recommended way to track enrolment status transitions without polling the Merchants API.

Each delivery uses the same webhook event object shape:

1{
2  "id": "{event_id}",
3  "type": "payments.pre-chargeback-enrolment-status.updated",
4  "data": {
5    ...configuration object...
6  },
7  "createdAt": "2025-02-11T10:30:00Z"
8}

The data field contains a configuration object describing the status transition.

The alert object

When Evervault receives an alert from one of the networks, it creates an alert record. Here is a full example:

1{
2  "id": "{chargeback_alert_id}",
3  "merchant_id": "{merchant_id}",
4  "alert_type": "ETHOCA_ALERT",
5  "alert_network_id": "1234567890",
6  "status": "ACTION_REQUIRED",
7  "chargeback_reason_code": "10.4",
8  "transaction_amount_in_cents": 4999,
9  "transaction_currency_code": "USD",
10  "transaction_authorized_at": "2025-02-10T10:30:00Z",
11  "action_required_deadline": "2025-02-17T10:30:00Z",
12  "transaction_authorization_code": "ABC123",
13  "transaction_acquirer_reference_number": "74027012345678901234567",
14  "transaction_statement_descriptor": "EXAMPLE STORE",
15  "transaction_card_bin": "424242",
16  "card": {
17    "bin": "424242",
18    "last_four": "4242",
19    "brand": "VISA",
20    "issuer": "Example Bank"
21  },
22  "transaction_refund_outcome": null,
23  "transaction_network_id": null,
24  "subscription_cancel_outcome": null,
25  "note": "Customer requested immediate review",
26  "integration_id": null,
27  "integration_transaction_id": null,
28  "created_at": "2025-02-11T10:30:00Z"
29}

• alert_type — either ETHOCA_ALERT or VERIFI_RDR.
• status — ACTION_REQUIRED (Ethoca only), RESOLVED, or INVALID.
• transaction_authorized_at, action_required_deadline, and created_at — ISO 8601 timestamps in UTC (for example, "2025-02-11T10:30:00Z"). For Ethoca alerts, you must act before action_required_deadline or the chargeback proceeds regardless of whether you refunded the customer.
• transaction_acquirer_reference_number — the ARN, which is useful when communicating with your PSP to identify the transaction.
• transaction_statement_descriptor — the descriptor that appeared on the cardholder's statement.
• transaction_card_bin — first 6–11 digits of the card number. Also included in card.bin.
• card — card details for the disputed transaction, when available. Contains bin (BIN/IIN), last_four (last four digits), brand (card scheme, for example VISA or MASTERCARD), and issuer (issuing bank name).
• transaction_refund_outcome — populated when a refund outcome is known. For Verifi RDR, this is set automatically.

The configuration object

When an enrolment's status changes, the payments.pre-chargeback-enrolment-status.updated event includes a configuration object in data. Here is a full example:

1{
2  "id": "{chargeback_alerts_enrolment_id}",
3  "merchant_id": "{merchant_id}",
4  "type": "ETHOCA_ALERT",
5  "old_status": "PENDING",
6  "status": "ACTIVE",
7  "updated_at": "2025-02-11T10:30:00Z"
8}

• id — Evervault enrolment UUID (for example, chargeback_alerts_enrolment_...).
• merchant_id — Evervault merchant ID the enrolment belongs to.
• type — enrolment network: ETHOCA_ALERT or VERIFI_RDR.
• old_status — status before this update. null on the first event for a new enrolment.
• status — current enrolment status after the update. See enrolment statuses for possible values.
• updated_at — ISO 8601 timestamp (UTC) when the enrolment was last updated.

Provider-specific configuration (Ethoca descriptors, Verifi BIN/CAID, and so on) is not included in the webhook payload — retrieve the merchant via the Merchants API if you need the full enrolment details.

Testing (sandbox)

In sandbox, you can simulate an incoming alert without waiting for a real dispute. This is useful for testing your webhook handler and alert-processing logic.

1curl -X POST 'https://api.evervault.com/payments/pre-chargeback-alerts/simulate-alert' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "merchantId": "{merchant_id}",
6    "status": "ACTION_REQUIRED",
7    "cardScheme": "MASTERCARD",
8    "amountInCents": 4999,
9    "currencyCode": "USD"
10  }'

All fields other than merchantId are optional. The merchantId must belong to a merchant that has already been enrolled in pre-chargeback alerts. When supplied:

• amountInCents must be a positive integer.
• currencyCode must be a valid ISO 4217 code.
• status must be one of ACTION_REQUIRED, RESOLVED, or INVALID.
• cardScheme must be one of VISA, MASTERCARD, MAESTRO, AMEX, DISCOVER, JCB, DINERS_CLUB, UNIONPAY, RUPAY, INTERAC, MIR, or OTHER.
• transactionRefundOutcome must be REFUNDED or NOT_REFUNDED, and may only be supplied when status is RESOLVED.
• transactionAcquirerReferenceNumber must be exactly 23 characters.
• transactionAuthorizationCode must be exactly 6 characters.

The endpoint returns a simulated alert object with a 201 status.

Disable alerts

To disable pre-chargeback alerts for a merchant, call PATCH /payments/merchants/{merchant_id} with preChargebackAlerts.enabled set to false:

1curl -X PATCH 'https://api.evervault.com/payments/merchants/{merchant_id}' \
2  -H 'Content-Type: application/json' \
3  -u '<app_id>:<api_key>' \
4  -d '{
5    "preChargebackAlerts": {
6      "enabled": false
7    }
8  }'

Errors

Pre-chargeback alerts endpoints return standard Evervault API error responses. Common cases:

Reason codes

Each alert includes a chargeback_reason_code field that identifies why the dispute was raised. The codes differ by card network.