The Global Payments Fraud Filter enables merchants to automatically Pass, Hold, or Block transactions based on the result of one or more rule results. This functionality is configured via the Fraud Management section in Ecommerce Portal.

It is important to note that any changes made to the Fraud Filter in Ecommerce Portal will impact the result returned in the API response. You will need to ensure that any changes don't adversely affect transaction processing in your application. For example:

  • If the Fraud Filter is turned off in Ecommerce Portal, the data will not be returned in the transaction response. If the mode is changed between Active and Passive, then this change will be reflected in the transaction response.
  • If a new rule is added, an additional element will be returned in the response. Similarly if a rule is deleted, the result will be removed from the response.
  • If a rule name is edited, the name will change to the new value in the response; the rule ID will remain the same.

Fraud Filter and data submission

With Fraud Filter, you can supply additional information in the request that you can set rules against. This includes the customer's IP address, billing and shipping details, and specific product codes.

For Authorization and Validate (OTB) requests, you can change the Fraud Filter Mode in the request. This will change the mode used for the current transaction only.

Individual rule setting

You can change the Fraud Filter Mode for an individual rule, based on the rule ID. This will change the mode used for an individual rule, for the current transaction only. All other rules will use the Fraud Filter Mode set in Ecommerce Portal or at the request level.

The Fraud Filter Mode works in a hierarchical manner. The value configured in Ecommerce Portal sets the highest level of activity that can be applied. For example, if the mode in Ecommerce Portal is set to Active, at a request or rule level it can be set to Active, Passive, or Off. However, if the mode in Ecommerce Portal is set to Passive, at a request or rule level it can only be set to Passive or Off.

The table below shows each level that the mode can be set and the corresponding outcome when Ecommerce Portal is set to Active.

Ecommerce Portal Setting: ACTIVE
Request Individual Rule Individual Rule Outcome
ACTIVE ACTIVE ACTIVE
- PASSIVE PASSIVE
- OFF OFF
PASSIVE ACTIVE PASSIVE
- PASSIVE PASSIVE
- OFF OFF
OFF ACTIVE OFF
- PASSIVE OFF
- OFF OFF

The table below shows each level that the mode can be set and the corresponding outcome when Ecommerce Portal is set to Passive.

Ecommerce Portal Setting: PASSIVE
Mode set in Request Mode set for Individual Rule Outcome for Individual Rule
ACTIVE ACTIVE PASSIVE
- PASSIVE PASSIVE
- OFF OFF
PASSIVE ACTIVE PASSIVE
- PASSIVE PASSIVE
- OFF OFF
OFF ACTIVE OFF
- PASSIVE OFF
- OFF OFF

The table below shows each level that the mode can be set and the corresponding outcome when Ecommerce Portal is set to Off.

Ecommerce Portal Setting: OFF
Mode set in Request Mode set for Individual Rule Outcome for Individual Rule
ACTIVE ACTIVE OFF
- PASSIVE OFF
- OFF OFF
PASSIVE ACTIVE OFF
- PASSIVE OFF
- OFF OFF
OFF ACTIVE OFF
- PASSIVE OFF
- OFF OFF
api-fraud-filter

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">1001</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>0519</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <!-- Begin Fraud Management Elements -->
  <fraudfilter mode="PASSIVE"/>
  <tssinfo>
    <custnum>E8953893489</custnum>
    <prodid>SID9838383</prodid>
    <varref>Car Part HV</varref>
    <custipaddress>123.123.123.123</custipaddress>
    <address type="billing">
      <code>321|456</code>
      <country>GB</country>
    </address>
    <address type="shipping">
      <code>852|369</code>
      <country>IE</country>
    </address>
  </tssinfo>
  <!-- End Fraud Management Elements -->
  <autosettle flag="1"/>
  <sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>

Address Verification Service

The Address Verification Service (AVS) verifies the cardholder's address by checking the information at the time of sale against the Issuer's records.

api-avs

