Embedded Fraud

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, so the merchant is not required to manage this piece of the workflow.

Create a Test Fraud Vendor

Spreedly supports a test vendor that mocks responses based on the vendor-specific parameter test_scenario. This test vendor can be used with the Spreedly Test Gateway and any other sandbox gateway connection as long as the test_scenario is also provided in the transaction.

To create a Fraud Vendor, send a request to https://core.spreedly.com/v1/fraud_control/vendors.json

{  
  "fraud_control_vendor": {  
    "type": "test",  
    "sandbox": true  
  }  
}

Spreedly will respond with a fraud control vendor token:

{
    "fraud_control_vendor": {
        "token": "SVNCAMF9M98VG67FS9MTF7A",
        "sandbox": true,
        "created_at": "2024-02-12T18:08:48Z",
        "updated_at": "2024-02-12T18:08:48Z",
        "type": "test"
    }
}

Initiate Fraud Check on Authorization or Purchase

Use the token from the previous step in Purchase/Authorize requests 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:

• fraud_control_vendor_key - fraud_control_vendor token from the previous step
• fraud_detection_parameters - this is the parent level object that contains information specific to the fraud transaction
• pre_authorization_check - true
  • currently Spreedly only supports pre-authorization fraud detection during a transaction
• vendor_specific_fields - Vendor-specific parameters
  • Similar to Spreedly's "Gateway Specific Fields", some fraud vendors will need individualized information that can not be normalized by Spreedly. These fields should be sent in this parameter and can be found on each fraud vendor's specific page.
  • Spreedly has also created fields in this object that are not specific to any one fraud vendor, but are only used for Fraud checks and not transactions. These fields will not be nested underneath a specific vendor.
    • cart_items is an array of objects. Each object contains desc, item, price, quantity, and type. These can be sent to provide more information about what is being purchased and may be required for some specific Fraud Vendors.
    • All of these values are strings

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.

Initiate Test Fraud Check

Add the fraud check to a Purchase or Authorization within the transaction object :

{
  "transaction": {
    // standard transaction params
    "fraud_control_vendor_key": "{{test_fraud_control_vendor}}",  
    "fraud_detection_parameters": {  
        "pre_authorization_check": true,  
        "vendor_specific_fields": {  
          "test_scenario": "approved"  
        }  
    }
  }
}

If using a Spreedly Test Fraud Vendor, the test_scenario of approved or declined can be supplied in vendor_specific_fields in order to dictate the outcome.

Spreedly Fraud Check Response

The transaction response will include new fraud detection objects (fraud_detection_pre_authorization) with some data that was sent to a fraud vendor and the vendor's response.

Transaction Identifiers

There are two main identifiers to record in the response: Spreedly's transaction identifier and the fraud providers:

• vendor_transaction_id - This is the identifier of the transaction with the fraud vendor
• token - this is the identifier of the Fraud Detection transaction at Spreedly

We recommend recording these for your records on every transaction. The Spreedly token value can be used with our transaction lookup tools in the Spreedly Application or the API.

Results of the Fraud Detection Transaction

The main fields that can be used to determine fraud check results are:

• state - indicates the status of request to a fraud vendor: succeeded, failed
• reason_code - vendor’s code (if it exists)
• message - based on the response from the vendor, we will set it to Approved, Declined, Indeterminate, Manual Review, or Step Up Auth
  • If the response is Approved, Indeterminate, Manual Review, or 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
  • If there is an error from the vendor, that error message will be passed through in this field

Detailed Response

Spreedly will also provide a vendor_response object which contains specific individualized response information from each vendor.

Spreedly’s response fraud_detection_pre_authorization object on the Purchase / Authorization API response will be:

"fraud_detection_pre_authorization": {  
  "created_at": "2022-02-01T15:03:10Z",  
  "updated_at": "2022-02-01T15:03:10Z",  
  "succeeded": true,  
  "state": "succeeded",  
  "token": "JTJgG8ciuGTSKiWJZ8Gab41EFm6",    
  "amount": 100,  
  "currency_code": "USD",
  "ip": "",
  "email": null,
  "order_id": null,  
  "transaction_type": "FraudControl::Detection",  
  "reason_code": null,    
  "vendor_transaction_id": "KK430MTDC5N7",
  "message": "Approved", // Spreedly's decision mapping  
  "fraud_control_vendor_key": "Xl5GsGWKAOSrrFwjF59dClyA",
  "vendor_response":{}
}

