Fraud Prevention API

Documentation

You can take advantage of our Fraud protection service by integrating your payment and user behavior data with our simple REST API. Not only can you send payments and receive a risk score but you can also send custom user actions (e.g. login, logout, web tracking), which allows our Machine Learning models to catch fraudsters at every turn and always be one step ahead of them.

If you are a platform and wish to provide this service to other businesses, you can also use our API to provision and manage different merchant accounts.

Stop fraud with your data! Get started by reading the documentation.

 

REST API Endpoints

/v1/payments
/v1/payments/{id}
/v1/payments/{id}/score
/v1/payments/{id}/label
/v1/payments/{id}/events
/v1/history/payments
/v1/users/{user_id}/status
/v1/actions
/v1/actions/{id}
/v1/merchants
/v1/merchants/{id}

Requests to the API are securely made via HTTPS. Examples are shown using the CURL command.

Authentication

To authenticate access to Feedzai’s API, your API Key is included in the request header using the standard HTTP Basic Authentication scheme. Your API Key must be passed as the username, with no password required. In practice, if you are building the Authorization header yourself, you would have to place your key followed by a colon “:”, convert it to Base64 and prepend the string “Basic “. In the CURL examples, this is accomplished by including  –u “<YOUR_API_KEY>:” in the requests.

 

Service Environments

We provide two main API instances that you can use to access the service:

api.feedzai.com – our main production environment. This is what you should you use after you have completely tested your integration.

sandbox.feedzai.com – our sandbox environment where you can play with our API, test your integration and use in your own development process.

 

Responses

On success, you get an HTTP response code of 200 or 201, plus the requested JSON object in the body. Otherwise you will get a HTTP status code (4XX or 5XX) plus the JSON object below describing the error:

{
  code:    "integer",
  message: "string"
}

 

HTTP status codes:

200Request OK
201Resource created
202Resource created but has been not processed
400Bad request - Often a missing or invalid parameter
401Unauthorized request - Invalid API key
402Failed request - Parameters valid but request failed
404Not found - The requested resource was not found
5xxFeedzai server error

Scoring a Payment

You can score a payment by doing a POST request with a simple JSON-encoded message:

Endpoint

POST   https://api.feedzai.com/v1/payments

Request

The full object for sending a payment with mandatory, optional, and user-defined is defined as:

Name Description
user_id*
string
The unique user ID for the buyer, used in your system. Example: “af00-bc14-1245”
amount*
integer
The payment’s amount in cents. Example: 11099 (given the currency of “USD”, represents $110.99). If the currency is not specified in the “currency” field, the merchant’s default currency will be assumed
ip
string
The user device IP at purchase time. Example: “89.180.212.63
currency
string
The payment’s currency (3-letter ISO 4217 currency code). Example: “USD”, “EUR”. If not specified, the merchant’s default currency will be used
id
string
The unique payment ID in your system. If omitted, we automatically generate one. Example: “124212-00245”
items
array
The list of items that were payed for
item_id
string
A unique product ID in your system. Example: “prod_1228”
quantity
integer
The purchased quantity of this specific item. Example: 3
name
string
The name of the purchased item. Example: Sci-Fi Compendium, 3rd Edition
price
integer
The unit price, in cents, of the purchased item in the currency specified in the “currency” field or in the same currency as the overall amount. Example: 11099 (given the currency of “USD”, represents $110.99)
currency
string
The currency of the unit price (3-letter ISO 4217 currency code). Example: “USD”, “EUR”. If not specified, the currency for the overall amount will be used (see the top-level “currency” field)
brand
string
The item’s brand. Example: “ACME”
store
string
This field can be used when items in the same order are sold and dispatched by different stores. This is usually the case in marketplaces where customers can buy from different sellers on the same platform. In this situation the transaction’s “merchant_id” field would identify the marketplace that takes the order, while the items’ stores would identify the sellers that fulfill it. Example: “Upstate Antique Books”
store_country
string
The country of the store specified in the “store” field (ISO 3166-1 alpha-2 code). Example: “FR”, “PT”
categories
array of arrays
A list of categories the item belongs to. Each element of the list can be multi-level (i.e. include sub-categories) and is in its turn represented by a list of strings, for example [“Clothing”, “Dresses”] denotes a subcategory “Dresses” of the category “Clothing”. A single-level category is represented by a list with a single element, for example: [“Gardening”]. Finally, here are some examples of values that can be used in the “categories” field: [[“Sport goods”]]; [[“Books”, “Crime, Thrillers & Mystery”, “Thrillers”], [“Books”, “Fiction”]]
is_promotion
boolean
Indicates whether there is currently a promotion on the item
url
string
The URL to the product’s description. Example: http://books.example.com/prod_1228.html
user_defined
object
We support an unlimited number of user defined fields (string, boolean, or integer), that you feel might better inform our machine learning system. Examples of what we typically receive here are: “gender”, “size”, “season”, “color”
transaction_type
string
The type of the transaction, according to your own business. Examples: “sale”, a money “transfer”, a “return”. In case of sending post-authorization, you should use the “auth” transaction type
payment_method
string
The payment method used. Examples: “card”, “voucher”, “cash”, “paypal”
card_cvv_present
boolean
Indicates if the card’s CVV was provided/checked when accepting card information and the CVV code was valid. If the CVV was not checked or it failed validation this should be false
user_email
string
The user’s registered Email address. Examples: “howey.1975@gmail.com”
user_fullname
string
The user’s full name, as registered in your system. Examples: “John Smith”, “Joanne Albert Doe”
user_created_at
long
The date the user first registered or appeared in your site (in milliseconds since the Unix Epoch, UTC timezone). If omitted, we assume the request time. Example: 1368457861425 (represents May 13 16:13:57 WEST 2013)
user_gender
string
“M” when the user is Male, “F” when the user is female, “O” in other/undefined cases
user_dateofbirth
string
The user’s date of birth in the format YYYY/MM/DD. Example: “1975/06/30”
user_phone
string
The user’s registered phone number, preferably with the country code and without spaces or hyphens. Example: “0016502608924”
user_address_line1
string
The user’s registered address (line 1). Example: “1875 South Grant Street”
user_address_line2
string
The user’s registered address (line 2). Example: “Suite 710”
user_zip
string
The user’s registered address’ zip/postal code. Examples: “94402”, “E16 2RD”
user_city
string
The user’s registered address’ city. Example: “San Mateo”, “London”
user_region
string
The user’s registered address’ region or state. Example: “CA”, “TX”
user_country
string
The user’s registered address’ country (ISO 3166-1 alpha-2 code). Example: “US”, “GB”
session_id
string
The unique ID of the user session, for example a tracking cookie ID
device_id
string
The unique ID of the device the purchase was made from. For mobile devices you can use the unique device ID (UDID). If this ID is not available, it might be a good idea to at least provide the session_id above
card_hash
string
Full, original PAN encrypted with SHA-512, unsalted. If you already have the full PAN encrypted in another way, you can send it like that
card_fullname
string
The cardholder name as appears on card. Example: “JOHN S SMITH”
card_exp
string
The card expiration date in the MM/YY format. Example: “04/17”
card_country
string
The card country in ISO-3166 format. Example: “US”
card_bin
string
The original card number (PAN) first 6 digits
card_last4
string
The original card number (PAN) last 4 digits. If you already provide the card_hash field this is unnecessary
billing_phone
string
The billing phone number, preferably with the country code and with no spaces of hyphens. Example: “0016502608924”
billing_address_line1
string
The billing address (line 1). Example: “1875 South Grant Street”
billing_address_line2
string
The billing address (line 2). Example: “Suite 710”
billing_zip
string
The billing address’ zip/postal code. Example: “94402”, “E16 2RD”
billing_city
string
The billing address’ city. Example: “San Mateo”, “London”
billing_region
string
The billing region or state. Example: “CA”
billing_country
string
The billing address’ country (ISO 3166-1 alpha-2 code). Example: “US”, “GB”
shipping_fullname
string
The shipping address’ associated receiver’s name, in case of a physically delivered item. Example: “John Smith”
shipping_phone
string
The shipping phone number, preferably with the country code and with no spaces of hyphens. Example: “0016502608924”
shipping_address_line1
string
The shipping address (line 1), in case of a physically delivered item. Example: “1875 South Grant Street”
shipping_address_line2
string
The shipping address (line 2), in case of a physically delivered item. Example: “Suite 710”
shipping_zip
string
The shipping address’ zip/postal code, in case of a physically delivered item. Example: “94402”, “E16 2RD”
shipping_city
string
The shipping address’ city, in case of a physically delivered item. Example: “San Mateo”, “London”
shipping_region
string
The shipping region or state, in case of a physically delivered item. Example: “California”
shipping_country
string
The shipping country in ISO-3166 format, in case of a physically delivered item. Example: “US”
merchant_id
string
The merchant’s unique ID, which can be used to disambiguate between several merchants. Example: “af00-bc14-1245”
merchant_created_at
long
The merchant’s registration date in milliseconds since the Unix Epoch (UTC), typically truncated to day resolution. Defaults to what is specified in the merchant’s account.
merchant_mcc
string
The 4-digit standard merchant category code (MCC). Defaults to what is specified in the merchant’s account. Examples: 7311, 2741
merchant_email
string
The merchant’s Email address. Defaults to what is specified in the merchant’s account. Example: “isellgoods@gmail.com”
merchant_country
string
The merchant’s country in ISO-3166 format. Defaults to what is specified in the merchant’s account.. Example: “US”
details_url
string
The URL to the underlying order/purchase, in your own internal order management system. Example: “books.example.com/admin/order-123”
events
array
List of events that represent changes in the payments’s state, such as successful bank authorization or a chargeback
type*
string
The type of payment event. Can be one of the following values: “3dsecure”, “authorization”, “capture”, “void”, “cancellation” or “chargeback”.
successful*
boolean
Whether the event was successful or not. Either successful or code must be defined.
code*
string
Status or reason code as supplied by the vendor. Either successful or code must be defined. Example: “4845”, “05”, “B”.
timestamp
long
The time of the event (in milliseconds since the Unix Epoch, UTC timezone). If omitted, we assume the request time. Should be greater than the timestamp of the payment or any previous events. Example: 1368457861425 (represents May 13 16:13:57 WEST 2013)
code_scheme
string
The vendor that supplied the value of the code field. Examples: “3D”, “VISA”, “MASTERCARD”, “PAYPAL”.
amount
long
The amount of the event, in cents. Can be supplied only when the code is “authorization”, “capture” or “cancellation”. In this latter case, the amount can be used to identify a partial cancellation.
currency
string
The currency of the amount (3-letter ISO 4217 currency code). Example: “USD”, “EUR”.
user_defined
object
We support an unlimited number of user defined fields (string, boolean, or integer), that you feel might better inform our machine learning system.
user_defined
object
We support an unlimited number of user defined fields (string, boolean, or integer), that you feel might better inform our machine learning system. Examples of what we typically receive here are: “is_gift”, “is_po_box”