This functionality is not supported by all Issuers and is only available for cardholders in the United States, Canada, and the United Kingdom. Global Payments supports this functionality; however, not all Acquirers do. For more information, contact our Support Team.

info

If a transaction fails an AVS check, it will not automatically be declined. It's an advisory service and requires that the details of non-matched transactions be checked by your application. AVS data is passed in the billing code address fields and must be formatted correctly depending on the billing country of the cardholder. We've outlined the different formats below.

Country Construction Sample Address Sample Billing Code
US or CA Concatenate the postcode and first line of the customer's billing address with a '|' in the middle. Flat 123
House 456
Chicago
50001
United States		 "50001|Flat 123"
UK Concatenate just the digits from the postcode and first line of the customer's billing address with a '|' in the middle. Flat 456
House 123
Halifax
WB3 A21
United Kingdom		 "321|456"

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">1001</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>0519</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <!-- Begin AVS Elements -->
  <tssinfo>
    <address type="billing">
      <code>50001|Flat 123</code>
    </address>
  </tssinfo>
  <!-- End AVS Elements -->
  <autosettle flag="1"/>
  <sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>

Hold

This request will change the transaction status to Hold. If the transaction was successful and due to be included in the next settlement file, this will prevent its inclusion until such a time that the transaction is released. If you're using Delayed Capture, the transaction must be released and then captured before it will be included in the settlement file.

Sample request

api-hold
<?xml version="1.0" encoding="UTF-8"?>
<request type="hold" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>dKH-d6mTSmCuciHLm_QfEg</orderid>
  <pasref>14612286471949679</pasref>
  <reasoncode>FRAUD</reasoncode>
  <sha1hash>86daf98b4ce6f5d463572c3a0692eceaace35740</sha1hash>
</request>

Release

If a transaction is set to Hold, the release request will return the transaction to its original status. For example, if a transaction was set to Auto-Capture, then the release request will return it to the queue of transactions to be included in the next settlement file. If you're using Multi or Delayed Capture the transaction will simply return to that status until it is captured. Transactions that are held must be released before they are captured.

Sample request

api-release
<?xml version="1.0" encoding="UTF-8"?>
<request type="release" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>dKH-d6mTSmCuciHLm_QfEg</orderid>
  <pasref>14612286471949679</pasref>
  <reasoncode>FALSEPOSITIVE</reasoncode>
  <sha1hash>36b168a9fa577df04684b5a20baad17483b8e11c</sha1hash>
</request>

Decision Manager

To enrich the functionality of the Fraud Filter, we've partnered with Cybersource to use their Decision Manager product. Our guide describes how your application can make use of the advanced fraud screening provided by Decision Manager along with the Global Payments API. Use our guide along with Cybersource's Decision Manager developer guide: Using the Simple Order API. You can find it on their website.

Before you set up the additional elements, you'll need to configure your Decision Manager credentials in the Client Settings section of Ecommerce Portal. The elements defined in this guide are in addition to those outlined above.

    Sample request

    api-additional-fields

    For users of the XML API: the following elements, if included in the request, must appear in the sequence outlined in the sample below.

    info
    <?xml version="1.0" encoding="UTF-8"?>
