Spreedly’s embedded fraud service allows a merchant to initiate a fraud check with a third party fraud vendor in the same request as an authorization or purchase. The intention is to reduce the number of distinct integrations and API calls a merchant must make to process both a fraud check and an authorization request on the same transaction attempt. This fraud check is executed as a pre-authorization fraud check, meaning the fraud check is completed before submitting the transaction to the gateway for authorization. In this flow authorization is only attempted if the fraud check results in a positive signal from the fraud vendor, otherwise authorization is not attempted. This orchestration of events is managed internally by Spreedly, a customer is not required to manage this piece of the workflow.
Adding Fraud Vendors
Adding a Test Vendor
Spreedly supports a test vendor that mocks response based on the vendor specific parameter test_scenario. 2 scenarios can be requested: approve and declined. Also, it supports pre authorization by passing the setting pre_authorization_check on Authorize or Purchase calls.
1{ |
Adding Forter as a Vendor
Customers need to register with Forter and create Forter Vendor with Spreedly using our endpoint for creating vendors /v1/fraud_control/vendors.json.
Create vendor request
1{ |
Create vendor response
1{ |
Customers need to pass the created token into the fraud_control_vendor_key field when requesting fraud checks on Purchase or Authorize transactions.
Initiate Fraud Check on Authorization or Purchase
Use the token from the previous step in Purchase/Authorize request along with some other parameters that are required to complete a fraud check.
Fraud Detection Transaction Parameters
There are 2 groups of parameters that are needed on Purchase and Authorize transactions in order to perform fraud detection:
- Standard parameters - fraud_control_vendor_key (fraud_control_vendor token from the previous step), pre_authorization_check
- Vendor specific parameters - vendor_specific_fields
The fraud_detection_parameters and fraud_control_vendor_key are only accepted on Purchase and Authorize transactions. If the fraud_detection_parameters are submitted for other types of transactions the error "fraud_detection_parameters are only accepted on Purchase and Authorization transactions" is returned and the transaction is marked as failed.
The transaction response will include fraud_detection objects (fraud_detection_pre_authorization) with some data that was sent to a fraud vendor. The main fields that can be used to determine fraud check results are:
- action - vendor’s response message if exists
- state - indicates the status of request to a fraud vendor - succeeded, failed
- reason_code - vendor’s code if exists
- message - based on the response from vendor we will set it to Approved, Declined, Indeterminate, Manual Review, and Step Up Auth
If the response is Approved, Indeterminate, Manual Review, and Step Up Auth we will record that but will carry on with the transaction.
If the response is Declined on a pre authorization check we will mark a transaction as Failed and will not make a call to the gateway
Initiate Test Fraud Check
Add the fraud check to a Purchase or Authorization
1"fraud_control_vendor_key": "{{test_fraud_control_vendor}}", |
Initiate Forter Fraud Check
When Spreedly makes a request to Forter we map all data we have to the Forter API schema on behalf of the customer. When a data point is already available in the Authorize or Purchase call, Spreedly internally maps those fields to the Forter schema. Forter has additional fields some of which are required, others are optional.
The minimum parameters that are needed for a Fraud detection request are fraud_control_vendor_key, fraud_detection_parameters, fraud_detection_parameters include pre_authorization_check / post_authorization_check and vendor_specific_fields. Forter has some required vendor_specific_fields. An example for a pre_authorization_check request with all required parameters is below.
1{ |
Besides required vendor_specific_fields for Forter, there are other optional fields that Spreedly supports. An example with all fields below:
1{ |
Spreedly Fraud Check Response
After we process Forter’s response and mapped it to standard Spreedly’s response fraud_detection_pre_authorization object on the Purchase / Authorization API response will be:
1"fraud_detection_pre_authorization": { |
Order Status Updates
Forter requires updates to transactions to indicate successful completion, voids, refunds etc. When a customer completes an action via Spreedly such as void or refund,Spreedly automatically handles updates to Forter on order status updates in the backend on behalf of the customer, no additional steps are required.