Loading...
This guide focuses on how to use Fraud Filter for both direct API integrations and for integrations via Hosted Fields and the Drop-In User Interface (UI). First, we test some configured fraud rules and view the fraud-related fields in the response. We then send a Hold request to investigate a transaction and eventually release it to its original status after determining that it’s not actually fraudulent.
For more information on Fraud Management, see our Overview.
The Fraud Filter feature must be configured and enabled via the Ecommerce Portal (RealControl) under the Fraud Management section before being used via the API or Hosted Fields / Drop-In UI. For more information, see Fraud Management FAQs for Ecommerce Help.
To access Ecommerce Portal (RealControl):
Test account: https://realcontrol.sandbox.realexpayments.com
Live account: https://realcontrol.realexpayments.com
Once you’ve set up a few Fraud Filter rules, you can then test them and note the different fraud-related fields returned in the response.
You can set a specific rule on a per-transaction basis by using the risk_assessment object in the request as shown in the example below.
The following table describes the fraud-related fields used in the request.
| Field | Description | Example(s) |
|---|---|---|
| risk_assessment.mode | Sets the overall transactional-level fraud mode. | PASSIVE/ACTIVE/OFF |
| risk_assessment.rules.reference | Unique identifier for a rule. | 5c52428c-1f73-4fdf-ae53-ff62857f89d8 |
| risk_assessment.rules.mode | Sets the mode at a per fraud rule level. | PASSIVE/ACTIVE/OFF |
The transaction response includes a risk_assessment object with details of the fraud rules that were carried out on the transaction.
The overall transaction mode is returned as either PASSIVE, ACTIVE, or OFF. The overall result is returned as either ACCEPTED, REJECTED, NOT_EXECUTED, or PENDING_REVIEW.
The outcome of passing the transaction through the Fraud Filter is included in the transaction response. You can check the overall Fraud Filter result and each individual rule outcome by using the rule's unique identifier.
{
"id": "TRN_RO1H0eICPZFJt8xYffvio8miTg0tUy_114123459878",
"time_created": "2023-03-23T11:03:43.555Z",
"type": "SALE",
"status": "PREAUTHORIZED",
"channel": "CNP",
"capture_mode": "LATER",
"amount": "3000",
"currency": "EUR",
"country": "IE",
"merchant_id": "MER_7e3e2c7df34f42819b3edee31022ee3f",
"merchant_name": "Sandbox_merchant_3",
"account_id": "TRA_c9967ad7d8ec4b46b6dd44a61cde9a91",
"account_name": "transaction_processing",
"reference": "TRANS-20180114123459878",
"payment_method": {
"result": "00",
"message": "[ test system ] Authorised",
"entry_mode": "MOTO",
"card": {
"brand": "VISA",
"masked_number_last4": "XXXXXXXXXXXX1112",
"authcode": "12345",
"brand_reference": "tmKvCwKEVQhX6PWw",
"brand_time_created": "",
"tag_response": "",
"cvv_result": "MATCHED",
"avs_address_result": "MATCHED",
"avs_postal_code_result": "MATCHED",
"avs_action": "",
"provider": {
"result": "00",
"cvv_result": "M",
"avs_address_result": "M",
"avs_postal_code_result": "M"
}
}
},
"risk_assessment": [
{
"mode": "ACTIVE",
"result": "PENDING_REVIEW",
"rules": [
{
"reference": "5c52428c-1f73-4fdf-ae53-ff62857f89d8",
"description": "unknown rule",
"mode": "ACTIVE",
"result": "ERROR"
},
{
"reference": "0c93a6c9-7649-4822-b5ea-1efa356337fd",
"description": "Cardholder Name Rule",
"mode": "ACTIVE",
"result": "ACCEPTED"
},
{
"reference": "a539d51a-abc1-4fff-a38e-b34e00ad0cc3",
"description": "CardNumber block",
"mode": "ACTIVE",
"result": "PENDING_REVIEW"
},
{
"reference": "d023a19e-6985-4fda-bb9b-5d4e0dedbb1e",
"description": "Amount test",
"mode": "ACTIVE",
"result": "ACCEPTED"
}
]
}
],
"batch_id": "",
"action": {
"id": "ACT_RO1H0eICPZFJt8xYffvio8miTg0tUy",
"type": "PREAUTHORIZE",
"time_created": "2023-03-23T11:03:43.555Z",
"result_code": "SUCCESS",
"app_id": "07V8FC6G7kZvdUBpqGYWBBgnWdQ59HOv",
"app_name": "Sandbox Merchant 3"
}
}The following table describes the fraud-related fields returned in the response.
| Field | Description | Example(s) | |
|---|---|---|---|
| risk_assessment.mode | Returns the overall transactional-level fraud mode. | PASSIVE/ACTIVE/OFF | |
| risk_assessment.result | Returns the result of the overall fraud check. | ACCEPTED/REJECTED/NOT_EXECUTED/PENDING_REVIEW | |
| risk_assessment.rules.reference | Returns the rule's unique identifier. | 5c52428c-1f73-4fdf-ae53-ff62857f89d8 | |
| risk_assessment.rules.description | Returns a system-generated description of the rule. | Amount Check | CardNumber Check |
| risk_assessment.rules.mode | Sets the mode at a per fraud rule level. | PASSIVE/ACTIVE/OFF | |
| risk_assessment.rules.result | Returns the result of the individual fraud check. | ACCEPTED/REJECTED/NOT_EXECUTED/PENDING_REVIEW |
If you suspect a transaction is fraudulent and requires further investigation, you can send a Hold request. If the transaction was already placed in the queue to be included in the next settlement file or batch, this will remove it from the queue until the transaction is released (see Step 4).
The following field is returned in the response.
| Field | Description | Example(s) |
|---|---|---|
| reason_code | The reason that the transaction is being held. | FRAUD/OUTOFSTOCK/OTHER/NOT_GIVEN |
If you decide that a transaction is not fraudulent or you have held one in error, you can send a Release request. This will return the transaction to its original status (awaiting settlement or in the queue for the next batch). Or, if you decide not to proceed with the transaction, you can reverse (void) it (see Transactions in the API Explorer). You don’t need to release the transaction before reversing it.
The following field is returned in the response.
| Field | Description | Example(s) |
|---|---|---|
| reason_code | The reason that the transaction is being released. | FALSE_POSITIVE/IN_STOCK/OTHER/NOT_GIVEN |