EVevervault
Payments
Pre-Chargeback Alerts

Simulate a Pre-Chargeback Alert

Changed on

Simulates an incoming pre-chargeback alert so you can test your webhook handler and alert-processing logic. This endpoint is only available for Sandbox Apps.

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

post/payments/pre-chargeback-alerts/simulate-alert

Request

Request body

merchantIdstring required

The Evervault Merchant ID to simulate an alert for.

status'ACTION_REQUIRED' | 'RESOLVED' | 'INVALID'

The simulated alert status.

cardScheme'VISA' | 'MASTERCARD' | 'MAESTRO' | 'AMEX' | 'DISCOVER' | 'JCB' | 'DINERS_CLUB' | 'UNIONPAY' | 'RUPAY' | 'INTERAC' | 'MIR' | 'OTHER'

The card scheme for the simulated alert.

amountInCentsinteger

The disputed amount in cents. Must be a positive integer when supplied.

currencyCodestring

A valid ISO 4217 currency code.

transactionRefundOutcome'REFUNDED' | 'NOT_REFUNDED'

The refund outcome. May only be supplied when status is RESOLVED.

transactionAcquirerReferenceNumberstring

The ARN for the simulated transaction. Must be exactly 23 characters.

transactionAuthorizationCodestring

The authorization code for the simulated transaction. Must be exactly 6 characters.

externalCustomerReferencestring

An optional reference of your choice, such as a correlation ID, that is attached to the request. The reference will be visible in your logs. Must be between 1 and 255 characters.

Example request

{
  "merchantId": "merchant_eead1d640d7c",
  "status": "ACTION_REQUIRED",
  "cardScheme": "MASTERCARD",
  "amountInCents": 4999,
  "currencyCode": "USD",
  "transactionRefundOutcome": "REFUNDED",
  "transactionAcquirerReferenceNumber": "74027012345678901234567",
  "transactionAuthorizationCode": "ABC123",
  "externalCustomerReference": "00-4bf92f3577b34da6a3ce929d3e0e4736-00f067aa0ba902b7-01"
}

Response

Returns the simulated Pre-Chargeback Alert object.

idstring required

A unique identifier for the alert.

merchantIdstring required

The Evervault Merchant ID associated with the alert.

alertType'ETHOCA_ALERT' | 'VERIFI_RDR' required

The alert network that originated the alert.

alertNetworkIdstring nullable

The alert identifier from the alert network.

status'ACTION_REQUIRED' | 'RESOLVED' | 'INVALID' required

The current status of the alert. ACTION_REQUIRED only applies to Ethoca alerts.

chargebackReasonCodestring nullable

The reason code identifying why the dispute was raised.

transactionAmountInCentsinteger nullable

The disputed transaction amount in cents.

transactionCurrencyCodestring nullable

The ISO 4217 currency code of the disputed transaction.

transactionAuthorizedAtstring date-time nullable

When the transaction was authorized, as an ISO 8601 timestamp in UTC.

actionRequiredDeadlinestring date-time nullable

The deadline by which an Ethoca alert must be actioned. After this time the chargeback proceeds regardless of whether you refunded the customer.

transactionAuthorizationCodestring nullable

The authorization code for the disputed transaction.

transactionAcquirerReferenceNumberstring nullable

The Acquirer Reference Number (ARN). Useful when communicating with your PSP to identify the transaction.

transactionStatementDescriptorstring nullable

The descriptor that appeared on the cardholder's statement.

transactionCardBinstring nullable

The first 6–11 digits of the card number. Also included in card.bin.

transactionRefundOutcome'REFUNDED' | 'NOT_REFUNDED' | 'null' nullable

Populated when a refund outcome is known. For Verifi RDR, this is set automatically.

transactionNetworkIdstring nullable

The network transaction identifier, when available.

subscriptionCancelOutcomestring nullable

The outcome of a subscription cancellation, when available.

notestring nullable

An optional note stored with the alert for your own records.

integrationIdstring nullable

An optional integration identifier associated with the alert.

integrationTransactionIdstring nullable

An optional integration transaction identifier associated with the alert.

createdAtstring date-time required

When the alert was created, as an ISO 8601 timestamp in UTC.

Example response

{
  "id": "pre_chargeback_alert_eead1d640d7c",
  "merchantId": "merchant_eead1d640d7c",
  "alertType": "ETHOCA_ALERT",
  "alertNetworkId": "1234567890",
  "status": "ACTION_REQUIRED",
  "chargebackReasonCode": "10.4",
  "transactionAmountInCents": 4999,
  "transactionCurrencyCode": "USD",
  "transactionAuthorizedAt": "2025-02-10T10:30:00Z",
  "actionRequiredDeadline": "2025-02-17T10:30:00Z",
  "transactionAuthorizationCode": "ABC123",
  "transactionAcquirerReferenceNumber": "74027012345678901234567",
  "transactionStatementDescriptor": "EXAMPLE STORE",
  "transactionCardBin": "424242",
  "card": {
    "bin": "424242",
    "lastFour": "4242",
    "brand": "VISA",
    "issuer": "Example Bank"
  },
  "transactionRefundOutcome": null,
  "transactionNetworkId": null,
  "subscriptionCancelOutcome": null,
  "note": "Customer requested immediate review",
  "integrationId": null,
  "integrationTransactionId": null,
  "createdAt": "2025-02-11T10:30:00Z"
}

Changes