API Reference

Made for Developers

 Back to top

Feedzai eCommerce API reference

You can take advantage of Feedzai Fraud protection service by integrating your payment and user behavior data with our simple REST API.

The Feedzai eCommerce API gives you a REST interface to send payments and receive a risk score. It also allows you to examine the results and manipulate the transactions you have already sent for a full and flexible integration with your own systems.

The API Reference provides all details about every available action, what and how you should send data, and what information the API returns to you.

Authentication

Access to Feedzai’s API is authorized by means of JWT (RFC 7519) — a cryptographically signed token that includes your username, validity date and other metadata.

There are two ways to include the token in the request: in HTTP “Authorization: Basic" header (supported for compatibility with the previous version of the API), or in HTTP “Authorization: Bearer" header.

  • “Authorization: Basic" header: Pass the token as the username and without a password.In practice, if you are building the Authorization header yourself, you would have to place your token followed by a colon “:”, convert it to Base64 and prepend with the string “Basic ”, for example: “Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==”.

    In the cURL examples, this is accomplished by including -u "<JWT>:" in the requests.

    See https://tools.ietf.org/html/rfc2617#section-2 for more details.

  • “Authorization: Bearer” header: Pass the token normally, as described in https://tools.ietf.org/html/rfc6750#section-2.1, for example: “Authorization: Bearer <JWT>”.In cURL, include the following argument: -H "Authorization: Bearer <JWT>".

Responses and Errors

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 indicating an error (4XX or 5XX) plus the JSON object describing the error. This object contains two fields:

Field Description
code Identifies the type of the error
errors Contains human-readable error description(s)
{
    "code": "nonexistentTransaction",
    "errors":[
      "The transaction 1773004 does not exist"
    ]
  }

The full list of currently used Feedzai codes is:

Code Description
ok request successfully processed
parseError malformed JSON request
validationError some data fields in the request are invalid
nonexistentTransaction requested transaction ID does not exist
duplicateTransaction sending a transaction with a pre-existing identifier
pendingTransaction transaction with the same identifier has still not finished being scored
pastTransaction transactions are out of order (timestamp is too far in the past)
pastTransactionChange the timestamp of the operation precedes the timestamp when the transaction was last changed
futureTransaction transaction’s timestamp is too far in the future
mismatchedTransactionType transaction type cannot be changed when doing transaction updates
nonexistentPaymentMethod the transaction does not contain the payment method specified for update
invalidEvent the event type is not supported by the payment method specified for update
ambiguousEvent the event is ambiguous, since it matches several payment methods
pastEvent some of the specified events have timestamps prior to the already received events
nonexistentList the specified list does not exist
nonexistentListEntry the specified list entry does not exist
mismatchedListSchema the specified list entry does not match the configured schema for that list
nonexistentEndpoint the specified endpoint does not exist
unsupportedMethod the endpoint does not support the HTTP method that was used
invalidHistoricalTransactions some of the historical transactions were invalid
timeoutError our internal services took too long to process your request
internalError unexpected server error

The list of HTTP response codes is as follows:

Code Description
200 Request OK
400 Bad request – Often a missing or invalid parameter, or a malformed request
401 Unauthorized request – Missing or invalid JWT
404 Not found – The requested resource was not found
409 Conflict – The transaction already exists or is being processed
5xx Feedzai server error

Payments

Payment score

Scoring a payment

POST/payments{?provide_explanations}

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

After posting a payment you will get, in addition to the HTTP 200 status code, a JSON object with a 0-to-1000 fraud score and the decision resulting from Feedzai’s analysis.

Possible HTTP responses and codes

Depending on the current processing state of the payment, and whether it is the first scoring request or a repeated transaction submission, you will receive the following HTTP responses:

Code Description
200 The payment has been successfully processed and scored. This is the success response for the first time a payment is scored.
409 The payment already exists in the system or is in the process of being scored. This is the response when a transaction is re-sent for scoring with the same id and not as an update request.
5xx Failure in scoring the payment.

In case of a HTTP 409 response, the error message indicates one of the following results:

Response Description
duplicateTransaction The transaction had already been completely processed before. The response body includes the original transaction’s scoring response.
pendingTransaction The transaction is still in the process of being scored and you should retry sending it again. In this case, you will see an error with the code transactionInProcess.

In case of a different error, you will get the respective code and message. Check the Responses and Errors section for a full list of possible errors.

Request Object

Check the detailed descriptions of all fields in the Payment object.

Response Object

Check the detailed descriptions of all fields in the Score object.

Example URI

POST https://api.feedzai.com/v1.1/payments?provide_explanations=false

URI Parameters

HideShow
provide_explanations
boolean (optional) Example: falseIf true, the response object includes the reasons in favor or against classifying the payment as fraud. However, explanations are still available when you obtain payment details. Activating this option adds extra processing time. The default is false.

Request  Scoring a payment

HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1477020120",
  "user_id": "af00-bc14-1245",
  "amount": 280000,
  "currency": "USD",
  "ip": "212.10.114.18",
  "order_status": "open",
  "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"
      }
    }
  ],
  "transaction_type": "sale",
  "user_email": "[email protected]",
  "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": "78c3f...544d",
  "payment_methods": [
    {
      "type": "card",
      "gateway": "adyen",
      "id": "a1ccb...5f7a8",
      "primary": true,
      "amount": 280000,
      "currency": "USD",
      "status": "pending",
      "card_fullname": "HUGH Howey",
      "card_hash": "a1ccb...5f7a8",
      "card_bin": "442742",
      "card_last4": "1011",
      "card_exp": "06/17",
      "card_country": "US",
      "card_brand": "visa",
      "auth_check": {
        "status": "passed",
        "status_code": null,
        "status_scheme": "visa"
      },
      "cvv_check": {
        "status": "passed",
        "status_code": "M",
        "status_scheme": "visa"
      },
      "avs_check": {
        "status": "passed",
        "status_code": "Y",
        "status_scheme": "visa"
      },
      "3ds_check": {
        "status": "disabled"
      },
      "chargeback_code": null
    }
  ],
  "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_addresses": [
    {
      "id": "0",
      "type": "standard",
      "primary": true,
      "email": "[email protected]",
      "fullname": "Hugh Howey",
      "phone": "00442032867590",
      "address_line1": "6 University Way",
      "address_line2": "",
      "zip": "E16 2RD",
      "city": "London",
      "region": "London",
      "country": "GB"
    }
  ],
  "details_url": "http://store.example.com/orders/1477020110",
  "events": [
    {
      "type": "3dsecure",
      "payment_method_type": "card",
      "payment_method_id": "a1ccb...5f7a8",
      "successful": true
    },
    {
      "type": "authorization",
      "payment_method_type": "card",
      "payment_method_id": "a1ccb...5f7a8",
      "successful": false,
      "code": "43",
      "code_scheme": "VISA"
    }
  ],
  "user_defined": {
    "is_po_box": true,
    "expedited_delivery": true
  }
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "score": 11,
  "decision": "approve",
  "base_risk": 0.005,
  "id": "1477020120",
  "explanation": [
    {
      "description": "Customer had little activity in last 3 months.",
      "risk": 0.008,
      "confidence": 5
    },
    {
      "description": "Customer has used a single internet address in the last 24 hours.",
      "risk": 0.003,
      "confidence": 5
    },
    {
      "description": "Score (11) is less than 500.",
      "risk": 0,
      "confidence": 5
    }
  ]
}

Response  409

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "code": "duplicateTransaction",
  "errors": [
    "The transaction 1477020120 already exists"
  ],
  "score": 11,
  "decision": "approve",
  "base_risk": 0.005,
  "id": "1477020120",
  "explanation": [
    {
      "description": "Customer had little activity in last 3 months.",
      "risk": 0.008,
      "confidence": 5
    },
    {
      "description": "Customer has used a single internet address in the last 24 hours.",
      "risk": 0.003,
      "confidence": 5
    },
    {
      "description": "Score (11) is less than 500.",
      "risk": 0,
      "confidence": 5
    }
  ]
}

Response  409

HideShow
Headers
Content-Type: application/json
Body
{
  "code": "pendingTransaction",
  "errors": [
    "The transaction 1477020120 is already being processed"
  ]
}

Payment details

Obtaining payment details

GET/payments/{id}

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.

The call returns an object with the updated submitted payment, as well as the response object that was returned when that payment was submitted. The object payload is as follows:

{
  "status": "ok",
  "payment": ,
  "score": ,
}

In case of an error, you will get the respective code and message. Check the Responses and Errors section for a full list of possible errors.

Example URI

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

URI Parameters

HideShow
id
number (required) Example: 1477020410ID of the payment for which you want to fetch the details

Request  Obtain details

HideShow
Headers
Content-Type: application/json

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok",
  "payment": {
    "timestamp": 1464604119179,
    "device_id": "78c3f...544d",
    "ip": "212.10.114.18",
    "session_id": "16ab4...928e",
    "user_region": "CA",
    "user_country": "US",
    "user_address_line2": "Suite 710",
    "user_phone": "0016502608924",
    "user_id": "af00-bc14-1245",
    "user_email": "[email protected]",
    "user_gender": "M",
    "user_city": "San Mateo",
    "user_address_line1": "1875 South Grant Street",
    "user_zip": "94402",
    "user_dateofbirth": "1975/06/30",
    "user_created_at": 1367337011244,
    "user_fullname": "Hugh Howey",
    "billing_zip": "94402",
    "billing_phone": "0016502608924",
    "billing_address_line1": "1875 South Grant Street",
    "payment_methods": [
      {
        "id": "a1ccb...5f7a8",
        "gateway": "adyen",
        "primary": true,
        "amount": 280000,
        "currency": "USD",
        "status": "pending",
        "auth_check": {
          "status": "passed",
          "status_scheme": "visa"
        },
        "card_bin": "442742",
        "card_hash": "a1ccb...5f7a8",
        "card_exp": "06/17",
        "card_last4": "1011",
        "card_country": "US",
        "card_fullname": "HUGH Howey",
        "cvv_check": {
          "status": "passed",
          "status_code": "M",
          "status_scheme": "visa"
        },
        "avs_check": {
          "status": "passed",
          "status_code": "Y",
          "status_scheme": "visa"
        },
        "3ds_check": {
          "status": "disabled"
        },
        "type": "card"
      }
    ],
    "amount": 280000,
    "billing_region": "CA",
    "billing_country": "US",
    "billing_address_line2": "Suite 710",
    "currency": "USD",
    "billing_city": "San Mateo",
    "events": [
      {
        "timestamp": 1464604119179,
        "type": "3dsecure",
        "successful": true,
        "payment_method_type": "card",
        "payment_method_id": "a1ccb...5f7a8"
      },
      {
        "timestamp": 1464604119179,
        "type": "authorization",
        "successful": false,
        "code": "43",
        "code_scheme": "VISA",
        "payment_method_type": "card",
        "payment_method_id": "a1ccb...5f7a8"
      }
    ],
    "items": [
      {
        "price": 25000,
        "currency": "USD",
        "quantity": 1,
        "name": "Cellphone 1450",
        "categories": [
          [
            "Electronics & Photo",
            "Mobile Phones"
          ],
          [
            "Entertainment & Multimedia"
          ]
        ],
        "is_promotion": true,
        "item_id": "cell_400200",
        "url": "http://store.example.com/products/cell_400200",
        "user_defined": {
          "color": "sarcoline"
        }
      }
    ],
    "shipping_addresses": [
      {
        "type": "standard",
        "id": "0",
        "primary": true,
        "fullname": "Hugh Howey",
        "email": "[email protected]",
        "phone": "00442032867590",
        "city": "London",
        "zip": "E16 2RD",
        "country": "GB",
        "region": "London",
        "address_line1": "6 University Way"
      }
    ],
    "id": "1477020120",
    "details_url": "http://store.example.com/orders/1477020110",
    "user_defined": {
      "is_po_box": true,
      "expedited_delivery": true
    },
    "order_status": "open",
    "transaction_type": "sale"
  },
  "score": {
    "score": 11,
    "decision": "approve",
    "base_risk": 0.005,
    "explanation": [
      {
        "description": "Customer had little activity in last 3 months.",
        "risk": 0.008,
        "confidence": 5
      },
      {
        "description": "Customer has used a single internet address in the last 24 hours.",
        "risk": 0.003,
        "confidence": 5
      },
      {
        "description": "Score (11) is less than 500.",
        "risk": 0,
        "confidence": 5
      }
    ]
  }
}

