Introduction

An implementation manual for the ADIQ Antifraud solution for e-commerce operations as a means of payment. The manual will help developers understand how to implement the solution.

Target Audience

The document has the following Target Audience:

• Developers from the ADIQ customers who intend to implement antifraud.

About Antifraud

In order to minimize the rate of fraud without harming the conversion rate, the payment methods industry has developed antifraud systems. Fraud is growing at the same rate as internet sales, which means that many online stores suffer considerable losses, resulting in the closure of their operations. The challenge is to allow e-shops to grow in sales and control fraud, so it's important to understand possible fraud attempts and how to minimize them.

In e-commerce, antifraud plays an extremely important role in assessing whether the transactions that pass through the virtual store are safe or fraudulent. Antifraud informs the online store of the result of the analysis and the online store then decides whether or not to accept the transaction. Here are the main features that a good antifraud system can offer:

• Intended for credit operations;
• Detailed information about the transaction;
• Origin of the transaction, e.g. IP address;
• Verifies important transaction data using a neural network;
• Uses market rules for fraud management according to the customer's profile;
• Allows the online store to create its own security rules to facilitate management.

The service is available at an additional cost.

How does Antifraud work in real life?

In each transaction, the antifraud system executes more than 260 tests, and here are the main tests:

• IP geolocation – Identifies the IP address of the computer at the time of the transaction;
• Device fingerprinting – identifies the number of the computer being used;
• Positive and negative lists – Allows the online store to create lists of its good and bad buyers;
• Customized fields for your own data – Allows the online store to register information and analyses pertinent to your business model;
• Risk detection through neural models – allows the online store to use the standards established by the tool according to its line of business;
• Speed monitoring – PerAllows the online store to monitor whether certain transaction data, such as the card number, appears in other transactions at short intervals. This can be a major indication of fraud, because in a short interval, a matter of seconds, it is unlikely that the cardholder will be able to make several purchases at different locations using the same data.

Antifraud Flowchart Explained.

Below is a flowchart with a success scenario:

                
                
{
    
    "paymentAuthorization": 
        {
            "returnCode": "0",
            "description": "Sucesso",
            "paymentId": "0200802861030409521500000620185000000000", 
            "authorizationCode": "043711", 
            "orderNumber": "000000001", 
            "expireAt": "2019-09-24T13:20:52.8775511-03:00",
            "amount": 1035,
            "releaseAt" : "2019-09-24T13:20:52.8775511-03:00"
        },
    
}
                			
            
        

Image Detail:

1. Back-end provides an id guid (unique identifier for a 24-hour period that must be generated by the user) for the front-end to use to capture the codeAntiFraud;
2. Send the “id guid” to the Back-end;
3. In the Gateway API “v1/payments”, enter this data and see how to provide it in the developer's documentation below the implementation documentation click here
4. Check in the response from “v1/payments” that it will return the data of the successfully executed payment;

Below is a flowchart of the failure scenario:

                
                
[
    {
        "tag": "1003", 
        "description": "Pagamento foi rejeitado pela analise do antifraude."
    }
]

                
            
        

Description of the additional scenarios above:

1. Back-end provides an id guid (unique identifier for a 24-hour period that must be generated by the user) for the front-end to use to capture the codeAntiFraud;
2. Send the “id guid” to the Back-end;
3. In the Gateway API “v1/payments”, enter this data and see how to enter it in the developer documentation click here
4. Check in the response from “v1/payments” that it will return the data of the payment executed with FAILURE;

Antifraud behavior when the customer also uses 3DS

If the customer purchases the 3DS service in addition to Antifraud, the system will behave as follows:

• The 3DS service is called prior to Antifraud;
• Antifraud will only be called if the 3DS service has not been successful in credit transactions, i.e. there is no need for an Antifraud check if the 3DS service has been successful;

JavaScript Implementation

Procedures

Antifraud Implementation.

The implementation of antifraud consists of placing a JavaScript command inside the head and body tags. This command will presumably be on a page of the e-commerce website, specifically on the screen where the end customer makes the purchase; this command will be executed as soon as the page is loaded.

Request

• The browser must be able to execute JavaScript.
• Have the organization_id provided by the Adiq onboarding team.
  • This data is important to determine which antifraud account the transaction will be directed to.

Process Checkpoints

• Include the JavaScript command on the payment page;
• Update codes in the back-end;

Step 1 - Include the JavaScript command in the html page

Include the command below inside the head and body tags.

Add inside the head

Add inside the body

It should look like this

The link in the script is as follows