* – Required Field

Note that for merchant-related fields, such as “merchant_mcc”, the defaults are taken from the corresponding merchant account. This can be your account, or the account of the merchant specified in the “merchant_id” field, if you have created accounts for subsidiary merchants (see Merchant Provisioning). In case you are indicating different merchants in the “merchant_id” field, but have not performed merchant provisioning, it is recommended to set the correct values of “merchant_mcc”, “merchant_email”, etc, for every payment you send us.

Response

After posting a payment you will get, besides the HTTP status code, a JSON object with a 0-to-1000 fraud score. That JSON also includes a top-level “explanation” field that includes the whole response object, with an explanation for the score in the form of a list of reasons. In case of an error, you will get the respective code and message.

Name Description
id
string
The ID of the just received payment. If you haven’t provided one, we will auto generate one for you. Example: “124212-00245”
score
int
The score attributed to this payment by our machine learning system, ranging from 0 (less likely to be fraud) to 1000 (more likely to be fraud). Example: 896
e_type
enum
Whether this score was delivered by our machine learning scoring system (“scored”), or by a pre-defined reason (e.g. “user_blocked”, “user_allowed”).
base_risk
double
The overall fraud percentage for all payments, represented as a number between 0 and 1. Example: 0.01 (on average, 1% of all payments are fraud)
likelyFraud
boolean
Indicates if Feedzai considered the transaction more likely to be fraudulent. Currently this means the score is higher than 500 (our cutoff point). Note the field is written in camel-case. This field is deprecated
explanation
array
The explanation object consists of a list of reasons contributing to the score, i.e. reasons that lean either in favor or against of classifying the payment as fraud, ordered by risk_factor.
description
string
Summary of this reason’s details. Example: “amount ($110.99) is higher than $100”
risk
double
An updated fraud risk for the subset of payments similar to the current payment. Example: 0.05 (meaning: payments with amount higher than $100 have 5% risk of being fraud)
risk_factor
double
According to this reason, how many times larger (smaller) is the fraud risk of this payment versus the base_risk. Values larger than 1 mean an increased compared to average risk (reason in favor of fraud), smaller than 1 a decreased risk (reason against fraud). Example: 5.0 (meaning 5x more likely to be fraud)
confidence
integer
The confidence that the system has in this particular reason, as an integer between 1 (lowest) to 5 (highest).
weight
double
The rank of the explanation (from 0 to 1.0) – indicating its importance to explaining the whole score. This field is deprecated
details
array
Information on the details of the characteristics of the payment that justify the explanation. These characteristics come in the form of equality or inequality expressions:

  • Equality expression “attribute operator value”, where the operator is “=”
  • Inequality expressions “attribute value operator reference” where operator can be any of following operators “<”, “<=”, “>”, “>=”, “!=”.
