> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sift

> Connect to Sift for machine learning-based fraud detection and prevention.

Sift is a technology company specializing in digital trust and safety. Founded in 2011
and headquartered in San Francisco, Sift provides machine learning-based fraud detection
and prevention solutions. Its platform helps businesses prevent various types of online
fraud, including payment fraud, account takeover, content abuse, and fake accounts.

## Credentials

To configure a Sift connection, you need to set the
following credentials. Each of these can be found in the [Sift portal](https://console.sift.com)
under the Developer menu.

| Credential | Description                                               |
| :--------- | :-------------------------------------------------------- |
| Account ID | Your unique Sift account ID                               |
| API key    | The secret API key for use with the Sift API              |
| Beacon Key | The secret key used in the Sift JS fingerprinting snippet |

## Merchant information

Additionally, some optional merchant configuration can be set.

| Credential      | Description                                                               |
| :-------------- | :------------------------------------------------------------------------ |
| Site country ID | Country the company is providing service from. Use ISO-3166 country code. |
| Site domain     | Domain being interfaced with. Use fully qualified domain name.            |

## Decision mapping

Decisions received from Sift are mapped to the decisions according to the following logic.

| Sift decision | Decision |
| :------------ | :------- |
| `accept`      | `accept` |
| `block`       | `reject` |
| `watch`       | `review` |
| other         | `error`  |

If any of the data requirements below are not met, the decision is `skipped`. Additionally,
if a decision could not be made but has been marked for review, a `review` status is returned.

All decisions need to set the **Entity** to **Orders**, otherwise the mapping between
the Sift decision won't be possible and it'll be considered an `error`.

## Webhooks for manual review

To enable manual review you need to set up webhooks from your anti-fraud service to the system. This
webhook is used to notify the system when a review is accepted or rejected.

To get the webhook URL, head over to your connection by going to **Connections** ->
**\[Anti-Fraud connection]** -> **Synchronization** and copy the webhook URL.

Next, login to Sift portal and navigate to the **Automate** -> **Decisions** panel to
set a [payment abuse event](https://console.sift.com/decisions?abuse_type=payment_abuse) for both
a blocked and an accepted review.

Click on **Create Decision**, and fill in the following.

* Set the **Entity** to **Orders**
* Set the category to **Block** or **Accept**
* Set the webhook URL to the one copied from the dashboard
  * Sift's webhook version 1.2 is required. Please contact Sift support to confirm
    the version used.
* Set a name and description

Save the changes, making sure to create a decision for both the **Block** and **Accept** category.

Make sure to use these events when handling a manual review of an order in the Sift portal to
notify the system.

<Warning>
  When a transaction is marked as in-review by Sift, and the manual review queue
  has been enabled, then the transaction is held in authorized state. If
  that authorization fails, or if a user manually voids/captures the transaction
  in the dashboard, the anti-fraud provider is usually contacted to clear
  that review from the queue. This feature is not available for Sift, so please
  note that there might be orders on the review queue that have actually already
  failed, been voided, or were captured.
</Warning>

## Rejections

An order can be auto-rejected by sending a `rejected_by_gr4vy_payment_abuse` decision to Sift. This is
sent when the transaction is declined or the payment service. To handle this event, please
set up a decision for payment abuse in the Sift portal.

Login to Sift portal and navigate to the **Automate** -> **Decisions** panel to
set a [payment abuse event](https://console.sift.com/decisions?abuse_type=payment_abuse) for a blocked
transaction.

Click on **Create Decision**, and fill in the following.

* Set the **Entity** to **Orders**
* Set the category to **Block**
* Leave the webhook URL empty
* Set the name to **Rejected by Gr4vy**

## Device fingerprinting

The use of device fingerprinting is highly recommended when using Sift. Please refer to the
[device fingerprinting guide](/guides/features/anti-fraud/fingerprint) for more information on the universal solution.

If needed, you could load the [fingerprint script for Sift][script] directly and pass the `_session_id`
value as the `anti_fraud_fingerprint` to the [new transaction API](/reference/transactions/new-transaction).

[script]: https://developers.sift.com/docs/curl/javascript-api/overview