Where:

session_id will be the result of concatenating the prefix adiq_br r i.e. organization_id, which is fixed and does not change, with a dynamic identifier of the GUID type.

Guid (globally unique identifier - GUID) is a 128-bit number used to identify information in computer systems, also called UUID (universally unique identifier). Although the probability of a GUID being duplicated is not zero, it is close enough to be negligible.

2dd470e0-698f-4ae4-bf31-71ccd33970dd is an example of a GUID generated by the merchant application, i.e. it must be generated on the server of the client implementing the antifraud solution.

To learn more about generating a GUID, click on the links below:

• Generate GUID in DotNet;
• Generate GUID in Java;

This GUID code must be entered in the authorization in the sellerInfo.codeAntiFraud field.

SDK Android Implementation

Links & Downloads

In order to implement Antifraud, below are some links for the SDK Android Adiq.

Download link for the Homologation SDK Android Adiq file “adiq-antifraude-package-1.0.0-hml.aar": https://github.com/adiqpagamentos/SDK_AF_Android_Mobile/blob/main/adiq-antifraude-package-1.0.0-hml.aar.zip

Download link for the Production SDK Android Adiq file “adiq-antifraude-package-1.0.0.aar”: https://github.com/adiqpagamentos/SDK_AF_Android_Mobile/blob/main/adiq-antifraude-package-1.0.0.aar.zip

In order to use the files, it is necessary to download them and replace the files with the latest ones each time the code is updated.

NOTE: It is strongly not recommended to use the SDK downloaded from other unofficial sources.

Procedures

Antifraud Implementation.

The implementation of antifraud consists of linking a call to the SDK Android Adiq on the button that executes a purchase. This button will presumably be in a view of the ecommerce Android application, specifically in the view where the end customer makes the purchase after inserting their credit/debit card.

Request

• Android version 4.4 (KitKat, Level 19) or above

Checkpoints do Processo

• Reference the SDK Android from Adiq;
• Create and Update Front-End Codes;
• Updating Back-End code;

Step 1 - Reference the SDK Android adiq-antifraude-package-1.0.0-hml.aar

After clicking on the JAR/AAR Dependency item, select the directory where the SDK was extracted.

Stage 2 - Mobile Development

The SDK features a single class for use, Antifraud, which provides the following method:

• executeDeviceFingerPrint(orgId: String, fingerprintServerUrl: String, providerIdentifier: String): String

Where:

This method is responsible for returning the “codeAntiFraud”, which must be sent to the Gateway API “v1/payments”.

For more information on how to consume the Gateway APIs, please access the developers' documentation (https://developers.adiq.io/manual/ecommerce).

iOS SDK implementation

Links & Downloads

To implement Antifraud, we have below some links to the Adiq iOS SDK

iOS Adiq Homologation SDK File Download Link “adiq-antifraud-package-1.0.0-hml.xcframework": https://github.com/adiqpagamentos/SDK_AF_iOS_Mobile/blob/main/adiq-antifraude-package-1.0.0-hml.xcframework.zip

Adiq Production iOS SDK File Download Link “adiq-antifraud-package-1.0.0.xcframework”: https://github.com/adiqpagamentos/SDK_AF_iOS_Mobile/blob/main/adiq-antifraude-package-1.0.0.xcframework.zip

To use the files, you need to download them and replace the files with the most recent ones with each code update..

NOTE: It is highly not recommended to use the SDK downloaded from other unofficial sources.

Procedures

Anti-Fraud Implementation.

The anti-fraud implementation consists of linking a call to the Adiq iOS SDK to the button that executes a purchase. This button will presumably be in a view of the ecommerce iOS application, specifically in the view where the end customer makes the purchase after entering their credit/debit card..

Requirement

• iOS 13.1 and XCode 11 or above

Process Checkpoints

• Reference the Adiq iOS SDK;
• Create and Update Front-End Code;
• Update Codes in the Back-End;

Step 1 – Reference the iOS SDK adiq-antifraude-package-1.0.0-hml.xcframework

Step 2 – Mobile Development

The SDK has a single class for use, the Antifraude, and this provides the following method:

• executeDeviceFingerPrint(orgId: String, fingerprintServerUrl: String, providerIdentifier: String) -> String

Where:

This method is responsible for returning the “codeAntiFraud”, which must be sent to the Gateway API “v1/payments”.

For more information on how to consume the Gateway APIs, please access the developers' documentation (https://developers.adiq.io/manual/ecommerce).

Required fields in the e-commerce gateway for Antifraud