attribute
string
The attribute that characterizes this reason. Example: “amount”
value
string
The attribute’s value in the payment. Example: “$110.99”
operator
string
The operator used to compare value and reference. Example: “>”
reference
string
The attribute’s reference value. Example: “$100”

 

Example:

$ curl https://api.feedzai.com/v1/payments \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
      "id": "1477020110",
      "user_id": "af00-bc14-1245",      
      "amount": 280000,
      "currency": "USD",
      "ip": "212.10.114.18",

      "items": [
        {
          "item_id": "cell_400200",
          "name": "Cellphone 1450",
          "price": 25000,
          "quantity": 1,
          "categories": [
            ["Electronics & Photo", "Mobile Phones"],
            ["Entertainment & Multimedia"]
          ],
          "is_promotion": true,
          "url": "http://store.example.com/products/cell_400200",
          "user_defined": {
            "color": "sarcoline"
          }
        },
        {
          "item_id": "comp_123500",
          "name": "Computer XT 1000",
          "price": 50000,
          "currency": "CHF",
          "quantity": 5,
          "brand": "ACME",
          "store": "ACME Custom Computers",
          "store_country": "CH",
          "url": "http://store.example.com/products/comp_123500"
        }
      ],
    
      "transaction_type": "sale",
      "payment_method": "card",
      "card_cvv_present": true,
    
      "user_email": "howey.1975@gmail.com",
      "user_fullname": "Hugh Howey",
      "user_created_at": 1367337011244,
      "user_gender": "M",
      "user_dateofbirth": "1975/06/30",
      "user_phone": "0016502608924",
    
      "user_address_line1": "1875 South Grant Street",
      "user_address_line2": "Suite 710",
      "user_zip": "94402",
      "user_city": "San Mateo",
      "user_region": "CA",
      "user_country": "US",
      
      "session_id": "16ab4...928e",
      "device_id": "afe05...334fd",
    
      "card_hash": "a1ccb...5f7a8",
      "card_fullname": "HUGH Howey",
      "card_exp": "06/17",
      "card_country": "US",
      "card_bin": "442742",
      "card_last4": "1011",

      "billing_phone": "0016502608924",
      "billing_address_line1": "1875 South Grant Street",
      "billing_address_line2": "Suite 710",
      "billing_zip": "94402",
      "billing_city": "San Mateo",
      "billing_region": "CA",
      "billing_country": "US",
    
      "shipping_phone": "00442032867590",
      "shipping_fullname": "Hugh Howey",
      "shipping_address_line1": "6 University Way",
      "shipping_address_line2": "",
      "shipping_zip": "E16 2RD",
      "shipping_city": "London",
      "shipping_region": "London",
      "shipping_country": "GB",

      "merchant_id": "9005-...-2113",
      "merchant_mcc": "7299",
      "merchant_created_at": 1381760524000,
      "merchant_email": "info@yourbusiness.com",
      "merchant_country": "US",

      "details_url": "http://store.example.com/orders/1477020110",

      "events": [
        {
          "type": "3dsecure",
          "successful": true
        },
        {
          "type": "authorization",
          "successful": false,
          "code": "43",
          "code_provider": "VISA"
        }
      ],

      "user_defined": {
        "is_po_box": true,
        "urgent_delivery": true
      }
    }'

Getting a previously sent Payment

Every time you submit a payment you get a score and a set of reasons for that score. Later, you may want to explicitly request the details of a past payment, including the payment itself, and the response that was previously returned. You can do that by GETting to this endpoint, providing the ID that was returned on the response when you originally POSTed your payment.

Endpoint

GET   https://api.feedzai.com/v1/payments/{id}

Parameters

The {id} is the ID of the payment you want to fetch.

Response

{ “payment”: …, “score”: …, "label": "ok" }

