Epag Fraud Protection API

Considerations

RESTful: The API is based on a RESTful architecture.

Stateless: The API does not handle states, all necessary data is sent by the client.

URLs: Each method has its unique URL.

HTTP methods: All requests have to respect the correct HTTP method:

  • GET: Read data;

  • POST: Store data;

  • PUT: Update data;

  • DELETE: Delete data.

Warning

This API integration is only necessary for non Epag Payment transactions.

If you are using Epag Payment API, this functionality is natively implemented.

Macro Flow

  1. Merchant registers with epag

  2. Merchant submits transaction history for screening and calibration

  3. Merchant integrates epag's Fraud Protection API into Merchant's Store

  4. User chooses products -> Proceeds to checkout -> Chooses Payment method -> Submits Payment data -> Receives Fraud Score -> Proceeds with process according to Fraud Score.

API Macro Flow

  1. Merchant registers with epag

  2. Merchant accepts terms and conditions

  3. Merchant submits transaction history for screening and calibration

  4. Merchant receives credentials to analyse transactions

  5. Merchant submits authentication data + Payment data and receives Fraud Protection Score

  6. Merchant decides if transaction should be processed or denied

Intake Specs

The Fraud Protection System needs about 6 to 12 months of transaction data starting 1 to 3 months back depending on when the merchants chargebacks tend to come in. For example, if the merchant’s chargebacks mostly come in during the first 30 days then this data file should start one month back. If most of the merchant’s chargebacks come in during a 90 day window then the data file should start 90 days back.

Below you’ll find a standard field list that we require to process your transactions through our pre screening system to develop our model.

This file should include all transactions. Ideally, accepted and declined.

Important: The file should be Tab or Comma Delimited.

Required Fields:

ID (a unique identifier to reference this record)

Order Date (YYYY-MM-DD)

Order Time (HH:MM:SSZ where Z is the time zone)

First name

Last name

Address (if comma delimited, no commas in address)

State

Zip

Country

Phone (XXXXXXXXXX)

Email

IP Address (of the customer making the purchase)

Recurring (Y/N/F/T – See Note 4 below)

Rebill Count (See Note 1 below)

Original Order ID (if this is a rebill, what was the first transaction ID in the series)

Credit Card BIN (See Note 2 below)

Credit Card Hash (See Note 2 below)

CC Exp Month (MM)

CC Exp Year (YYYY)

Country Code (BR, US)

Refunded (Y/N)

Refunded Date (YYYY-MM-DD)

Charged Back (Y/N)

Chargeback Date (YYYY-MM-DD) CVV2 (Y/N)

AVS (Y/N)

Transaction Amount ($xx.xx)

Status (Accepted, Declined)

Any Optional Fields (See Note 3 below)

Notes:

  1. Rebill Count: If you are a recurring merchant, this number is very important for both Chargebacks but also for risk of accepting certain card and only being able to bill it once. With this transaction record, provide the number of times this card number has been rebilled total in your system, not just within this data set.

  2. Credit Card Number: Just provide the first 6 - of the card number in this field (known as the BIN). The preferred format is 123456 thus leaving out most of the digits. This provides us enough to do our analysis. If you do not have this, please discuss with us so we can figure out another variable that will convey similar information. Additionally, as valuable would be a Card Hash. This would be a representation of the card that if the same number was hashed twice it would be the same hash, but that isn’t able to be decrypted. Examples would be sha256 (not salted) or other strong cryptography as long as the same number hashed at different times would generate the same value for comparison purposes.

  3. Optional Fields: After providing the required fields, please provide any other variables that could help in our analysis. Example would be Affiliate ID, Product ID, Tracking ID (this could be an id that relates to a specific ad, link, banner, campaign, traffic source, etc), Age, Age of Account, Number of Purchases this Customer has had before, etc. Other examples could be another company’s fraud score or your own internal fraud score or fraud info. Basically any piece of info that could in some way relate to fraud or other parameter that we may optimize on. Often these extra items are extremely important for our models. We should require some of these fields for optimal results....

  4. Recurring – This tells us if the transaction is a recurring transaction. Use "Y" if the transaction is one of a series of recurring transactions. Use “N” if it is a One Time Only Transaction. Even if the transaction is the First transaction with a trial price, mark it Y for Recurring if the customer with this card will be billed again automatically. Optionally, you may mark the first transaction in a series of a recurring transaction as “F”. This will let us easily optimize based on if the transaction is the First in a series. You may also mark a transaction as “T” for Trial ... use this if you wish for the Trial price that then the customer will be rebilled a different amount automatically once the trial is over. Additionally, could be another optional field ... trial length ... where you provide the length of this trial, you could also provide Rebill Length where you provide the number of days between rebills (ie. 30, 60, 90).

