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


Payment matching is performed on the client side; for example, the gateway labels the order using an algorithm, which includes several steps. Each step uses different data.

Matching algorithm

If the ARN is available for the alert and the transaction, then use this with the PAN to match the alert. ARNs are recycled, so they are not unique by themselves. However, when coupled with the account number, they will be unique. This method is the most accurate and the easiest in terms of implementation.

If there is no ARN data, then use Authorization Code, and PAN filters. If you get several transactions for one Authorization Code and PAN, then filter by the Authorization Date with an interval of 2 days. This way, you would achieve more than 80% of successful matching.

If ARN and authorization codes are not available, use PAN, the transaction timestamp (i.e., transaction date), transaction amount, and currency identifier, whereas, the transaction timestamp and amount (with currency) are variable criteria for matching. Some points related to variable parts to be aware of are listed below:

  • Amount

If real-time currency conversion is available to you, using a foreign exchange rate (FX), convert the currency. It will be best to use the currency you have on hand based on the transaction timestamp on the alert. Even in this case, due to FX rate differences between providers, a small variance of 1~2% will help in the match.

If the above is not possible, a static conversion may be an option. The static FX rate can be refreshed periodically, i.e., use a rate of 1.05 for some time frame for all EUR to USD conversions until a refresh is required. In this case, a slightly larger variance than 1~2% will help with the match.

If currency conversion is not possible at all, you’ll need to find a variance that works to account for multiple currencies.

  • Transaction Timestamp
Not all issuers deliver the same date/time format. Some send a full timestamp with the date and time. Some send only the date without the time or, time-stamped as midnight from their system of record. Take this into account as it will impact potential matching logic. For dates with no time/midnight, a larger variance will be needed.

If an alert cannot be matched to a transaction, it would be updated with the Acknowledged outcome and shown as Not found in the system. It is possible to review them via the Portal or the Glossary
Chargeback reconciliation, is the process of balancing the general ledgers when a chargeback occurs.
API. We strongly recommend reviewing this list periodically, especially after going live with the integration, to ensure that the matching logic can be optimized from these learnings.

Matching logic approaches

  • Cascading Rules
This involves reducing the potential matching data set by running each criterion as a rule. In other words, find transactions that match the card –> of those transactions, find transactions that have an amount within x% variance –> of those transactions, and find transactions that are within y time of transaction timestamp.

  • Sliding Window
This involves using recursive or iterative queries, assuming they can be done with a performant method. Sliding windows can either be done to narrow or widen the match. For example, you can start with a large window of variance on both the amount and the transaction timestamp. You can then iterate through the process by reducing the variance until a single match is found.

  • Card Acceptor ID
This is recommended to use to narrow the pool of potential transactions.

Response time

The matching should be performed in an almost real-time manner. The full cycle of request-response should be made in the timeframe for:

  • Inquiry ( Glossary
    A tool that allows merchants to stop Visa chargebacks before they are initiated by the customer.
    Order Insight
    / Glossary
    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 - it is possible not to tag, but for verification we recommend

The best practice is to match all at once, and if the transaction data is insufficient, we send temporary data. All alerts that would fall outside the required timeframes would be provided with the outcome Acknowledged , and they would be updated as Not found in the system.

Request alert fields

The following fields from the alert request should be considered for the transaction matching:

Field API Name Example
Acquirer Reference Number (ARN) requestData:arn 24118599140010072053960
Card Acceptor ID (CAID) requestData:cardAcceptorId 72000573
Personal Account Number (PAN)* requestData:personalAccountNumber 400022xxxxxx5582
Transaction Currency ID** requestData:transactionAmount:currency 840
Transaction Date Time*** requestData:transactionDate 2022-04-26 02:40:01
Authorization Code requestData:authorizationCode 032B87D
Transaction Amount requestData:transactionAmount:value 0.99
*Partial card number (BIN + Last 4) as the full card number is not available for the transaction due to security reasons.
**Currencies ID by ISO 4217.
***All DateTime fields in request are delivered using ISO8601 DateTime format. Transaction date and time stamp are in GMT. Time part and timezone offset could be absent as described in ISO8601. Below are all cases:
- YYYY-MM-DD no timezone offset, assumed to be GMT
- YYYY-MM-DDTHH:MM:SS no timezone offset, assumed to be GMT
- YYYY-MM-DDTHH:MM:SS+03:00 DateTime in GMT + 3 hours