You get an object with the originally-submitted payment (see Scoring a payment), as well as the response object that was returned when that payment was submitted (see Scoring a payment – Response).

Name Description
payment
structure
The original JSON payment structure that was previously submitted on the initial payment POST. Refer to Scoring a payment for the fields that may be included. If the original request contained the ip field, then the structure will also include IP geolocation fields such as latitude, longitude, ip_country, ip_region, ip_city, etc.
score
structure
The same JSON structure that was previously returned to the initial payment POST. Refer to the Response to Scoring a payment for the fields that may be included.
label
string
The label associated to the payment (i.e. “ok” or “fraud”). If there is no label, this field will be empty (null). Refer to Labeling a payment for more information on labeling payments.

 

Example:

$ curl 'https://api.feedzai.com/v1/payments/1001' \
   -u '<YOUR_API_KEY>:'

Searching Payments

You may also wish to get a paged list of payments, based on a filter or search query.

Endpoint

GET   https://api.feedzai.com/v1/payments

Parameters

To configure the request and the filters, you can pass the following parameters:

Name Description
page_size
integer
The maximum size of each page.
page
integer
The index of the requested page. The first page has a 0 index.
timestamp_min
long
Filter out payments older than this timestamp. A timestamp should be the number of milliseconds since epoch, in UTC.
timestamp_max
long
Filter out payments newer than this timestamp. A timestamp should be the number of milliseconds since epoch, in UTC.
id
comma-separated list
Provide a comma-separated list of of desired payment IDs to fetch at once.
{any-field-name}
string
All the payment’s fields can be passed as a parameter to filter by that field, according to the provided value.

 

Response

{ “payments”: [ {“payment”: …, “score”: …, "label": "ok"} ] }

A JSON list is returned with all the matching payments, corresponding scores and label. Refer to Getting a previously sent payment for the fields that may be included in each object in the list.

 

Example:

$ curl 'https://api.feedzai.com/v1/payments?&page_size=10&id=1,2' \
   -u '<YOUR_API_KEY>:'

Labeling a previously sent Payment

Labeling a payment is your way to teach the machine learning algorithms if the payment was actually fraudulent or not. This is achieved through a PUT request:

Endpoint

PUT   https://api.feedzai.com/v1/payments/{id}/label

Parameters & Request

The {id} is the ID of the payment you want to label. The body of the PUT, should be a JSON object with a single field, marking the payment as fraudulent or not, as showed in the object:

Name Description
label*
enum
The payment’s label, denoting whether the payment was actually fraudulent (“fraud”) or legitimate (“ok”).

* – Required Field

Response

HTTP Status code 202 with no body or, in case of error, the error code and message.

Example:

$ curl 'https://api.feedzai.com/v1/payments/1001/label' \
   -X PUT \
   -H 'Content-Type: application/json' \
   -u '<YOUR_API_KEY>:' \
   -d '{ "label": "fraud" }'

Adding events to a previously sent payment

As your transaction goes through different states (3dsecure authentication passed, authorized, captured, etc), you can send the corresponding events to our API, so that our machine learning algorithms can capture the intricacies of transaction handling and leverage this information to score future payments more accurately. This is especially important for events indicating fraud, such as authorization failures with codes 41 and 43, chargebacks, etc. You can add events through a POST request:

Endpoint

POST   https://api.feedzai.com/v1/payments/{id}/events

Parameters & Request

The {id} is the ID of the payment you want to add events to. The body of the POST should be a JSON object with a single field which is an array of the events for the payment, as showed in the object:

Name Description
events*
array
List of events that represent changes in the transaction’s state, such as successful bank authorization or a chargeback. Refer to Scoring a payment for the fields of this object.

* – Required Field

Response

HTTP Status code 200 with no body or, in case of error, the error code and message.

Example:

$ curl https://api.feedzai.com/v1/payments/1001/events \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
      "events": [
        {
          "type": "3dsecure",
          "successful": true
        },
        {
          "type": "authorization",
          "successful": false,
          "code": "43",
          "code_provider": "VISA"
        }
      ]
    }'

Getting payment’s events

To explicitly request the event details of a past payment you can do a GET request to this endpoint providing the ID of the transaction with the events.

Endpoint

GET   https://api.feedzai.com/v1/payments/{id}/events

Parameters & Request

The {id} is the ID of the payment you want to get events from.

Response

{ “events”: [ {“type”: …, “code”: …,“amount”: 123} ] }