<request timestamp="20170414100216" type="auth">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">16400</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>1025</expdate>
    <type>VISA</type>
    <chname>James Mason</chname>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <sha1hash>5245df9edbfc10b6dceb74ca2f616fd9e15271a3</sha1hash>
  <tssinfo>
    <address type="billing">
      <street1>Flat 123</street1>
      <street2>House 456</street2>
      <city>Halifax</city>
      <postalcode>W6 9HR</postalcode>
      <state>West Yorkshire</state>
      <country>GB</country>
    </address>
    <address type="shipping">
      <firstname>Philip</firstname>
      <lastname>Marlowe</lastname>
      <phone>+3538547854</phone>
      <shippingmethod>threeday</shippingmethod>
      <street1>Flat 456</street1>
      <street2>House 321</street2>
      <city>Dublin</city>
      <postalcode>6</postalcode>
      <state>Leinster</state>
      <country>IE</country>
    </address>
  </tssinfo>
  <customer>
    <customerid>0f357b45-9aa4-4453-a685-c69232e9024f</customerid>
    <firstname>James</firstname>
    <lastname>Mason</lastname>
    <dateofbirth>01011980</dateofbirth>
    <customerpassword>VerySecurePassword</customerpassword>
    <email>james.mason@example.com</email>
    <domainname>example.com</domainname>
    <phonenumber>+3535611177</phonenumber>
    <devicefingerprint>sessionId</devicefingerprint>
  </customer>
  <products>
    <product>
      <productid>SKU251584</productid>
      <productname>Magazine Subscription</productname>
      <quantity>12</quantity>
      <unitprice>1200</unitprice>
      <gift>true</gift>
      <type>subscription</type>
      <risk>low</risk>
    </product>
    <product>
      <productid>SKU8884784</productid>
      <productname>Charger</productname>
      <quantity>10</quantity>
      <unitprice>2000</unitprice>
      <gift>false</gift>
      <type>electronic_good</type>
      <risk>high</risk>
    </product>
  </products>
  <fraud>
    <dm>
      <billtohostname>example.com</billtohostname>
      <billtohttpbrowsercookiesaccepted>true</billtohttpbrowsercookiesaccepted>
      <billtohttpbrowseremail>jamesmason@example.com</billtohttpbrowseremail>
      <billtohttpbrowsertype>Mozilla</billtohttpbrowsertype>
      <billtoipnetworkaddress>123.123.123.123</billtoipnetworkaddress>
      <businessrulesscorethreshold>40</businessrulesscorethreshold>
      <billtopersonalid>741258963</billtopersonalid>
      <invoiceheadertendertype>consumer</invoiceheadertendertype>
      <invoiceheaderisgift>true</invoiceheaderisgift>
      <decisionmanagerprofile>DemoProfile</decisionmanagerprofile>
      <invoiceheaderreturnsaccepted>true</invoiceheaderreturnsaccepted>
      <itemhosthedge>High</itemhosthedge>
      <itemnonsensicalhedge>High</itemnonsensicalhedge>
      <itemobscenitieshedge>High</itemobscenitieshedge>
      <itemphonehedge>High</itemphonehedge>
      <itemtimehedge>High</itemtimehedge>
      <itemvelocityhedge>High</itemvelocityhedge>
    </dm>
  </fraud>
  <custom>
    <field01>fieldValue01</field01>
    <field02>fieldValue02</field02>
  </custom>
</request>

    Decision Manager - Device Fingerprinting

    The Device Fingerprinting service of Decision Manager gathers information about the customer devices that use your mobile app or place orders on your website. Use this unique identifier to consistently identify the location of a customer's device, despite whatever identity masking techniques they may use (for example, a VPN or proxy). For more information, see Cybersource's Device Fingerprinting Guide, which is available on their website.

    Cybersource provides SDKs for iOS and Android, along with sample scripts for web applications. In each case, the Session ID used must be passed to Global Payments in the request. This must be a unique identifier for each transaction. The examples below show the One-Pixel Image and JavaScript Code for websites.

    Sample embedded scripts

    <!-- One-Pixel Image -->
<p></p>
<img src="https://www.fingerprintingserver.com/fp/clear.png?org_id=<ORG ID>&session_id=<MERCHANT ID><SESSION ID>&m=2" alt="">

