# Notification of a New Alert The notification of a new alert will notify the merchant that a new alert has been received, and the details for the alert.\ \ The merchant must provide TxShield with the URL that they want the new alert notifications sent to. This must be a https URL.\ The merchant can also, and it's also strongly recommended, that they protect the endpoint with a long lived bearer token that they provide to TxAlert.\ \ If post to the url fails, the system reties every 12hr, 0th minute of the hour (UTC time). \ Post retry stops when\ a) If the time is more than 72hrs from the time we received the alert\ b) if alerts outcome gets updated. ## Notification of a new alert `POST` `https://{merchant_supplied_url}` The data in this call is sent as x-www-form-urlencoded data. #### Headers | Name | Type | Description | | ------------- | ------ | ------------ | | Authorization | String | Bearer Token | #### Request Body | Name | Type | Description | | -------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | card | string | Masked or unmasked card number | | transaction\_timestamp | DateTime | Authentication date/time for the transaction | | descriptor | String | The merchant descriptor is the description as seen on the card holders’ statement | | amount | String | Transaction amount | | currency | String | Transaction currency | | arn | String | Acquirer Reference Number (ARN) is a unique 23-digit number that tags a card transaction when it goes from the merchant bank (acquiring bank) through the card scheme to the cardholders’ bank | | alert\_id | String | Alert ID from TxShield. This ID should be used when sending status updates | | alert\_type | String | Type of the alert or event - DISPUTE - DISPUTE\_RDR - DISPUTE\_NOTICE - CANCEL - FRAUD\_NOTICE - FRAUD | | alert\_action | String | Action to be taken on the merchant system - REFUND - CANCEL - REVIEW - MATCHED - RESOLVED - DECLINED The action required by the merchant to take, for this alert. Or in the case of an alert\_type of DISPUTE\_RDR, the action that has already been taken. | | auth\_code | String | auth\_code is sent by the alert provider. TxShield will send the same auth\_code to the merchant. In some cases, the auth\_code can be empty. | | descriptor\_id | String | descriptor\_id is a code given by the merchant for each descriptor. TxShield will send this descriptor code with every alert sent to the merchant. The idea of this code is to make the merchant system search its transactions faster. This ID is not used in TxShield for any of its processes. This is treated as a merchant reference code. | | matched\_enrolled\_descriptor | String | enrolled descriptor which was matched to the alert descriptor | | mid | Number | Mid from TxShield that the alert belongs to. | | rid | Number | Rid from Txshield that the alert belongs to. | | sid | Number | Sid from Txshield that the alert belongs to. | | provider | String | The name of the provider the alert originated from. | | txdetails | String | JSON array | | txdetails\[].alert\_transaction | String |

JSON Object that represents the original transaction the alert is raised for, with the payment processors details . The 4 fields inside the object are from the payment gateway. If null, no direct match could be found
\* only available for dispute intelligence matches

| | txdetails\[].transaction\_action | String |

JSON Object that represents the action performed by dispute intelligence.
\* only available for dispute intelligence matches

| | txdetails\[].transaction\_potential\_matches | String |

JSON array of all the potential matches that could be found in the payment gateway. If empty, no matches are found
\* only available for dispute intelligence matches

| | dispute\_condition\_code\_reason | String | If we have a text based explanation for the condition\_code we will forward that here. This will not always be filled even if there is a condition\_code | | condition\_code | String | If the Alert Provider sent a Condition Code for why the alert was raised, we will forward the code in this field. | | site | String | The TxShield Site name that the alert belongs to. | | retailer | String | The TxShield Retailer name that this alert belongs to | | issuer\_name | String | The credit card issuers name. Either a string or empty. | | provider\_case\_id | String | The alert providers identifier for the alert | | alert\_age | String | The alert age as sent in by the alert provider | | alert\_transactionid | String | The transaction id that this alert is for, as sent in by the alert provider. | | dispute\_amount | String | Case amount | | dispute\_currency | String | Case amount currency | | tier | String | The billing tier for the alert | | alert\_date | DateTime | Received date/time for the alert | | is\_duplicate | String | if alert is a duplicate, the value will be 'yes' and txdetails\[].duplicate\_alertid and txdetails\[].comment will have details | | txdetails\[].duplicate\_alertid | String | If alert is a duplicate of another alert, this field will have alertid of the duplicate | | txdetails\[].comment | String |

