Primer Docs

Sift provides a comprehensive fraud prevention solution that combines advanced machine learning techniques with real-time data analysis to help businesses detect and prevent fraudulent activities, protect their users, and maintain the integrity of their platforms.

Sift helps businesses to make accurate, real-time decisions that both improve user experience and increase revenue. You can use Sift whether you’re building a brand new risk system or looking to augment an existing legacy system.

See our Fraud Overview for more general information about how we support fraud prevention.

Sift-Specific Concepts

Decisions: Decisions represent business actions taken on an order-level or user-level. You use decisions to record what has happened. Sift uses this information to continuously improve the accuracy of your risk scores. Sift allows users to add decisions and have a lot of flexibility.
Workflow: In addition to Primer workflows, you will need to set up order and transaction level workflow in your Sift Dashboard. We take you through the required steps below.

Instructions

Set up Sift decisions

For the integration to work with Primer add decisions similar to these:

decisions

Go to Automate > Decisions
Create or edit your Sift decisions, for both orders and users, using the following categories:
- Category "Block"
- Category "Watch"
- Category "Accept"
Sift will generate IDs for these decisions, take note of these IDs.

Set up a Sift integration

Go to your Primer Dashboard.
Navigate to the "Integrations" section, select "Add Integration" at the top of the page and search for Sift. Follow the dashboard instructions.
For sandbox testing make sure you have enabled sandbox mode on your Sift account. Click on the account icon and toggle "Sandbox".
Go to your Primer dashboard, go to your Sift integration, and paste any relevant decision ID from Sift into the following fields:
- Sift order 'Pass' decision ID
- Sift order '3DS' decision ID
- Sift order 'Reject' decision ID

Required fields

For card payments, the following fields have to be passed for Sift to accept the request.

Field	Type
`customerId`	string
`customer.emailAddress`	string

We recommend passing as many customer fields as you have available to create a more accurate fraud profile for the customer.

Additional field mappings

Advanced Metadata Mapper is supported via Sift. You can map Sift's Complex Field Types, such as booking-type objects specific to your industry, directly from the integrations dashboard.

Please note you will not be able to override fields that have already been mapped by Primer such as payment_method, browser and merchant_profile.

Using Sift via the Payments app

Using the Payments app in a Primer workflow, you can optionally enable the following fraud checks:

Pre-authorization -> We trigger a $create_order event on Sift.
Post-authorization -> We trigger a $create_transaction event on Sift

Note that setting up fraud checks is optional. You can also set up a pre-authorization check only and omit post-authorization.

The fraud check can then result in on of:

Pass
3DS (pre-authorization only)
Reject
Fail

Follow the Primer Workflows for fraud checks guide to set up the app.

Set up pre-authorization Sift workflow

Navigate to your Sift account dashboard
Go to Automate > Workflows
Set up a pre-authorization (create order) Sift workflow
- Add new Workflow
- Set Type of Workflow to: "Payment protection"
- Set Triggered on which Events to "Create order"
- Set your Sift workflow routes to use some or all of the three Sift decisions defined above
- Set to Always Run

decisions

Set up post-authorization Sift workflow

Navigate to your Sift account dashboard
Go to Automate > Workflows
Set-up a post-authorization Sift workflow
- Add new Workflow
- Set Type of Workflow to: "Payment protection"
- Set Triggered on which Events to "Transaction"
- Set your Sift workflow routes to use the order_looks_ok and order_looks_bad Sift decisions
- Set to Always Run

decisions

Testing

See our Get Started guide for an example Client Session to use for testing.

Pre-authorization fraud check

Set up your workflow with an "Authorize payment" action and a pre-auth fraud check as described above.

To trigger a Pass outcome, set customer.emailAddress to start with out_of_scope.
To trigger a Reject outcome, set customer.emailAddress to start with fraud.
To trigger a 3DS outcome, set customer.emailAddress to start with sca.
To trigger a Fail outcome you will need to pass a request that is incorrect. An example of this is to set the currency to something as this field needs to be a recognised currency code.