A JSON list is returned with all the payment events, with the corresponding event fields. Refer to Scoring a payment for the fields that may be included in each object in the list.

Example:

$ curl 'https://api.feedzai.com/v1/payments/1001/events' \
   -u '<YOUR_API_KEY>:'

Sending Historical Payments in Bulk

You can upload one or more historic payments (previously labeled), in bulk. These payments will not be scored but are crucial in building historic profiles of your business. You can send us a batch of payments by performing a POST request:

Endpoint

POST   https://api.feedzai.com/v1/history/payments

Request

Send a JSON object with an array of labeled payments in the format shown below.

Name Description
payments
array
An array of past payments and respective fraud label.
payment
object
A past payment, however the timestamp field is now mandatory. Refer to Scoring a payment for information about all the fields in this object.
label
enum
The label for this payment. Possible values are "ok", "fraud" or null.

Response

HTTP Status code 202 with no body or, in case of error, the error code and message.

 

Example:

$ curl https://api.feedzai.com/v1/history/payments \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
      "payments": [
        {
          "label": "fraud",
          "payment": {  
            "id": "123458000123",
            "user_id": "4599800",
            "amount": 99000,
            "timestamp": 1367337700000,
            "ip": "89.180.212.63"
          }
        },
        {
          "label": "ok",
          "payment": {
            "id": "123458000124",
            "user_id": "1123",
            "amount": 120000,
            "timestamp": 1367337800,
            "ip": "189.122.100.12" 
          }
        }
      ]
    }'

Blacklisting and Whitelisting Users

Sometimes you know users are bad and you want to block them automatically by blacklisting them. Other times, there are trusted users that present suspicious patterns (e.g. an employee) and you don’t want to receive alerts over them. You can set users’ status through a PUT request:

Endpoint

PUT   https://api.feedzai.com/v1/users/{user_id}/status

Request & Parameters

The JSON object to send has the following format.

Name Description
status *
enum
The status of the user, either “blocked”, “allowed” or “ok”.

* – Required Field

All payments of “blocked” users have a score of 1000 and the e_type field in the JSON response object of the payment’s request will be “user_blocked”.

All payments of “allowed” users have a score of 0 and the e_type field in the JSON response object of the payment’s request will be “user_allowed”.

Response

HTTP 200 Status code and a JSON object with updated user status (either “blocked”, “allowed” or “ok”). In case of error, a status object with error code and message will be returned instead.

 

Example:

$ curl https://api.feedzai.com/v1/users/1477020110/status \
   -X PUT \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d '{ "status": "blocked" }'

Getting a User’s status

You can obtain the blocked or allowed status of a user by using a GET request:

Endpoint

GET   https://api.feedzai.com/v1/users/{user_id}/status

Parameters

The {user_id} is the unique customer identifier sent in the “user_id” field when scoring or sending historical payments.

Response

{ "user_id": 1000, "status": "blocked" }

HTTP User Status 200 with the requested user status. In case of error, a status object with error code and message will be returned instead.

 

Example:

$ curl https://api.feedzai.com/v1/users/1001/status \
   -u "<YOUR_API_KEY>:"

User Actions

A payment is the final step in a fraudster’s process. That is the action that you actually have to stop in order to prevent receiving a chargeback and fulfilling items purchased with a cloned credit card. Feedzai is able to detect most fraudulent transactions with just the payment data you send us and which is described above.

However, users’ behavior is much more than the actual payments it tries to make. It includes every action they make in your website (e.g. signing in, changing password, reviewing items) and every interaction they undertake with your business (e.g. in-store, by telephone). Getting these user events allows us to have broader visibility into more complex fraud patterns and regular user behavior.

Read the documentation below to learn more about how to send user action events.

 

Sending a User Action

Actions are activities such as login, register, review, etc., executed by your users that can be used to enrich fraud models and make them more efficient. Actions are submitted through a POST request:

Endpoint

POST   https://api.feedzai.com/v1/actions

Request

The JSON object to send has the following format, again with mandatory and optional fields.

Name Description
user_id *
string
The unique user ID.
ip
string
The user device IP when executing this action
action *
string
The action type. The predefined actions available are: sign_up, login, fail_login, change_password, recover_password, edit_account. You can also create your own actions by using any other user-defined string as the action’s name. User-defined actions can be useful if they can provide a way to highlight odd patterns that may indicate fraud. For example, you can add an action “return” to track if users are returning too many items.
item_id
string
The product or item involved in the action, if there is one. For example, the product a user is viewing.
timestamp
long
The action’s timestamp. If not provided we assume the current system time.
target
string
The target of the action, if there is one. Can be other user_id, if other user was involved in the event (for example in an auction site), or another entity in your website (e.g. “wishlist”).