If alert is a duplicate of another alert, the comment will have the details
In case of DECLINED DISPUTE\_RDR, this field will have the status code of the decline

| | bin | String | if alert is DISPUTE\_RDR, Acquirer BIN info | | caid | String | CAID info | | rdr\_reason\_code | String | In case of DECLINED DISPUTE\_RDR, this field will have the status code of the decline | ### Example **Headers** ``` Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: {BEARER_TOKEN_VALUE_TO_BE_GIVEN_BY_THE_MERCHANT} ``` #### Data -full This is an example of the full data sent with a new alert call. The data in this call is sent as x-www-form-urlencoded data. ``` card=411111%2A%2A%2A%2A%2A%2A1111&transaction_timestamp=2024-01-17+00%3A00%3A00&descriptor=Payshield&amount=123.0¤cy=USD&alert_id=340739&alert_type=FRAUD&alert_action=REFUND&alert_date=2024-01-17+22%3A54%3A42&arn=65678998765&auth_code=rtv451&descriptor_id=Test&retailer=Test+Retailer&site=Test+Site&condition_code=10.1&dispute_condition_code_reason=EMV+Liability+Shift+Counterfeit+Fraud&issuer_name=National+Bank&provider_case_id=687c4760-9f05-4105-90ad-0d6cca087128&alert_age=009&alert_transactionid=GUI898789876JKYHNJ&tier=T2provider=ethoca ``` #### Data - txdetails: no match found, no refund processed example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field. ```json [{ "alert_transaction": null, "transaction_action": null, "transaction_potential_matches": null } ] ``` #### Data - txdetails: match found, no refund processed example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field. ```json [{ "alert_transaction": { "payment_gateway_reference": "1233778452", "payment_gateway_reference2": "order_123456", "payment_gateway_tx_type": "sale", "payment_gateway_transaction_date": "" }, "transaction_action": null, "transaction_potential_matches": null } ] ``` #### Data - txdetails: match found, refund processed example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field. ```json [{ "alert_transaction": { "payment_gateway_reference": "1233778452", "payment_gateway_reference2": "order_123456", "payment_gateway_tx_type": "sale", "payment_gateway_transaction_date": "" }, "transaction_action": { "payment_gateway_reference": "1233778453", "payment_gateway_reference2": "order_123456", "payment_gateway_tx_type": "refund", "payment_gateway_transaction_date": "" }, "transaction_potential_matches": null } ]json ``` #### Data - txdetails: no exact match found / unable to determine exact match, potential matches found example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field. ```json [{ "alert_transaction": null, "transaction_action": null, "transaction_potential_matches": [{ "payment_gateway_reference": "1233778452", "payment_gateway_reference2": "order_123456", "payment_gateway_tx_type": "sale", "payment_gateway_transaction_date": "" }, { "payment_gateway_reference": "1233778454", "payment_gateway_reference2": "order_123457", "payment_gateway_tx_type": "sale", "payment_gateway_transaction_date": "" }, { "payment_gateway_reference": "1233778455", "payment_gateway_reference2": "order_123458", "payment_gateway_tx_type": "sale", "payment_gateway_transaction_date": "" } ] } ] ``` ### Payment Processor Field Mapping When a new alert is pushed to the merchant, *and the merchant is using dispute intelligence*, TxAlert will map several of the txdetails fields directly to values from the payment processor.\ \ A list of the fields and their mappings can be found in the [Appendix here](https://docs.payshield.ai/txalerts-dispute-alerts/appendix/dispute-intelligence-payment-processor-field-mappings)