<!-- JavaScript -->
<script src="https://www.fingerprintingserver.com/fp/check.js?org_id=<ORG ID>&session_id=<MERCHANT ID><SESSION ID>"></script>

     

    The scripts should be embedded—for example, on the checkout page that initiates the transaction. The value you pass in the request will be the Session ID included in the scripts (it's supplied as part of the Customer fields). In our example below, we're using a random 32-character string as our Session ID.

    The Device Fingerprint service provides the following information in Decision Manager: Date Device First Seen, Application Type, Time on Page, True IP Address. For apps, Device Longitude and Latitude are available, as well as whether the device is Jailbroken.

    Sample request

    api-device-fingerprinting
    <?xml version="1.0" encoding="UTF-8"?>
<request timestamp="20170414100216" type="auth">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">16400</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>1025</expdate>
    <type>VISA</type>
    <chname>James Mason</chname>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <sha1hash>5245df9edbfc10b6dceb74ca2f616fd9e15271a3</sha1hash>
  <customer>
    <customerid>0f357b45-9aa4-4453-a685-c69232e9024f</customerid>
    <firstname>James</firstname>
    <lastname>Mason</lastname>
    <email>james.mason@example.com</email>
    <phonenumber>+3535611177</phonenumber>
    <devicefingerprint>kyhb-hc1sa5jdf-tjbqec-uz19a-5n5b</devicefingerprint>
  </customer>
</request>

    Decision Manager - Travel Data

    You can use Decision Manager to screen orders that contain travel data such as details of the journey or of the main passenger. The elements defined in this article are in addition to the standard Decision Manager elements. All travel data is optional but if passenger record is included a Unit Price must be defined.

    Sample request

    api-travel-data
    <?xml version="1.0" encoding="UTF-8"?>
<request timestamp="20170414100216" type="auth">
  <merchantid>Merchant ID</merchantid>
  <account>internet</account>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">200000</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>1025</expdate>
    <type>VISA</type>
    <chname>James Mason</chname>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <sha1hash>5245df9edbfc10b6dceb74ca2f616fd9e15271a3</sha1hash>
  <tssinfo>
    <address type="billing">
      <street1>Flat 123</street1>
      <city>Halifax</city>
      <postalcode>W6 9HR</postalcode>
      <country>GB</country>
    </address>
  </tssinfo>
  <customer>
    <firstname>James</firstname>
    <lastname>Mason</lastname>
    <email>james.mason@example.com</email>
  </customer>
  <products>
    <product>
      <unitprice>200000</unitprice>
    </product>
  </products>
  <supplementarydata>
    <item type="pnr">
      <field15>Passenger 1</field15>
      <field16>Standard</field16>
      <field17>ADT</field17>
      <field18>james.mason@example.com</field18>
      <field19>James</field19>
      <field20>Mason</field20>
      <field21>+3535611177</field21>
    </item>
    <item type="leg">
      <field02>LAS</field02>
      <field03>LGW</field03>
      <field08>231217</field08>
      <field11>0335</field11>
      <field14>Round Trip</field14>
      <field15>GMT</field15>
    </item>
    <item type="leg">
      <field02>LHR</field02>
      <field03>LOS</field03>
      <field08>241217</field08>
      <field11>1035</field11>
      <field14>Round Trip</field14>
      <field15>GMT</field15>
    </item>
    <item type="leg">
      <field02>LOS</field02>
      <field03>LHR</field03>
      <field08>170118</field08>
      <field11>1100</field11>
      <field14>Round Trip</field14>
      <field15>GMT</field15>
    </item>
    <item type="leg">
      <field02>LGW</field02>
      <field03>LAS</field03>
      <field08>180118</field08>
      <field11>1010</field11>
      <field14>Round Trip</field14>
      <field15>GMT</field15>
    </item>
  </supplementarydata>
</request>

    Generate hash

    Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulting string to the request.

    generate-hash

    In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the <sha256hash> tag instead of the <sha1hash> tag. For more information, contact our support team at ecomsupport@globalpay.com.

    info

    Build the Request hash

    Use the drop-down arrow below to select a request type: Fraud Filter and data submission, Hold, or Release. After making a selection, the steps on how to build the request hash for that type are provided.

    Check hash

    Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulting string to the request.

    Check the Response hash

    Use the drop-down arrow below to select a request type: Fraud Filter and data submission, Hold, or Release. After making a selection, the steps on how to check the response hash for that type are provided.

    check-hash
    Show Content Nav
    On
    Tags