* – Required Field

Response

HTTP Status code and if applicable, error code and message.

 

Example:

$ curl https://api.feedzai.com/v1/actions \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
      "user_id": "1001",
      "action": "fail_login",
      "ip": "212.10.114.18"
    }'

Merchant Provisioning

If you are a platform and want to provide built-in fraud protection for multiple businesses or subsidiary merchants, in a way that each merchant will have its own semi-isolated data and fraud management, you can use our Merchant Provisioning API endpoints to add new merchant accounts and manage them. Each merchant account will have its own API Key which you can use on their behalf.

Read the documentation below to learn more about managing subsidiary merchant accounts, as well as scoring payments and black-/whitelisting users in this setting.

Note that if you do not wish to provide subsidiary merchants with their own accounts, dashboards and API keys, you can simply use our payment scoring API instead, indicating the desired merchant in the “merchant_id” field.

Creating a new Merchant Account

To create a new merchant account, with its own API Key you just have to send the following POST request:

Endpoint

POST   https://api.feedzai.com/v1/merchants

Request

The JSON object to send has the following format, again with mandatory and optional fields.

Name Description
merchant_id *
string
This is your own internal unique identifier for the merchant account.
name *
string
The merchant’s descriptive public name.
email *
string
The merchant’s email address.
created_at *
long
The merchant’s registration date in your platform, in milliseconds since the Unix Epoch, UTC timezone.
currency *
string
The merchant’s default currency (3-letter ISO 4217 currency code). Example: “USD“, “EUR“.
country *
string
The merchant’s country of origin (ISO 3166-1 alpha-2 code). Example: “US“, “CN“, “AU“.
mcc
string
The merchant’s official category code (MCC).
timezone
string
The identifier for the merchant’s main timezone, using the TZ format. Example: “America/New_York“, “Europe/London“, “Asia/Shanghai“.
locale
string
The identifier for the merchant’s main locale. Example: “en_US“, “en_GB“.

* – Required Field

Response

{ "merchant": { "api_key": "a0ef…", "merchant_id": "my-super-store", "username": "generated-username", "password": "AMgf4Er…", … }}

HTTP Status code 200 and the created Merchant JSON object, including the merchant’s own API Key (the api_key field) and dashboard credentials (the username and password fields). Note that you should store the API Key and the credentials, as they are not returned on querying or updating requests.

In case of error, a status object with an error code and message will be returned instead.

Example:

$ curl https://api.feedzai.com/v1/merchants \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
       "merchant_id": "my-super-store",
       "name": "My Super Store",
       "email": "store@example.com",
       "created_at": 1388534400000,
       "currency": "USD",
       "country": "US",
       "mcc": "5462",
       "timezone": "America/New_York",
       "locale": "en_US"
    }'

Deleting a Merchant Account

To delete a merchant account you just have to send the following DELETE request:

Endpoint

DELETE   https://api.feedzai.com/v1/merchants/{id}

Parameters

The {id} is the ID of the merchant you want to remove. This is the identifier you provided in the “merchant_id” field when Creating the Merchant.

Response

HTTP Status code 200 and an empty JSON object. In case of error, a status object with an error code and message will be returned instead.

Example:

$ curl https://api.feedzai.com/v1/merchants/my-super-store \
   -X DELETE \
   -u "<YOUR_API_KEY>:" \

Updating a Merchant

If you want to update one or more merchant fields, you can use the following PUT request:

Endpoint

PUT   https://api.feedzai.com/v1/merchants/{id}

Request & Parameters

The {id} is the ID of the merchant you want to update. This is the identifier you provided in the “merchant_id” field when Creating the Merchant. Furthermore, you can update fields by sending their values in a JSON object. Refer to Creating a Merchant to see the list of the available fields. In this request you just need to send the fields you want to update — none are mandatory. Note that you cannot update the merchant ID.

Response

{ "merchant": { "merchant_id": "my-super-store", … }}

HTTP 200 Status code and a JSON object with the updated Merchant object. In case of error, a status object with error code and message will be returned instead.

 

Example:

$ curl https://api.feedzai.com/v1/merchants/my-super-store \
   -X PUT \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
       "mcc": "2741",
       "timezone": "America/Detroit",
       "locale": "en_US"
    }'