The token object represents Spreedly's identifier for the fraud portion of the transaction flow. It can be used with the Transcript endpoint to see Spreedly's interaction with the fraud vendor.

Initiate a Fraud Check When Adding a Card to the Vault

📘

If you would like to utilize this feature, please reach out to your Customer Success Manager

Use the Fraud Vendor token in Add Card API requests along with some other parameters that are required to complete a fraud check. Spreedly will not make any decision around redacting or retaining a card based on the fraud response.

Fraud Detection Transaction Parameters

The transaction parameters needed during adding a card are the mostly same as the parameters needed during an Authorize or Purchase. The main parameters are:

• fraud_control_vendor_key - fraud_control_vendor token from the previous step
• fraud_detection_parameters this is the parent level object that contains information specific to the fraud transaction

Spreedly will default to $0 USD if the vendor requires and amount and currency. If there are other vendor specific required fields, you will need to supply them in the vendor_specific_fields.

Initiate Test Fraud Check

The difference between the fraud detection parameters during an Authorize or Purchase and a Create payment method is that you will need to include card_add_check: true instead of pre_authorization_check: true.

Add the fraud check to an Add Card API request:

"email": "{{Email}}",
"ip":"{{IP}}",
"fraud_control_vendor_key": "{{test_fraud_control_vendor}}",  
"fraud_detection_parameters": {  
    "card_add_check": true,  
    "vendor_specific_fields": {  
      "test_scenario": "approved"  
    }  
}

If using a Spreedly Test Fraud Vendor, the test_scenario of approved or declined can be supplied in vendor_specific_fields in order to dictate the outcome.

Spreedly Fraud Check Response

The transaction response will include new fraud detection objects (fraud_detection_card_check) with some data that was sent to a fraud vendor and the vendor's response.

Transaction Identifiers

There are two main identifiers to record in the response: Spreedly's transaction identifier and the fraud providers:

• vendor_transaction_id - this is the identifier of the transaction with the fraud vendor
• token - this is the identifier of the Fraud Detection transaction at Spreedly

We recommend recording these for your records on every transaction. The Spreedly token value can be used with our transaction lookup tools in the Spreedly Application or the API.

Results of the Fraud Detection Transaction

The main fields that can be used to determine fraud check results are:

• state - indicates the status of request to a fraud vendor: succeeded, failed
• reason_code - vendor’s code (if it exists)
• message - based on the response from vendor we will set it to Approved, Declined, Indeterminate, Manual Review, and Step Up Auth
  • Spreedly does not take any action on the payment method, no matter the response message
  • The response can be: Approved, Indeterminate, Manual Review, Step Up Auth, or Declined
  • If there is an error from the vendor, that error message will be passed through in this field

Detailed Response

Spreedly will also provide a vendor_response object which contains specific individualized response information from each vendor.

Spreedly’s response fraud_detection_pre_authorization object on the Purchase / Authorization API response will be:

"fraud_detection_card_check": {
  "created_at": "2024-04-08T20:24:00Z",
  "updated_at": "2024-04-08T20:24:00Z",
  "succeeded": true,
  "state": "succeeded",
  "token": "7Q1zkYvsQ8OJ0yIjR5UFSWeiXu",
  "amount": 0,
  "currency_code": "USD",
  "ip": "158.179.84.103",
  "email": "[email protected]",
  "order_id": null,
  "transaction_type": "FraudControl::Detection",
  "message": "Approved",
  "fraud_control_vendor_key": "5SVN7FCAMF98VG67FS9MTF7A",
  "vendor_transaction_id": null,
  "vendor_response": null
}

The token object represents Spreedly's identifier for the fraud portion of the transaction flow. It can be used with the Transcript endpoint to see Spreedly's interaction with the fraud vendor.

Order Status Updates

Some Fraud providers require updates to transactions to indicate successful completion, voids, refunds etc. When a customer completes an action via Spreedly, such as a void or refund, Spreedly automatically handles updates to these vendors on order status updates in the backend on behalf of the customer, no additional steps are required.

Since there is no order during Card Add, this update is not sent for those transactions.