Post-authorization fraud check

Set up your workflow with an "Authorize payment" action and a post-auth fraud check as described above.

To trigger a Pass outcome, set customer.emailAddress to equal test@approve.com
To trigger a Reject outcome, set customer.emailAddress to equal test@decline.com

Using the Sift app

Primer provides a Sift app for conveniently interacting directly with Sift.

The following actions are supported:

Apply decision -> Using Sift's API we can apply decisions on specific orders or customers.
Create account event -> We trigger a $create_account event on Sift
Update account event -> We trigger a $update_account event on Sift
Link a session to a user id -> We trigger a $link_session_to_user event on Sift

Apply user or order decision

After configuring your Sift decisions (see instructions above), you can use the Sift app to apply these decisions to a specific customerId or orderId.

Link session to user

Use this action to associate data from a specific session to a user. Generally used only in anonymous checkout workflows. This action can be used in workflows either as part of a payment flow, if a session ID is also passed in, or outside. If a session needs to be linked to a user at different points in the customer journey, a custom workflow using the Primer Web Requests app can be set up.

Create or update account

This serves to inform Sift of a new customer or an existing customer using a new payment method. Based on the current payment and the data provided on the client session, we determine whether to trigger a "create account" or "update account" event.

The outcome of the action could be either ACCOUNT_CREATED, ACCOUNT_UPDATED or NO_ACCOUNT_ACTION_TAKEN (if neither happened).

Below is an example of how this action could be used in a workflow

workflow

Optionally you can set up a Sift workflow for $create_account and $update_account events. If you do, then go to your Primer dashboard and to your Sift integration, and paste any relevant decision ID from Sift into the following fields:

Sift account 'Pass' decision ID
Sift account 'Monitor' decision ID
Sift account 'Reject' decision ID

Create account

This case will be triggered if it is a brand new customer, i.e. you are using a new customerId when creating a client session.
The resulting output status will be ACCOUNT_CREATED and optionally would have a Sift decision_id depending on whether you configured a Sift workflow to trigger on a $create_account event.

It is recommended that you vault a customer’s payment method using the vaultOnSuccess flag. This is to ensure if they use the same card, it won’t be seen as an "update" event.

If you populate the customer.emailAddress, customer.billingAddress or customer.shippingAddress, these values will be mapped and sent to Sift for $create_account events.

Update account

This case will be triggered in the case of a returning customer, i.e. you are using the same customerId when creating a client session, but they are using a new payment method, i.e. a new card that was not vaulted before.
The resulting output status will be ACCOUNT_UPDATED and optionally would have a Sift decision_id depending on whether you configured a Sift workflow to trigger on an $update_account event.

Crucially a card is considered new if it has not been "vaulted" before.

No action

If you are referencing an existing customer using a previously vaulted card, then a new account won’t be created and neither will any be updated.
The resulting output status will be NO_ACCOUNT_ACTION_TAKEN and naturally there will be no decision_id.

Testing

See our Get Started guide for an example Client Session to use for testing.

Create or update account action on Sift app

→ Ensure you have a workflow set up with a "Payment created" trigger and the Sift app "Create or update account" action. We recommend having an "Authorize payment" action in the same workflow after your Sift action, to ensure the payment is authorized and the card is vaulted. See example below.

auth_workflow

To trigger a ACCOUNT_CREATED output on the Sift app, create a new payment using the client session mentioned above. Since you are also authorizing the payment, the card used should now be vaulted.
To trigger a ACCOUNT_UPDATED output on the Sift app, create a new payment using the client session mentioned above, however use a new test card (you can just change the expiration date and it should be considered to be "new").
To trigger a NO_ACCOUNT_ACTION_TAKEN output on the Sift app, Create a new payment using the same client session above and use the same payment method that was vaulted before.

You can repeat the tests above after having set up Sift workflows to "watch", "block" or "accept" specific accounts. Then there should also be a decision_id on the output of the Sift action.