Layer 1 copy

Use Case

This guide is written for companies offering payment processing solutions to various types of merchants. These include payment gateways, payment facilitators, PSPs, payment aggregators, and payment platforms. Use the Partner API to create accounts for each of your merchants, and use Sift Scores to stop transactions that would result in chargebacks before you push the transaction to the payment networks.

Before You Start

Before proceeding, please be sure that you have applied for a Partner Account with Sift Science. This will enable you to create and manage Sift Science accounts on behalf of your merchants programatically. You can do this here.

Integration Recommendations

The integration includes two parts:

Adding a New Merchant to Your Platform

Whenever a new merchant joins your platform, use this Partner API call to programatically create a Sift Science account on behalf of the merchant. This will allow you to start sending the approprate data to Sift Science.

Why Create an Account Per Merchant?

With a dedicated account, each of your merchants will be provisioned a unique machine learning model. This allows Sift Science to learn the fraud patterns specific to each of your merchants, rather than treating all merchants the same.

The analyst_email and password fields can be those of an internal team member who will be managing fraud for the merchant, or those of the fraud manager working at the merchant company. The site_url field should follow the format of {customer name}.{your company name}.com. See example request below:

$ curl -XPOST '{parnter ID}/accounts' \
  -H 'Content-Type: application/json' \
  -u {API_KEY}: \
  -d '{
  "site_url" : "",
  "site_email" : "",
  "analyst_email" : "",
  "password" : "s0mepA55word"

The response will contain a set of API keys that you will use to send data on behalf of this merchant. See the example response below:

  "account_id" : "545d48e84d6963acf1000000",
  "production" : {
    "api_keys" : [ {
      "id" : "545d491c4d6963acf12d0000",
      "state" : "ACTIVE",
      "key" : "34fc67af86069804"
    } ],
    "beacon_keys" : [ {
      "id" : "545d491c4d6963acf12e0000",
      "state" : "ACTIVE",
      "key" : "735ea65235"
    } ]
  "sandbox" : {
    "api_keys" : [ {
      "id" : "545d491c4d6963acf1300000",
      "state" : "ACTIVE",
      "key" : "1f46f7f726607c1b"
    } ],
    "beacon_keys" : [ {
      "id" : "545d491c4d6963acf1310000",
      "state" : "ACTIVE",
      "key" : "63d0d7605c"
    } ]

The Per Merchant Integration

For each merchant whom you onboard onto Sift Science, you will want to take the following integration steps. This will allow you to collect the appropriate data and feedback from your merchants to provide Sift's fraud prevention to them. Be sure to validate that the correct API key is being used for the correct merchant.

JavaScript Snippet Integration

JavaScript Snippet Requirements

This section is only applicable if you support a hosted payment page and/or have the ability to place JavaScript onto your merchant's site. If neither or these situations apply to you, please skip to the next section.

Place the JavaScript Snippet on your hosted payment page and/or place it onto your customer's checkout page, at minimum. Adding it to as many other merchant pages as possible increases our score accuracy because it allows Sift Science to detect additional behavioral signals. Please follow the Javascript Snippet tutorial.

  • Set the _session_id variable in the JavaScript Snippet to a unique session ID. You will link this session ID to the user later in the payment flow.

Merchant Submits a Transaction

Whenever a merchant sends you a transaction to process, you will want to take the following steps:

  • Send Sift Science a $create_order event with as many fields filled out as are applicable
  • If you capture item data, send an $item for each item purchased by this transaction
  • The $user_id sent with this event should be the email address of the user transacting. It can also be a unique account identifier if end users can create accounts with your service.
  • Set the $session_id to the same value used in the _session_id field on the JavaScript snippet from the last step. This will link the pageview to this user.
  • Include a custom field in the $create_order event called merchant_id. This field's value should be the unique identifier of the merchant who sent you this transaction. It could be the merchant's name or other internal ID, and should be sent as a String.

Whenever you push a transaction to your payment network, do the following:

  • Send Sift Science a $transaction event to capture each interaction with your payment network. Fill out all applicable fields and include a $transaction_status (either $success or $failure) depending on whether you were able to charge the payment instrument or not.

Send Feedback to Sift

One of the key strengths of the Sift Science platform is that as you give it feedback it continues to learn and adapt to patterns. By providing continuous feedback on who your good and bad users are, we will evolve our detection and improve the accuracy of risk scores. You’ll be able to stop bad actors even as they change their attack vectors. In addition to sending an optional historical backfill:

  • Create a Feedback focused Workflow where you review high scoring users and tell us how well we are predicting your fraudsters.
  • If you are already doing manual review in your existing system, just send the outcome of each review to our Labels API

Once you’re up and running with Sift, continuing to send feedback will improve your score accuracy in real-time, catching bad users as soon as they appear. This is an important part of a successful integration.

Make Decisions with Sift

Scores are an indication of how risky a user is for a given abuse type. You can use these scores as a means to block bad users, add friction to users you are unsure about (e.g., SMS verification), and let good users sail right through. You’ll likely be making this check at $create_order.

The two ways to do this are:

  • Create a Sift Workflow You can build merchant-level criteria that get evaluated whenever specified events occur. Learn more in our Workflows tutorial.
  • Build application logic in your system An alternate approach is to request abuse specific risk scores to be returned in the response of the user events you send. See our API documentation

Any questions? We're happy to talk it through.