Response  404

HideShow
Headers
Content-Type: application/json
Body
{
  "code": "nonexistentTransaction",
  "errors": [
    "The transaction 1477020410 does not exist"
  ]
}

Payment labels

Labeling payments

PUT/payments/{id}/label

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. The body of the PUT, should be a JSON object with a single field, marking the payment as fraudulent or not.

In case of an error, you will get the respective code and message. Check the Responses and Errors section for a full list of possible errors.

Request Fields

Check the detailed descriptions of all fields in the Label object.

Example URI

PUT https://api.feedzai.com/v1.1/payments/1477020110/label

URI Parameters

HideShow
id
number (required) Example: 1477020110ID of the payment you want to label

Request  Label as fraud

HideShow
Headers
Content-Type: application/json
Body
{
  "label": "fraud"
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}

Response  404

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "code": "nonexistentTransaction",
  "errors": [
    "The transaction 147702120 does not exist"
  ]
}
Unabeling payments

DELETE/payments/{id}/label

If you want to remove a previously assigned label to a payment, effectively marking its fraud status as undetermined, you can send a DELETE request to the same label resource.

In case of an error, you will get the respective code and message. Check the Responses and Errors section for a full list of possible errors.

Example URI

DELETE https://api.feedzai.com/v1.1/payments/1477020110/label

URI Parameters

HideShow
id
number (required) Example: 1477020110ID of the payment you want to label

Request  Unlabel payment

HideShow
Headers
Content-Type: application/json

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}

Response  404

HideShow
Headers
Content-Type: application/json
Body
{
  "code": "nonexistentTransaction",
  "errors": [
    "The transaction 1477020110 does not exist"
  ]
}

Payment events

Adding events to a previously sent payment

POST/payments/{id}/events{?cancel_order}

As your transaction goes through different states (3dsecure authentication passed, authorized, captured, etc), you can send the corresponding events to the 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.

It is also possible to update multiple payment methods via the transaction events interface, using the payment_method_type and payment_method_id fields. If no type or id is specified then the event applies to the transaction’s primary payment method.

The payment method is matched by type. If there is a conflict, then there is an attempt to match by identifier as well. If the identifier does not match any of the received payment methods, then the update is rejected.

For a complete list of possible response errors refer to Responses and Errors.

Request Fields

Check the detailed descriptions of all fields in the Events list object.

Example URI

POST https://api.feedzai.com/v1.1/payments/1477020110/events?cancel_order=true

URI Parameters

HideShow
id
number (required) Example: 1477020110ID of the payment to which you want to add events.
cancel_order
boolean (optional) Example: trueIf true, the order status of the associated transaction will be set to cancelled. By default this is false, which means the order status remains the same. To update it you should use the Order Status Update endpoint.

Request  Failed authorization

HideShow
Headers
Content-Type: application/json
Body
{
  "events": [
    {
      "payment_method_id": "1234",
      "payment_method_type": "card",
      "type": "3dsecure",
      "successful": true
    },
    {
      "payment_method_id": "1234",
      "payment_method_type": "card",
      "type": "authorization",
      "successful": false,
      "code": "43",
      "code_scheme": "VISA"
    }
  ]
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}

Response  404

HideShow
Headers
Content-Type: application/json
Body
{
  "code": "nonexistentTransaction",
  "errors": [
    "The transaction 1477020110 does not exist"
  ]
}

Payment updates

Updating a previously sent payment

POST/payments/updates{?provide_explanations}{?reopen}

In some situations, you might need to update some fields in a transaction, such as the billing address, and you wish to rescore it as a result.

In these cases you must:

  • Make sure the transaction has been sent in the first payment scoring API call.
  • Make an update API call. The update call must use the same transaction ID.

The request follows the same format as the payment scoring endpoint with the difference that you should only send the fields that you want to replace in the original transaction.

Nonetheless, there are some fields you cannot send in these requests because they cannot be changed:

Field Description
id The identifier of the transaction cannot be changed.
timestamp The original timestamp of the transaction cannot be changed.
transaction_type It is not possible to change the transaction type (e.g. from “sale” to “transfer”) in an update operation.
events The events should be instead updated through the events API call.
order_status The order status should be instead updated through the order update API call.

Updated timestamp field

The timestamp field, if specified, is interpreted as the timestamp of the update event. It will not update the original timestamp when the transaction occurred.

The response from this endpoint is the same as from the payment scoring endpoint, reflecting any changes to the score that may have occurred.

For a complete list of possible response errors refer to Responses and Errors.

Example URI

POST https://api.feedzai.com/v1.1/payments/updates?provide_explanations=false?reopen=false

URI Parameters

HideShow
provide_explanations
boolean (optional) Example: falseIf true, the response object includes the reasons in favor or against classifying the payment as fraud. However, explanations are still available when you obtain payment details. Activating this option adds extra processing time. The default is false.
reopen
boolean (optional) Example: falseIf true, the order_status field of the underlying transaction will be set to “open”. Otherwise, the order_status will remain the same. Use the Order Status Update endpoint to perform updates. The default is false.

Request  Change billing address

HideShow
Headers
Content-Type: application/json
Body
{
  "billing_address_line1": "1875 South Grant Street",
  "billing_address_line2": "Suite 710"
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok",
  "score": 1000,
  "id": "1477020120",
  "decision": "review"
}

