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.

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 account on behalf of the merchant. This will allow you to start sending the approprate data to Sift.

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 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 'https://api3.siftscience.com/v3/partners/{parnter ID}/accounts' \n  -H 'Content-Type: application/json' \n  -u {YOUR_API_KEY}: \n  -d '{
  "site_url" : "merchant123.mypaymentgateway.com",
  "site_email" : "owner@merchant123.com",
  "analyst_email" : "john.doe@merchant123.com",
  "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, 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 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 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 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 Business Decisions

Whenever your automated systems or analysts take action, send those actions into Sift as Decision events. Actions range from positive (eg Approve Order), to neutral (Flag Account), to negative (Ban User). The key thing is that you should send all Actions you take to Sift, not just your negative actions.

Set up your Business Decisions

In order to send Decision events you'll first have to create the specific Decisions your business takes in the Sift Console. While we start all accounts out with a few generic Decisions, Decisions are fully customizable so you can create a Decision for every action that your business takes. Some examples of Decisions are:

  • Ban Account (Block Category Decision)
  • Cancel Order (Block Category Decision)
  • Flag for Additional Review (Watch Category Decision)
  • Approve User (Accept Category Decision)

See the Decisions tutorial for more context.

During your integration, you should send the Decisions that your business is currently making through any internal fraud engines or Manual Review processes to the Sift Decisions API. If you currently do not have in-house fraud logic or a manual review process, work with Sift to setup your initial Workflows within Sift's platform.

Get Started with Sift Scores

When you are initially integrating with Sift, your scores will be based on whatever data you’ve sent us. So if it is a brand new integration with no backfilled data, Sift will need a week or two of data to learn your unique fraud patterns. One of the key strengths of the Sift platform is that it consistently learns as you send more and more data to it. You should see a substantial increase in accuracy of your scores during these first weeks as you send more Decisions and User Events.

During this stage, you should be assessing your Sift Scores in the Sift Console and determining which actions you want to take for different score ranges. Since all businesses are different, finding your unique score thresholds that achieve your business goals is key.

To reduce the amount of time required in this initial learning phase, you can send a historical backfill so that Sift can learn about your user's fraud patterns.

Build Your Business Logic With Sift Scores

Now that you sending both user events and business decisions to Sift, you’re ready to start using Sift Scores in your business logic. At this point, you’ll have an understanding how scores correlate to different levels of risk. Based on the user’s risk score, you’ll set up different outcomes within your application (eg users with low score are automatically approved).

To build this logic, you'll want to evaluate a user's Sift Score at the key events where bad users can hurt your business or good users can have a more frictionless experience.

The two ways to use Sift Scores:

  • Create a Sift Workflow: Sift Workflows give you a powerful way to automate your Decisions without having to write business logic on your side. Workflows let you set up rules that gets evaluated whenever specified events occur. These rules enable you to route users to different outcomes based on Sift Score and other attributes of the user and transaction (eg User is from Canada, Order is greater than $500, and Sift Score is greater than 80). With Sift Workflows, you also get Sift Review Queues for fast, easy investigation so you won’t have to build your own queues. To learn more, see our Workflows documentation.
  • Build application logic in your system: You can synchronously request the Sift score of a user with any event you send to Sift. This score will take into consideration all data you’ve sent to Sift including the event you just sent. Sift Scores should only be requested at the key events where fraud or abuse occurs (eg ask for score when sending a Create Order event) To learn more, see our API documentation

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