There is a list of fields that are required to be sent to the Gateway when we are running Antifraud. These fields, according to the requests, are:

Request

                
                
{
    "Payment": {
            "TransactionType": "debit",
            "Amount": "111",
            "CurrencyCode": "brl",
            "ProductType": "debito", 
            "Installments": 1, 
            "CaptureType": "ac", 
            "Recurrent": "false"
        },
    "CardInfo":{ 
            "NumberToken":"d56109ce-6a3b-4190-beea-1c975e8cd486", 
            "CardholderName":"Luiz Silveira Neto", 
            "SecurityCode":"123", 
            "Brand": "mastercard", 
            "ExpirationMonth":"01", 
            "ExpirationYear":"29" 
        }, 
    "SellerInfo":{ 
        "OrderNumber":"1110197548565", 
        "SoftDescriptor":"PAG*TESTE", 
        "CodeAntiFraud":"2dd470e0-698f-4ae4-bf31-71ccd33970dd",
        "ThreeDsDataOnly":"false"
        "MerchantCs":"adiq_br",
        "Antifraud": 
          {
            "app": "client",
            "platform": "android",
            "paymentType": "Pix",
            "sellerTerminalNumber": 1215454,
            "sellerSegment": "rodoviario",
            "scoreCustomized": 2,
            "customerDaysEnrollment": 225,
            "customerDaysFromFirstPurchase": 150,
            "customerDaysFromLastPurchase": 10,
            "completeRoute": "SAO-RIO-SAO",
            "boardingTime": 36,
            "passengerName": "Luiz Silveira Neto",
            "shoppingSameDocLast6Month": 20,
            "Browser": "Chrome",
            "PurchasesLast30days": 0,
            "PurchasesLast60days": 1,
            "PurchasesLast90days": 2,
            "PurchasesLast180days": 3,
            "PurchasesLast360days": 4,
            "PurchaseValueLast30days": 0,
            "PurchaseValueLast60days": 22,
            "PurchaseValueLast90days": 33,
            "PurchaseValueLast180days": 44,
            "PurchaseValueLast360days": 55
         }
        }, 
    "Customer":{ 
            "DocumentType": "cpf", 
            "DocumentNumber":"51115672088", 
            "FirstName":"Luiz", 
            "LastName":"Silveira Neto", 
            "Email":"luiz.silveira@teste.rafael.com", 
            "PhoneNumber":"1122542454", 
            "MobilePhoneNumber":"11987683332", 
            "Address":"Rua Luiz Vieira", 
            "AddressNumber": "134",
            "Complement":"apto. 34 - Vila Guarani", 
            "City":"São Paulo", 
            "State":"SP", 
            "ZipCode":"09876-098", 
            "IpAddress":"45.233.232.248", 
            "Country":"BR" 
        }, 
    "ShipTo":{ 
            "FirstName":"Luiz Paulo", 
            "LastName":"Cardoso", 
            "PhoneNumber":"1122542454", 
            "Address":"Rua Luiz Vieira", 
            "AddressNumber": "134",
            "Complement":"apto. 34 - Vila Guarani", 
            "City":"São Paulo", 
            "State":"SP", 
            "ZipCode":"09876098", 
            "Country":"BR" 
        }, 
    "LineItems":[ 
            { 
                "UnitPrice":"1055",  
                "Quantity":"1", 
                "ProductSKU":"922111212", 
                "ProductName":"Cadeira de plastico", 
                "ProductCode":"235422555252" 
            }, 
            { 
                "UnitPrice":"935",  
                "Quantity":"1", 
                "ProductSKU":"455451212", 
                "ProductName":"Guarda-chuva", 
                "ProductCode":"23656565644" 
            } 
        ], 
    "Sellers":[                                         
        ]      
}
                			
            
        

All the above fields are in the Body.

CPF/CNPJ Validator

Provide an antifraud service known as Cardholder Validator.

The Cardholder Validator uses the card number and CPF provided to perform a thorough analysis in a database of more than 40 banking institutions. This analysis validates whether the card really belongs to the holder of the CPF indicated, all within a secure environment and under the control of the banks.

• By activating the Cardholder Validator through a field indicating that the customer wishes to use this service. This functionality is defined by the SellerInfo.antifraud.checkDocBearer field in the payment API (/v1/payments).
• It is important to note that this service has a different fee to that established for the use of conventional antifraud, so it is necessary to contract the service in order to use it. If this parameter is entered without contracting, the authorizer will invalidate it, returning an operational failure.