Response  404

HideShow
Headers
Content-Type: application/json
Body
{
  "code": "nonexistentTransaction",
  "errors": [
    "The transaction 1477020110 does not exist"
  ]
}

Order status update

Updating the status of an order

PUT/payments/{id}/order_status

To properly support multi-step processes, it is important to be able to represent the current state of an order. This allows you to track the order progress throughout the several stages of the end-to-end commerce process.

Allowed order status updates

Updates to the order status must always be performed via this API call. For example, always use this endpoint when you need to re-open a cancelled order.

The API does not allow changing the order status via an update API call.

The body of the request should be a JSON object containing the new status value.

For a complete list of possible response errors refer to Responses and Errors.

Example URI

PUT https://api.feedzai.com/v1.1/payments/1477020110/order_status

URI Parameters

HideShow
id
number (required) Example: 1477020110ID of the payment for which you want to perform a status update

Request  Cancel order

HideShow
Headers
Content-Type: application/json
Body
{
  "value": "cancelled"
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}

Response  404

HideShow
Headers
Content-Type: application/json
Body
{
  "code": "nonexistentTransaction",
  "errors": [
    "The transaction 1477020110 does not exist"
  ]
}

Payment history

Loading historical payments in bulk

POST/payments/history

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 on the payment patterns of your business.

You can send us a batch of payments by performing a POST request. You must send a JSON object with an array of labeled payments.

Since the operation is performed in bulk, it may result in partial success. This means that some historical transactions may be accepted while others are rejected with specific error messages.

For a complete list of possible response errors refer to Responses and Errors.

Request Fields

Check the detailed descriptions of all fields in the Historical payments object.

Example URI

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

Request  Batch loading

HideShow
Headers
Content-Type: application/json
Body
{
  "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": 1367337800000,
        "ip": "189.122.100.12"
      }
    }
  ]
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok",
  "info": [
    "Transaction 123458000123 was successfully processed",
    "Transaction 123458000124 was successfully processed"
  ]
}

Response  202

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok",
  "info": [
    "Transaction 123458003129 was successfully processed"
  ],
  "errors": [
    "Transaction 123458000159 is too far in the future",
    "A transaction with id 123458000130 already exists"
  ]
}

Response  400

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "code": "invalidHistoricalTransactions",
  "errors": [
    "A transaction with id 123458000123 already exists",
    "A transaction with id 123458000124 already exists"
  ]
}

Cards

Card tokens

Registering card tokens

POST/cards

This endpoint enables you to limit the exposure of PANs, thus increasing the security on how you exchange card information.

With this service you may:

  • Expose the PAN once, generate a token, and use only the token subsequently.
  • Register a token and never expose the PAN.
  • Register several tokens for the same card. For example, when different family members use the same card with different user accounts.

You can use this endpoint call to correlate card tokens with the corresponding PAN. Tokens should have been generated for payments that use the card method.

The body of the request should be a JSON object containing an array of cards. For each card, it must include the full PAN and the token to be registered, along with other fields describing the card.

For a complete list of possible response errors refer to Responses and Errors.

Request Fields

Check the detailed descriptions of all fields in the Cards object.

Example URI

POST https://api.feedzai.com/v1.1/cards

Request  Map token

HideShow
Headers
Content-Type: application/json
Body
{
  "cards": [
    {
      "card_pan": "4111111111111111",
      "card_token": "9df27d6c-e5e1-4cb0-80e1-c7d6a55a0bd0",
      "card_exp": "06/19"
    }
  ]
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}

Lists

Positive-Negative lists

Blacklisting and whitelisting users or other identifiers

PUT/lists/posneg/{entity}/{entity_id}

Sometimes you know users are fraudsters 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. It’s also common to want to block or allow certain IP addresses or devices. Additionally, you can also greylist entities, for example when they require a review before being blocked or allowed.

You can add these entities through a PUT request.

The following entities are supported:

Entity Description
user User ID
email User email
phone User phone
ip User IP (internet address)
card Credit card (token or hash)

Configuring positive/negative for other entities

Other entities can be configured in the system by Feedzai’s Professional Services team. In essence, any data field can be used in this way.

For a complete list of possible response errors refer to Responses and Errors.

Request Fields

Check the detailed descriptions of all fields in the Positive/negative list object.

Example URI

PUT https://api.feedzai.com/v1.1/lists/posneg/user/1477020110

URI Parameters

HideShow
entity
string (required) Example: userName of the entity you want to whitelist, greylist, or blacklist.
entity_id
number (required) Example: 1477020110Field value for that entity (its ID), and the one you are actually blacklisting (decline), greylisting (review) or whitelisting (approve).

Request  Blacklisting

HideShow
Headers
Content-Type: application/json
Body
{
  "value": "decline"
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}
Checking if entity is whitelisted/greylisted/blacklisted

GET/lists/posneg/{entity}/{entity_id}

Use this endpoint to check if a user or a card (or other supported entities) are in a positive/negative list.

The following entities are supported:

Entity Description
user User ID
email User email
phone User phone
ip User IP (internet address)
card Credit card (token or hash)

For a complete list of possible response errors refer to Responses and Errors.

Response Fields

Check the detailed descriptions of all fields in the Positive/negative list object.

Example URI

GET https://api.feedzai.com/v1.1/lists/posneg/user/1477020110

URI Parameters

HideShow
entity
string (required) Example: userName of the entity you want to check whether it is whitelisted, greylisted, or blacklisted.
entity_id
number (required) Example: 1477020110Field value for that entity (its ID), and the one you are actually checking.

Request  Check positive/negative list

HideShow
Headers
Content-Type: application/json

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok",
  "value": "decline"
}
Removing an entity from whitelist/greylist/blacklist

DELETE/lists/posneg/{entity}/{entity_id}

Use this endpoint to remove a user or a card (or other supported entities) from a positive/negative list.

The following entities are supported:

Entity Description
user User ID
email User email
phone User phone
ip User IP (internet address)
card Credit card (token or hash)

For a complete list of possible response errors refer to Responses and Errors.

Example URI

DELETE https://api.feedzai.com/v1.1/lists/posneg/user/1477020110

URI Parameters

HideShow
entity
string (required) Example: userName of the entity you want to remove from a whitelist, greylist, or blacklist.
entity_id
number (required) Example: 1477020110Field value for that entity (its ID), and the one actually whitelisted, greylisted, or blacklisted.

Request  Remove from positive/negative list

HideShow
Headers
Content-Type: application/json

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}

Generic lists

Manipulating generic lists

PUT/lists/generic/{list}/{list_item_key}

Feedzai supports any list configured with custom fields that are specific to your business, for example defining purchase limits for products in the list.

Configuring generic lists

Feedzai’s Professional Services team will perform all configuration of underlying lists.

When you send a request to this endpoint, it is not mandatory that you include all the fields that are configured in schema of the list.

For a complete list of possible response errors refer to Responses and Errors.

Request Fields

Check the detailed descriptions of all fields in the List entry object.

Example URI

PUT https://api.feedzai.com/v1.1/lists/generic/product_limits/sku_1234

URI Parameters

HideShow
list
string (required) Example: product_limitsName of the list you want to manipulate. For example, product_limits.
list_item_key
string (required) Example: sku_1234Identifier of the list item you are manipulating. For example, the sku_1234 item in the product_limits list.

Request  Adding product limits

HideShow
Headers
Content-Type: application/json
Body
{
  "comment": "Add limits for new product",
  "active_from": 0,
  "active_until": 9223372036854776000,
  "enabled": true,
  "value": {
    "max_total_purchases_per_user": 5,
    "max_daily_purchases_per_user": 2
  }
}

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "status": "ok"
}
Reading from generic lists

GET/lists/generic/{list}/{list_item_key}

Use this endpoint to check the contents of a generic list.

Configuring generic lists

Feedzai’s Professional Services team will perform all configuration of underlying lists.

For a complete list of possible response errors refer to Responses and Errors.

Response Fields

Check the detailed descriptions of all fields in the List entry object.

Example URI

GET https://api.feedzai.com/v1.1/lists/generic/product_limits/sku_1234

URI Parameters

HideShow
list
string (required) Example: product_limitsName of the list you want to manipulate. For example, product_limits
list_item_key
string (required) Example: sku_1234Identifier of the list item you are manipulating. For example, the sku_1234 item in the product_limits list.

Request  Check generic list

HideShow
Headers
Content-Type: application/json

Response  200

HideShow
Headers
Content-Type: application/json
Body
{
  "comment": "some comment",
  "active_from": 0,
  "active_until": 9223372036854776000,
  "enabled": true,
  "status": "ok",
  "value": {
    "max_total_purchases_per_user": 5,
    "max_daily_purchases_per_user": 2
  }
}

Data structures

Payment

The Payment object represents a transaction you send to Feedzai for scoring.

Name Description
timestamp (number) The time when the transaction occurred (in milliseconds since the Unix Epoch, UTC timezone). If omitted, then the request time is assumed. Example: 1462891706 When using the re-scoring and update endpoint, this field corresponds to the time when the update occurred, since the original transaction timestamp cannot be updated.
id (string, required) The unique payment ID in your system. Example: 124212-00245
amount (number, required) The payment amount in cents. Example: 11099 (given the currency of “USD”, represents $110.99). If the currency is not specified in the “currency” field, “USD” will be assumed.
user_id (string) The unique user ID for the buyer, used in your system. Example: af00-bc14-1245
order_status (string) The status of the order associated with the transaction. Supported values are “open”, “cancelled”, “fulfilled”. By default the status will be “open”. You can update the order status through the Order Status Update endpoint. Example: open
ip (string) The user device IP at purchase time in IPv4 or IPv6 format. Example: 89.180.212.63
currency (string) The payment currency (3-letter ISO 4217 currency code). If not specified, “USD’ will be assumed.
items (array(Item)) The list of items that were paid for. Example: USD
transaction_type (string) The type of the transaction, according to your own business. Supported types are “sale”, “exchange”, a money “transfer”, a “topup” or a “preauth” charge (e.g. small $1 charge to validate a card). If not specified, “sale” will be assumed. Example: sale
user_email (string) The user’s registered email address. Example: [email protected]
user_fullname (string) The user’s full name, as registered in your system. Example: John Smith
user_created_at (number) The date the user first registered or appeared in your site (in milliseconds since the Unix Epoch, UTC timezone). If omitted, the request time will be used. 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 cases. If gender is unknown you should leave this field as empty, or null. Example: M
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. Example: 94402
user_city (string) The user’s registered address’ city. Example: San Mateo
user_region (string) The user’s registered address’ region or state. Example: CA
user_country (string) The user’s registered address’ country (ISO 3166-1 alpha-2 code). Example: US
session_id (string) The unique ID of the user session, for example a tracking cookie ID. Example: 16ab4...928e
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, if you are tracking user sessions it’s recommended to at least provide the session id. Example: 78c3f...544d
payment_method (string) The type of the payment method. Check the supported types in the payment types reference. Example: card Deprecated: Use the “type” field in the payment methods object.
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. Example: true Deprecated: Use the equivalent field in the payment methods object.
card_hash (string) Full, original PAN encrypted with SHA-512, salted. If you already have the full PAN encrypted in another way, you can send it like that. Example: a1ccb...5f7a8 Deprecated: Use the equivalent field in the payment methods object.
card_fullname (string) The cardholder name as appears on card. Example: JOHN S SMITH Deprecated: Use the equivalent field in the payment methods object.
card_country (string) The card country in ISO-3166 format. Example: US Deprecated: Use the equivalent field in the payment methods object.
card_bin (string) The first 6 (in rare cases, 5) digits of the original card number (PAN). Example: 442742 Deprecated: Use the equivalent field in the payment methods object.
card_last4 (string) The last 4 digits of the original card number (PAN). At most 3 digits on the left can be masked with the “*” symbol, for example, “1234”, “*234”, “**34” and “***4” are all valid values. If you already provide the card hash field, this field is unnecessary. Example: 1001 Deprecated: Use the equivalent field in the payment methods object.
payment_methods (array(PaymentMethod)) An array of payment methods used. Methods of the same type should have different ids.
billing_fullname (string) The name associated with the billing address. Example: John Smith
billing_phone (string) The billing phone number, preferably with the country code and with no spaces or 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
billing_city (string) The billing address’ city. Example: San Mateo
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
shipping_fullname (string) The receiver’s name associated with the shipping address, in case of a physically delivered item. Example: “John Smith”. Example: John Smith Deprecated: Use the equivalent field in the shipping addresses object.
shipping_phone (string) The shipping phone number, preferably with the country code and with no spaces or hyphens. Example: 0016502608924. Deprecated: Use the equivalent field in the shipping addresses object.
shipping_address_line1 (string) The shipping address (line 1), in case of a physically delivered item. Example: 1875 South Grant Street. Deprecated: Use the equivalent field in the shipping addresses object.
shipping_address_line2 (string) The shipping address (line 2), in case of a physically delivered item. Example: Suite 710 Deprecated: Use the equivalent field in the shipping addresses object.
shipping_zip (string) The shipping address’ zip/postal code, in case of a physically delivered item. Example: 94402 Deprecated: Use the equivalent field in the shipping addresses object.
shipping_city (string) The shipping address’ city, in case of a physically delivered item. Example: San Mateo Deprecated: Use the equivalent field in the shipping addresses object.
shipping_region (string) The shipping region or state, in case of a physically delivered item. Example: California Deprecated: Use the equivalent field in the shipping addresses object.
shipping_country (string) The shipping country in ISO-3166 format, in case of a physically delivered item. Example: US Deprecated: Use the equivalent field in the shipping addresses object.
shipping_addresses (array(ShippingAddress)) An array of used shipping addresses.
merchant_id (string) The merchant’s unique ID, which can be used to disambiguate between several merchants. Example: af00-bc14-1245
merchant_created_at (number) The merchant’s registration date in milliseconds since the Unix Epoch (UTC), typically truncated to day resolution. Example: 1462891706
merchant_mcc (string) The 4-digit standard merchant category code (MCC). Examples: 7311, 2741. Example: 7311
merchant_email (string) The merchant’s email address. Example: [email protected]
merchant_country (string) The merchant’s country in ISO-3166 format. 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(Event)) List of events that represent changes in the payment state, such as successful bank authorization or a chargeback.
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 can typically be sent here are: “is-gift”, “is-po-box”.
String fields restrictions