Getting Merchant Information

If you want to get information about one of the registered merchants, you can use the following GET request:

Endpoint

GET   https://api.feedzai.com/v1/merchants/{id}

Parameters

The {id} is the ID of the merchant you want to obtain. This is the identifier you provided in the “merchant_id” field when Creating the Merchant.

Response

{ "merchant": { "merchant_id": "my-super-store", … }}

HTTP 200 Status code and a JSON object with the merchant information. Refer to the fields documented in Creating a Merchant to learn about the received data. Note that neither the API Key nor the password are returned by this endpoint — both fields are only returned when Creating a Merchant.

In case of error, a status object with error code and message will be returned instead.

 

Example:

$ curl https://api.feedzai.com/v1/merchants/my-super-store \
   -u "<YOUR_API_KEY>:" \

Searching Merchants

You may also wish to get a paged list of merchants, based on a filter or search query.

Endpoint

GET   https://api.feedzai.com/v1/merchants

Parameters

To configure the request and the filters, you can pass the following parameters:

Name Description
page_size
integer
The maximum size of each page.
page
integer
The index of the requested page. The first page has an index of 1.
created_at_min
long
Filter out merchants older than this timestamp. A timestamp should be the number of milliseconds since epoch, in UTC.
created_at_max
long
Filter out merchants newer than this timestamp. A timestamp should be the number of milliseconds since epoch, in UTC.
id
comma-separated list
Provide a comma-separated list of of desired merchant IDs to fetch at once.
{any-field-name}
string
All the merchant’s fields can be passed as a parameter to filter by that field, according to the provided value.

 

Response

{ “merchants”: [ {“merchant_id”: … } ] }

A JSON list is returned with all the matching merchants. Refer to the documentation on Response to Getting a Merchant for the fields that may be included in each object in the list. Note that neither the API Keys nor the passwords are returned by this endpoint — both fields are only returned when Creating a Merchant.

 

Example:

$ curl 'https://api.feedzai.com/v1/merchants?&id=1,2' \
   -u '<YOUR_API_KEY>:'

Scoring Payments

The payment scoring API remains the same for subsidiary merchants. However, it is important to understand how to attribute a payment to a particular merchant. It can be done in two ways:

  • Using your own API Key and setting the “merchant_id” field to the identifier you provided when Creating the MerchantThis method is recommended.
  • Using the merchant’s API Key.

Two examples of achieving the same goal can be found on the right.

Examples:

Using your own API Key and the merchant ID:

$ curl https://api.feedzai.com/v1/payments \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d \
   '{
      "id": "1477020110",
      "user_id": "af00-bc14-1245",      
      "amount": 1150,
      "ip": "212.10.114.18",
      …
      "merchant_id": "my-super-store",
      …
    }'

Using the merchant’s API Key:

$ curl https://api.feedzai.com/v1/payments \
   -H "Content-Type: application/json" \
   -u "<SUBSIDIARY_API_KEY>:" \
   -d \
   '{
      "id": "1477020110",
      "user_id": "af00-bc14-1245",      
      "amount": 1150,
      "ip": "212.10.114.18",
      …
    }'

 

Blacklisting and Whitelisting Users

User blacklisting and whitelisting is integrated with subsidiary merchant accounts. Using the same API as outlined in Blacklisting and Whitelisting Users, you can blacklist an undesired fraudster for all the merchants at once (using your own API Key), or only for a single merchant (using that merchant’s API Key). Note that the user status which is set for a particular merchant overrides the global setting for all merchants. Several examples can be found on the right.

Examples:

Blocking user Alice for merchant 1:

$ curl https://api.feedzai.com/v1/users/Alice/status \
   -X PUT \
   -H "Content-Type: application/json" \
   -u "<MERCHANT_1_API_KEY>:" \
   -d '{ "status": "blocked" }'

Blocking user Bob for all merchants:

$ curl https://api.feedzai.com/v1/users/Bob/status \
   -X PUT \
   -H "Content-Type: application/json" \
   -u "<YOUR_API_KEY>:" \
   -d '{ "status": "blocked" }'

Making an exception for user Bob and merchant 2:

$ curl https://api.feedzai.com/v1/users/Bob/status \
   -X PUT \
   -H "Content-Type: application/json" \
   -u "<MERCHANT_2_API_KEY>:" \
   -d '{ "status": "allowed" }'