Getting Started

In order to integrate with epag you will need to:

  1. Register with epag

  2. Agree to terms and conditions

Request API Key

In order to receive your API Key you need to:

  1. Agree to Fees and Taxes for a specific Project

  2. Request API Key to screen transactions

Screen Transaction

In order to screen a Transaction:

Service: /trx/score/

Method: POST

Request fields:

  • OrderID (number/required): Unique Tx ID

  • ClientID (string/required): MY_EPAG_ID

  • OrderDate (string/required): YYYY-MM-DD

  • FirstName (string/required): Persons first name

  • LastName (string/required): Persons last name

  • Address (string/required): Ex. 84 New York Plaza

  • City (string/required): Ex. New York

  • State (string/required): Ex. NY

  • Zip (string/optional): Post Code, Ex. 32082-000

  • Country (string/required): Ex. US

  • Phone (string/optional): Ex. 551133337777

  • Email (string/required): Ex. [email protected]

  • IPAddress (string/required): Client IP

  • Referer (string/required): Merchant's Website where the transaction is being processed

  • AffID (string/optional): Affiliate reference Id

  • ProductID (string/optional): Product ID

  • TrackingID (string/optional): Tracking ID

  • Recurring (string/required): Recurring payment - Y/N/F/T

  • Rebills (boolean/required): 0

  • OriginalID (string/optional): Reference Id

  • BIN (string/required): 6 first credit card character numbers

  • CardHash (string/optional): A-One-Way-Hash-Of-Card

  • Exp (string/required): MM/YYYY

  • CVV (string/required): Credit card Secret code

  • AVS (string/optional): Address Verification System code

  • Amount (number/required): 19.95

  • TrxCurrencyCode (string/required): Currency, ex USD, BRL

  • OtherFields (json object/optional): {

    • Username (string/optional): Username at merchants store

    • Level (string/optional): In case of gaming, ex 30

    • CPF (string/optional): Unique country identification to identify this person in country tax system.

    • InstallmentNumber (string/optional): Number of installments

    • Additional (string/optional): Any additional information available

Example Request:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'x-api-key: MY_APY_KEY -d '{

    "OrderID": "IYWEGQR 90",

    "ClientID": "CUS-5R1XKLKB2LGY",

    "OrderDate": "2018-01-01",

    "FirstName": "Alice",

    "LastName": "Sonnentag",

    "Address": "817 Rua Araguari",

    "City": "São Paulo",

    "State": "SP",

    "Zip": "04379-020",

    "Country": "BR",

    "Phone": "551123372225",

    "Email": "[email protected]",

    "IPAddress": "76.12.123.12",

    "Referer": "My Webstore",

    "AffID": "333",

    "ProductID": "PID123",

    "TrackingID": "T123",

    "Recurring": "N",

    "Rebills": "0",

    "OriginalID": "O123",

    "BIN": "513131",

    "CardHash": "917C3D6227FD0804801EBB933B68B9ED7807EDE24CCC0EF7DA0DE2FB08F44B7D",

    "Exp": "01/2021",

    "CVV": "123",

    "AVS": "Y",

    "Amount": "19.95",

    "TrxCurrencyCode": "BRL",

    "OtherFields": {

        "Username": "ASonnentag",

        "Segment": "Morning"

    }

}' 'https://fraudprotect.epag.io/trx/score/

Success response body:

{

    "Score": 0,

    "Success": "true",

    "Code": "200",

    "Recommendation": ""

}

Error response body:

{ 

"timestamp": 1488823431214, 

"status": 401, 

"error": "Unauthorized", 

"message": "Access Denied", 

"path": "/merchant/contracts" 

}

Error response body:

{

    "message": "Forbidden"

}
{

    "message": "Could not process payload"

}