All string fields that are not inside a user_defined object are limited to 255 characters in size.

Deprecated fields
Deprecated fields

For a smooth transition from previous API versions, existing card_* fields can be used as a shorthand for adding a single payment method of type card. Usage of card_* fields is always converted to injecting a primary payment method of type card.

If you fill in both the card_* fields and another primary payment method inside payment_methods, you will receive an error.

Similarly, existing shipping_* fields can be used as a shorthand for adding a single shipping address. Usage of the shipping_* fields is always converted to injecting a shipping address into the array.

If you fill in both the shipping_* fields and the shipping_addresses object, you might have duplicate addresses.

card_* and shipping_* fields are deprecated in favor of the payment_methods and shipping_addresses interfaces, respectively.

The following table presents the deprecated fields and which ones are recommended instead.

Deprecated field Recommended field
payment_method payment_methods.type
card_cvv_present payment_methods.cvv_check
card_hash payment_methods.card_hash
card_fullname payment_methods.card_fullname
card_exp payment_methods.card_exp
card_country payment_methods.card_country
card_bin payment_methods.card_bin
card_last4 payment_methods.last4
shipping_fullname shipping_addresses.fullname
shipping_phone shipping_addresses.phone
shipping_address_line1 shipping_addresses.address_line1
shipping_address_line2 shipping_addresses.address_line2
shipping_zip shipping_addresses.zip
shipping_city shipping_addresses.city
shipping_region shipping_addresses.region
shipping_country shipping_addresses.country

Item

The Item object represents a piece of merchandise that has been paid for within a transaction.

Name Description
item_id (string) A unique product ID in your system. Example: prod-1228
quantity (number) The purchased quantity of this specific item. Example: 3
name (string) The name of the purchased item. Example: Sci-Fi Compendium, 3rd Edition
price (number) 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
currency (string) The currency of the unit price (3-letter ISO 4217 currency code). If not specified, the currency for the overall amount will be used (see the top-level “currency” field) Example: USD
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: US
categories (object) 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”]]. **Note: Each element of a category hierarchy must not have “
is_promotion (boolean) Indicates whether there is currently a promotion on the item. Example: true
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 you can typically send here are: “gender”, “size”, “season”, “color”.

Payment method

The Payment method object represents how payment should be processed for a transaction.

