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.

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
Authentication	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
alert_action	String	Action to be taken on the merchant system - REFUND - CANCEL - REVIEW - MATCHED - RESOLVED 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.
provider	String	The name of the provider the alert originated from.
txdetails	String	JSON array containing orderid and transactionid when a matched refund is done
tx_details[].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
tx_details[].transaction_action	String	JSON Object that represents the action performed by dispute intelligence.
tx_details[].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
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 / SID that the alert belongs to.
retailer*	String	The TxShield Retailer / RID 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.
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 tx_details[].duplicate_alertid and tx_details[].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 will be
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&currency=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.

[{
        "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.

[{
        "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.

[{
        "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.

[{
        "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