Loading...
In this API reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on Fraud Management, see our Overview.
Our 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 more information, see Fraud Filter - Overview.
<?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>Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.
Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]
| Element/Field | Category | Format | Type | Length | Description |
|---|---|---|---|---|---|
| Timestamp | string | numeric | M | 14 | Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK. |
| Merchant ID | string | alphanumeric | M | 1-50 | Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.] |
| Account | string | alphanumeric | O | 0-30 | The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.] |
| Channel | string | enum | O | Specify how a transaction is to be processed. Compatible with us and certain other acquirers. Allowed values: ECOM - Ecommerce MOTO - Mail Order/Telephone Order | |
| Order Id | string | alphanumeric | M | 1-50 | A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-] |
| Currency | string | ISO 4217 | M | 3 | The processing currency of the transaction. Please see the list of Currency Codes. |
| Card Number | string | numeric | M | 12-19 | The full Primary Account Number (PAN) of the card. |
| Expiry Date | string | MMYY | M | 4 | The expiry date of the card. |
| Cardholder Name | string | alphanumeric | M | 1-100 | The cardholder name. |
| Card Type | string | enum | M | 0-15 | Please see the list of supported Card Type Strings. |
| Security Code Number | string | numeric | O | 0-4 | The 3 digit number on the reverse of the card (known as CVC for Visa and CVV2 for MasterCard). For American Express the code is 4 digits long. |
| Presence Indicator | integer | C | 0-1 | Used to specify whether the Security Code is being submitted. Allowed values: 1 - cvn present - cvn illegible - cvn not on card - cvn not requested |
<response timestamp="20180802120019">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
<authcode>12345</authcode>
<result>00</result>
<cvnresult>M</cvnresult>
<batchid>319623</batchid>
<message>[ test system ] AUTHORISED</message>
<pasref>14610544313177922</pasref>
<timetaken>0</timetaken>
<authtimetaken>0</authtimetaken>
<srd>MMC0F00YE4000000715</srd>
<cardissuer>
<bank>AIB BANK</bank>
<country>IRELAND</country>
<countrycode>IE</countrycode>
<region>EUR</region>
</cardissuer>
<fraudresponse mode="PASSIVE">
<result>PASS</result>
<rules>
<rule name="Customer IP List" id="478a55db-5430-4c2a-afca-7dde181eb9f4">
<action>PASS</action>
</rule>
<rule name="Card Numbers" id="cf609cf9-9e5a-4700-ac69-8aa09c119305">
<action>PASS</action>
</rule>
</rules>
</fraudresponse>
<sha1hash>3ebd3655d378eb32a44b015d26c32c28111e8fb0</sha1hash>
</response>| Element/Field | Category | Format | Description |
|---|---|---|---|
| Timestamp | string | numeric | Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK. |
| Merchant ID | string | alphanumeric | Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.] |
| Account | string | alphanumeric | The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.] |
| Order Id | string | alphanumeric | A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-] |
| Authcode | string | alphanumeric | The authorization code returned by the Issuer. Allowed characters: [a-zA-Z0-9␣] |
| Result | string | numeric | The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes. |
| CVN Result | string | enum | The result of the Security Code (CVN, CVV) check: M - Matched N - Not Matched I - Not checked due to circumstances U - Not checked - issuer not certified P - Not Processed |
| Batch Id | integer | The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests. | |
| Message | string | alphanumeric | Text of the response from the Gateway, Acquirer, Issuer or Payment Method. |
| Payments Reference | string | alphanumeric | A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣] |
| Time Taken | integer | The total time taken to process the request in seconds. | |
| Auth Time Taken | integer | The total time taken by the Acquirer to process the request in seconds. | |
| Bank | string | alphanumeric | The name of the card Issuer. |
| Country | string | alphanumeric | The country of the card Issuer. |
| Country Code | string | alphanumeric | Country code of the card Issuer. |
The Address Verification Service (AVS) verifies the cardholder's address by checking the information at the time of sale against the Issuer's records.
This functionality is not supported by all Issuers and is only available for cardholders in the United States, Canada, and the United Kingdom.
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" |
<?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><response timestamp="20180731090859">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
<authcode>12345</authcode>
<result>00</result>
<cvnresult>M</cvnresult>
<avspostcoderesponse>M</avspostcoderesponse>
<avsaddressresponse>M</avsaddressresponse>
<batchid>319623</batchid>
<message>[ test system ] AUTHORISED</message>
<pasref>14610544313177922</pasref>
<timetaken>1</timetaken>
<authtimetaken>0</authtimetaken>
<srd>MMC0F00YE4000000715</srd>
<cardissuer>
<bank>AIB BANK</bank>
<country>IRELAND</country>
<countrycode>IE</countrycode>
<region>EUR</region>
</cardissuer>
<sha1hash>8f4dfe7460ce91f78a144a2ed4f334617feaaab4</sha1hash>
</response>| Element/Field | Category | Format | Description |
|---|---|---|---|
| AVS Postcode Response | string | enum | The result of the Address Verification Service (AVS) check on the postcode and first line of the billing address: M - Matched N - Not Matched I - Problem with check U - Unable to check - Issuer not certified, for example P - Partial Match Available for US, CA and GB cardholders only. |
| AVS Address Response | string | enum | See AVS Postcode Response |
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.
<?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>Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.
Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]
| Element/Field | Category | Format | Type | Length | Description |
|---|---|---|---|---|---|
| Timestamp | string | numeric | M | 14 | Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK. |
| Merchant ID | string | alphanumeric | M | 1-50 | Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.] |
| Account | string | alphanumeric | O | 0-30 | The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.] |
| Order Id | string | alphanumeric | M | 1-50 | A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-] |
| Payments Reference | string | alphanumeric | M | 0-50 | A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣] |
| Reason Code | string | enum | O | Used to indicate the reason for a transaction action. If no value is supplied the default reason code NOTGIVEN will be applied. Allowed values: FRAUD OUTOFSTOCK OTHER NOTGIVEN | |
| Sha1hash | string | alphanumeric | M | 40 | The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F] |
<response timestamp="20180903100255">
<merchantid>Merchant ID</merchantid>
<account>internet</account>
<orderid>dKH-d6mTSmCuciHLm_QfEg</orderid>
<result>00</result>
<message>Held Successfully</message>
<pasref>14612331056825417</pasref>
<sha1hash>f2bfcf445514381d79a7a0e86b5b4298571ba66b</sha1hash>
</response>| Element/Field | Category | Format | Description |
|---|---|---|---|
| Timestamp | string | numeric | Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK. |
| Merchant ID | string | alphanumeric | Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.] |
| Account | string | alphanumeric | The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.] |
| Order Id | string | alphanumeric | A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-] |
| Message | string | alphanumeric | Text of the response from the Gateway, Acquirer, Issuer or Payment Method. |
| Payments Reference | string | alphanumeric | A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣] |
| Reason Code | string | enum | Used to indicate the reason for a transaction action. If no value is supplied the default reason code NOTGIVEN will be applied. Allowed values: FRAUD OUTOFSTOCK OTHER NOTGIVEN |
| Sha1hash | string | alphanumeric | The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F] |
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.
<?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>Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.
Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]
| Element/Field | Category | Format | Type | Length | Description |
|---|---|---|---|---|---|
| Timestamp | string | numeric | M | 14 | Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK. |
| Merchant ID | string | alphanumeric | M | 1-50 | Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.] |
| Account | string | alphanumeric | O | 0-30 | The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.] |
| Order Id | string | alphanumeric | M | 1-50 | A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-] |
| Payments Reference | string | alphanumeric | M | 0-50 | A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣] |
| Reason Code | string | enum | O | Used to indicate the reason for a transaction action. If no value is supplied the default reason code NOTGIVEN will be applied. Allowed values: FALSEPOSITIVE INSTOCK OTHER > NOTGIVEN | |
| Sha1hash | string | alphanumeric | M | 40 | The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F] |
<response timestamp="20180903100255">
<merchantid>Merchant ID</merchantid>
<account>internet</account>
<orderid>dKH-d6mTSmCuciHLm_QfEg</orderid>
<result>00</result>
<batchid>319970</batchid>
<message>Released Successfully</message>
<pasref>14612357998755963</pasref>
<sha1hash>973e1d53a1f3f2201ed4dda349d3b6c6f2197416</sha1hash>
</response>| Element/Field | Category | Format | Description |
|---|---|---|---|
| Timestamp | string | numeric | Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK. |
| Merchant ID | string | alphanumeric | Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.] |
| Account | string | alphanumeric | The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.] |
| Order Id | string | alphanumeric | A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-] |
| Result | string | numeric | The result code indicating the outcome of the transaction. Please see the list of Messages & Error Codes. |
| Batch Id | integer | The ID of the batch to be sent to the Acquirer. Returned in the case of AutoSettle (AutoCapture) Authorizations, Capture (Settle) and Refund requests. | |
| Message | string | alphanumeric | Text of the response from the Gateway, Acquirer, Issuer or Payment Method. |
| Payments Reference | string | alphanumeric | A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣] |
| Sha1hash | string | alphanumeric | The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F] |
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 resulted string to the request.
In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the tag instead of the tag. For more information, contact our support team.
Use the tabs below to follow the steps for a certain request type: Fraud Filter and data submission, Hold, or Release.
The blueprint of the hash for this request is:
"timestamp.merchantid.orderid.amount.currency.cardnumber"Based on the XML example above our initial string will be:
"20200205093140.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.1001.EUR.4263970000005262"After step 1, you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882
You'll need to concatenate this with your Shared Secret, for example:
"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269
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 tabs below to follow the steps for a certain 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.
The blueprint of the hash for this response is:
"timestamp.merchantid.orderid.result.message.pasref.authcode"So based on the above example the initial string to check the hash of the response will be:
"20200205093140.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.[ test system ] Authorised.14631546336115597.12345"After step 1, you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882
You'll need to concatenate this with your Shared Secret, for example:
"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269
We create the hash in the same way on our side and send it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha1hash element.
| Fraud Filter Mode | string | enum | O | N/A | Optional parameter used to determine to what degree Fraud Filter executes. If not submitted the Fraud Filter will behave in accordance with the Ecommerce Portal mode configuration. Allowed values: PASSIVE - Execute the rules but do not execute the action detailed in the Fraud Filter overall result (for example, HOLD or BLOCK) OFF - Does not execute the Fraud Filter at all for this transaction. In this case, only the mode is returned in the response. ACTIVE - Execute the action detailed in the Fraud Filter overall result for OTB transactions. |
| Customer Number | string | alphanumeric | O | 0-50 | A unique reference for this customer for example from your CRM system. Allowed special characters: [-.,+@_␣] |
| Product Id | string | alphanumeric | O | 0-50 | The code you assign to the product, for example the SKU. Allowed special characters: [-.,+@_␣] |
| Variable Reference | string | alphanumeric | O | 0-50 | Any reference you also would like to assign to this transaction. Can also be used to pass the Acquirer Statement reference, where supported. Allowed special characters: [-.,+@_␣] |
| Customer IP Address | string | numeric | O | 0-15 | The IP address of the customer's device. Allowed characters: [0-9:] |
| Address Type | string | enum | O | Allowed values: BILLING SHIPPING |
| Billing or Shipping Code | string | alphanumeric | O | 0-30 | The Postal Code concatenated with the first line of the billing or shipping address. The billing code can be used for the Address Verification Service (AVS). Allowed characters: [a-zA-Z0-9_-] |
| Billing or Shipping Country | string | alphanumeric | O | 0-50 | The country of the billing or shipping address. Allowed characters: [a-zA-Z0-9.-] |
| AutoSettle/AutoCapture Flag | string | enum | M | Used to specify the settlement/capture type. Allowed values: 0 - Delayed Settle (Capture) / Authorize, don't automatically add to the settlement file. 1 - Auto Settle (Capture) / Charge, automatically added to the next settlement file. MULTI - Multi Settle (Capture), don't automatically add to the settlement file. Enables multiple settlement/capture requests up to 115% of the original transaction value. |
| Sha1hash | string | alphanumeric | M | 40 | The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F] |
| Region |
| string |
| enum |
| The region the card was issued in: MEA - Middle East/Asia LAT - Latin America US - United States EUR - Europe CAN - Canada A/P - Asia/Pacific |
| Response Mode | string | enum | Indicates the mode the Fraud Filter executed in. The possible values are: ACTIVE - The rules were executed and the fraud result actioned. PASSIVE - The rules were executed but the fraud result was actioned. OFF - Fraud Filter was specifically not executed. ERROR - There was an unexpected error in executing Fraud Filter |
| Sha1hash | string | alphanumeric | The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F] |