Name Description
type (string, required) The type of the payment method. Check the supported types in the payment types reference. Example: card In case you require other types that are not listed, Feedzai will include support for them.
gateway (string) Payment gateway. Check the supported gateways in the gateway types reference. Example: adyen In case you require other gateways that are not listed, Feedzai will include support for them.
primary (boolean) If set to true, this is the method that can be shown in the alert list and that will allow more efficient search. If only a single payment method is provided, it will be automatically considered primary. If more than one method is provided, exactly one must be marked as primary. Example: true
id (string, required) The identifier of the payment method. Identifiers should be unique within the transaction, but not necessarily across all transactions. If two or more payment methods of a certain type are provided, all of them should have distinct ids. Example: a1ccb...5f7a8
amount (number, required) Amount, in cents, paid with this payment method. Example: 28000
currency (string, required) 3-letter ISO 4217 currency code that represents the currency of the amount field. Example: USD
status (string) The status of the payment with this method. The following statuses are allowed: “pending”, “authorized”, “captured”, “declined”, “cancelled”, “chargeback”. Example: pending
card_fullname (string) The cardholder name as appears on card. Example: JOHN S SMITH Supported only for the payment type card.
card_hash (string) Unique, consistent id/hash for the credit card. We recommend using a full, original PAN encrypted with SHA-512, salted. If you already have the full PAN encrypted in another way, you can send it like that. Example: a1ccb...5f7a8 Supported only for the payment type card.
card_pan (string) The full, original and unencrypted PAN. Feedzai is PCI-DSS compliant and will ensure that this information is securely stored and handled. Feedzai securely stores the card hash and generates a unique ID for the card. The ID is used subsequently. Example: 4427 4211 1111 1011 Supported only for the payment type card.
card_token (string) A token representing the PAN. Use the Card token registration endpoint to inform Feedzai of the mapping between PANs and Tokens. Example: a87f32eed63 Supported only for the payment type card.
card_bin (string) The original card number (PAN) first 6 digits. Not needed if PAN is provided. Example: 442742 Supported only for the payment type card.
card_last4 (string) The original card number (PAN) last 4 digits. Not needed if PAN is provided. Example: 1011 Supported only for the payment type card.
card_exp (string) The card expiration date in the MM/YY format. Example: 06/17 Supported only for the payment type card.
card_country (string) 2-letter ISO-3166 code that corresponds to the issuing country. Supported only for the payment type card. Example: US
auth_check (Check) The status of the Authorization check. Transaction Events can be used to update these checks. Supported only for the payment type card. Example:
cvv_check (Check) The status of the CVV check. Transaction Events can be used to update these checks. Supported only for the payment type card.
avs_check (Check) The status of the AVS (Address Verification System) check. Transaction Events can be used to update these checks. Supported only for the payment type card.
3ds_check (Check) The status of the 3-D Secure check. Transaction Events can be used to update these checks. Supported only for the payment type card.
chargeback_code (string) Chargeback code. Supported only for the payment type card.
user_defined (object) We support an unlimited number of extra user defined fields (string, boolean, or integer), that you feel might better inform our machine learning system.

Check

The Check object represents a payment verification performed on a transaction.

Name Description
status (string) Whether the check was “passed”, “failed”, “disabled” or if the check status is “unknown”. Example: passed
status_code (string) The response code provided by the payment network. Example: M
status_scheme (string) The vendor that supplied the value of the code field. Examples: “visa”,“mastercard”, “paypal”. Example: visa

Shipping address

The Shipping address object represents how the transaction items should be shipped to the customer.

Name Description
id (string, required) The identifier of the shipping method. This is used to distinguish between shipping addresses in the same transaction – i.e. it doesn’t need to be unique among different transactions. Example: 0
type (string, required) The type of shipping method used: “standard”, “expedited”, “digital”, etc. Check the supported types in the shipping address types reference. Example: physical In case you require other types that are not listed, Feedzai will include support for them.
carrier (string, required) The used shipping carrier. Check the supported carriers in the shipping address types reference. Example: ups In case you require other carriers that are not listed, Feedzai will include support for them.
primary (boolean) Indicates that this is the primary/default shipping address. If there is only one shipping address, this can be omitted, otherwise it must be specified for only one of the shipping addresses. Example: true
email (string) The email associated with the address. Example: [email protected]
fullname (string) The receiver’s name associated with the shipping address. Example: John Smith
phone (string) The shipping phone number, preferably with the country code and with no spaces or hyphens. Example: 0016502608924
address_line1 (string) The shipping address (line 1), in case of a physically delivered item. Example: 1875 South Grant Street
address_line2 (string) The shipping address (line 2), in case of a physically delivered item. Example: Suite 710
zip (string) The shipping address’ zip/postal code, in case of a physically delivered item. Example: 94402
city (string) The shipping address city, in case of a physically delivered item. Example: San Mateo
region (string) The shipping region or state, in case of a physically delivered item. Example: California
country (string) The shipping country in ISO-3166 format, in case of a physically delivered item. Example: US
user_defined (object) We support an unlimited number of extra user defined fields (string, boolean, or integer), that you feel might better inform our machine learning system.

Event

The Event object represents a change on the transaction state such as successful bank authorization or a chargeback.

Name Description
type (string, required) The type of payment event. Can be one of the following values: “3dsecure”,“authorization”, “capture”, “void”, “cancellation”, “chargeback” or “info”. The latter value can be used for updating the payment details, such as the amount and the user-defined fields. Example: 3dsecure
payment_method_type (string, required) The type of target payment method. Possible values are the same as supported for the payment methods’ type field. Example: 3dsecure
payment_method_id (string, required) The identifier of target payment method. It needs to correspond to a valid id in one of the payment methods included in the transaction. Example: a1ccb...5f7a8
successful (boolean, required) Whether the event was successful or not. Either successful or code must be defined. Example: true
code (string, required) Status or reason code as supplied by the vendor. Either successful or code must be defined. Example: “4845”, “05”, “B”. Example: 43
timestamp (number) The time of the event (in milliseconds since the Unix Epoch, UTC timezone). If omitted, then the request time is used. 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 (number) The amount of the event, in cents. Can be supplied only when the code is “info”, authorization”, “capture” or “cancellation”. In this latter case, the amount can be used to identify a partial cancellation. Example: 18000
currency (string) The currency of the amount (3-letter ISO 4217 currency code). Example: USD
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.

Score

The Score object represents the results of scoring a transaction with Feedzai.

Name Description
id (string) The ID of the received and scored payment. Example: 124212-00245
score (number) 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
decision (string) Indicates the outcome of Feedzai’s fraud analysis by indicating a recommendation based on the score. The decision can be “approve”, “review” or “decline”. Example: approve
warnings (array) Indicates if there were any notable warnings when processing the transaction. One notable example is when the provided card_token has no associated card_pan. Use this information to do adjustments to your integration or send new data after the transaction has been scored.
explanation (array(Explanation)) The explanation array 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. This field is only returned if explanations were requested by setting the URL parameter provideExplanations=true.
reason_codes (array(ReasonCode)) An array of reason codes returned. Each code provides high-level context on the decision (approve, decline, review). It can help you distinguish between transactions declined for fraud or for other types of abuse.

