Matching alerts
Get started
Sign In
Matching alerts
Internal logic for quick matching of alert data by the system in real-time

Payment matching is performed client-side using an algorithm that involves multiple steps, each utilizing different data sets.

Matching algorithm

The first step in the matching process involves using the Transaction ID parameter. If transaction IDs on transactions include additional dates before or after the ID, it is necessary to adjust the format to match the clean format found in the alert.

If both the ARN is available for an alert and the transaction, use these along with the PAN to match. Although ARNs are recycled and not unique by themselves, pairing them with the account number ensures uniqueness. This method is both highly accurate and easy to implement.

If ARN data is unavailable, use the authorization code and PAN. If multiple transactions match the same authorization code and PAN, narrow your search by using an authorization date within a 2-day interval to achieve more than 80% successful matches.

If neither ARN nor authorization codes are available, match using the PAN, transaction timestamp (date), transaction amount, and currency identifier. Note that the transaction timestamp and amount (along with the currency) are variable criteria for matching. Consider the following:

  • Amount
    If real-time currency conversion is available, use an FX rate to convert the transaction currency based on the transaction timestamp. Expect a small variance due to FX rate differences between providers; a 1-2% variance may aid in matching.
    • If real-time conversion isn’t possible, consider a static conversion using a periodic refresh rate, e.g., a rate of 1.05 for EUR to USD conversions, allowing for a slightly larger variance than 1-2%.
    • Without currency conversion, find a variance that accommodates multiple currencies.
  • Transaction Timestamp
    Issuers may deliver dates in various formats, including full timestamps or the date. Some may use midnight as the timestamp. Account for these differences, as they can affect matching logic. For dates without a specific time, a larger spread is required.

If an alert cannot be matched to a transaction, update it with an reconciliation API , especially post-integration, are recommended to optimize matching logic.

Matching logic approaches:

  • Cascading rules
    Reduce potential matches by sequentially applying each criterion.
  • Sliding window
    Use recursive or iterative queries to adjust the match variance, narrowing or widening the search as needed.
  • Card acceptor ID
    Use this to narrow down potential transactions further.

Response time

Matching should occur in near-real-time, with the full request-response cycle occurring within specific timeframes for various services:

  • Inquiry ( Guide
    A tool that allows merchants to stop Visa chargebacks before they are initiated by the customer.
    Order Insight
    / Guide
    Consumer Clarity (formerly referred to as Ethoca Eliminator) is a system that allows the merchant to provide details of the transaction to the issuing bank to prevent unlawful chargebacks.
    Consumer Clarity
    ) - 1 second
  • Ethoca - 24 hours
  • CDRN - 72 hours
  • RDR - while not required, tagging is recommended for verification.

The best practice is to match all transactions simultaneously, and if data is insufficient, send temporary data. Alerts outside required timeframes are acknowledged and marked as Not found in the system.

Request alert fields

Field API Name Example
Acquirer reference number (ARN) is a unique number assigned to credit card transactions as they progress through the payment flow. arn 24118599140010072053960
Card acceptor ID (CAID) is an internal identifier your Acquirer provides when setting up your merchant account, essential for enrolling in services like Order Insight, Inform, or Rapid Dispute Resolution. caid 72000573
Personal account number (PAN) is a partial card number (BIN + Last 4) used in transactions due to security reasons that prevent showing the full card number. personalAccountNumber 400022xxxxxx5582
Transaction ID is the primary identifier used in most alerts, useful for initial matching attempts. Visa and Mastercard use different ID formats. transaction: id MDSXK1CQE (Visa), XYZ123ABC (Mastercard)
Transaction amount is the monetary value of the transaction. transaction: amount 0.99
Transaction currency ID represents the currency used in the transaction and is identified by ISO 4217 codes. transaction: currency 840
Transaction date time is delivered in the ISO8601 DateTime format, and the transaction timestamp is in GMT; time part and timezone offset may be omitted. transaction: date 2022-04-26 02:40:01
Authorization code is an identifier provided when a transaction is authorized. authorizationCode 032B87D