Explanation

The Explanation object represents a reason contributing to the score, i.e. a reason that leans either in favor or against of classifying the payment as fraud.

Name Description
description (string) Summary of this reason’s details. Example: Customer's credit card is linked to previous fraudulent transactions.
risk (number) An updated estimated fraud risk for the subset of payments similar to the current payment. Example: 0.5
confidence (number) The confidence that the system has in this particular reason, as an integer between 1 (lowest) to 5 (highest). Example: 5

Reason code

The Reason code object represents a high-level description of the decision (approve, decline, review). It can help you distinguish between transactions declined for fraud or for other types of abuse.

Name Description
name (string) The name of the reason code. Possible values will depend on your use cases.

Label

The Label object represents the fraud status of a transaction.

Name Description
label (enum, required) The payment label, denoting whether the payment was actually fraudulent (“fraud”) or legitimate (“ok”).
comment (string) Optional comment on the payment labeling.
timestamp (number) Represents when the payment labeling occurred.

Events list

The Events list object represents all the events you add to an existing transaction.

Name Description
events (array(Event), required) List of events that represent changes in the transaction’s state, such as successful bank authorization or a chargeback.

Historical payments

The Historical payments object represents a list of past transactions used to train Feedzai’s machine learning models.

Name Description
payments (array(HistoricalPayment)) An array of past payments and respective fraud label.
Historical payment object
Name Description
payment (Payment) A past payment. However, the timestamp field is mandatory.
label (enum) The optional label for this payment. Possible values are “ok” or “fraud”.

Cards

The Cards object represents the mapping between card numbers and respective tokenization.

Name Description
cards (array(CardToken)) An array with the cards to be registered.
Card token object
Name Description
card_pan (string, required) The plain-text card number. Example: 4111111111111111
card_token (string, required) The card token used in your system. Example: 9df27d6c-e5e1-4cb0-80e1-c7d6a55a0bd0
card_exp (string) The card’s expiration date in the format MM/YY. Example: 06/19
card_fullname (string) The cardholder name as appears on card. Example: JOHN S SMITH

Positive/negative list

The Positive/negative list value object represents the status of an entity in a positive/negative list.

Name Description
value (enum, required) The action to execute on the entity. Can be either “approve” (whitelist), “decline” (blacklist), or “review” (greylist).

List entry

The List entry object represents an entry of a generic list.

Name Description
comment (string) An optional comment to be associated with this list entry.
active_from (number) The (optional) epoch from which the list entry is valid from.
active_until (number) The (optional) epoch until which the list entry is valid.
enabled (boolean) Whether this entry is enabled. By default it is set to true.
value (object, required) An object containing the fields of the list entry. These fields must match the specified schema for the list.

Payment types and Gateways

Supported Payment types

Supported types of payment, specified in the payment_methods.*.type field of the Payment method object.

payment_methods.*.type
offline_bank_transfer
realtime_bank_transfer
card
cash
cash_on_delivery
check
crypto_currency
digital_wallet
direct_debit
gift_card
store_credit
voucher
invoice
external_provider
Supported Gateways

Supported types of gateways, specified in the payment_methods.*.gateway field of the Payment method object.

payment_methods.*.gateway
adyen
affirm
alipay
altapay
amazon_payments
applepay
astropay
authorizenet
balanced
banwire
beanstream
blockchain
bluepay
bluesnap
braintree
buckaroo
ccavenue
chain_commerce
chase_paymentech
checkout_com
cielo
circlek
cofinoga
coinbase
collector
compropago
conekta
cuentadigital
culqi
cybersource
datacash
debitway
dibs
digital_river
dragonpay
edgil_payway
elavon
epayeu
eprocessing_network
eway
family_mart
first_atlantic_commerce
first_data
g2apay
giropay
global_payments
global_payways
globalcollect
gocardless
hdfc_fssnet
hipay
ideal
ingenico
internetsecure
intuit_quickbooks_payments
iugu
jabong
klarna
konbini
lawson
mastercard_payment_gateway
mercadopago
merchant_esolutions
mini_stop
vmirjeh
moip
mollie
moneris_solutions
moneygram
nmi
ogone
okpay
omise
openpaymx
optimal_payments
pagar_me
pagofacil
pagseguro
paxum
payeasy
payeer
payfast
paygate
payment_express
paymentwall
paymill
payone
paypal
paysera
paysimple
paystation
paytrace
paytrail
payture
payu
payulatam
payza
peach_payments
perfect_money
pinpayments
pivotal_payments
planet_payment
princeton_payment_solutions
psigate
qiwi
quickpay
aberil
rbkmoney
rede
redpagos
redsys
rewardspay
rietumu
rocketgate
sagepay
seico_mart
sermepa
seven_eleven
simplify_commerce
skrill
smart2pay
smartcoin
sofort
sps_decidir
stone
stripe
synapsepay
telerecargas
tenpay
tnspay
towah
transact_pro
transfirst
trustcommerce
trustly
twocheckout
unionpay
usa_epay
vantiv
venmo
veritrans
versapay
vesta
vindicia
virtual_card_services
vme
webmoney
webpay_oneclick
wechat
wepay
western_union
wirecard
worldpay
worldspan
xipay
yandex_money

Shipping address types and Carriers

Supported Shipping address types

Supported types of shipping types, specified in the payment_methods.*.type field of the Shipping address object.

shipping_addresses.*.type
digital
standard
expedited
Supported Shipping carriers

Supported types of shipping carriers, specified in the payment_methods.*.carrier field of the Shipping address object.

shipping_addresses.*.carrier
ctt
ups
usps
fedex
sagawa
ems
dhl
email
sms

Copyright &copy Feedzai. All rights reserved.