Send Antifraud Pre-Analysis Data (optional)

Receives a new transaction antifraud data for (synchronous) pre-analysis. This step is performed before payments authorization.

WARNING


  • The pre-analysis does not exclude the need for full analysis after payments authorization

REQUEST HEADERS


Header Value
X-PROVIDER-API-AppKey {{X-PROVIDER-API-AppKey}}
X-PROVIDER-API-AppToken {{X-PROVIDER-API-AppToken}}
Content-Type application/json
Accept application/json

REQUEST BODY


Name Type Mandatory Description
reference string max 255 chars Yes VTEX order reference key. The key of the order (from VTEX OMS system) related with this payment
id string max 255 chars Yes VTEX transaction ID. The ID of the transaction related with this payment.
value decimal ex 20.95 Yes VTEX transaction order value
ip string ip format Yes The original ip addres from browser
deviceFingerprint string Device fingerprint generated by the provider. This is generated by using Google Tag Manager that the provider implements. This field is optional, is sent only if received. See Implement Device Fingerprint
store string Yes VTEX has a main Name for the store. This unique name is often used in url to access VTEX configurations.
miniCart object Yes Mini cart data
buyer object Yes Buyer data
     ↳ id string Yes VTEX buyer ID. The unique identifier of the buyer
     ↳ firstName string max 255 Yes First name of the buyer
     ↳ lastName string max 255 Yes Last name of the buyer
     ↳ document string max 255 Yes Document number of the buyer
     ↳ documentType string max 255 Yes Type of document of the buyer. It depends on the coutry. See Document Types by Country
     ↳ email string max 255 Yes Email of the buyer
     ↳ phone string max 255 Yes Phone number of the buyer
     ↳ address object Yes buyer address
          ↳ country string Yes Buyer address country
          ↳ street string Yes Buyer address street
          ↳ number string Yes Buyer address number
          ↳ complement string Yes Buyer address complement
          ↳ neighborhood string Yes Buyer address neighborhood
         ↳ postalCode string Yes Buyer address postal code
         ↳ city string Yes Buyer address city
          ↳ state string Yes Buyer address state
shipping object Yes Shipping data
     ↳value decimal Yes Shipping value with two decimal places
     ↳estimatedDate date 2028-06-15T21:15:07 Yes Estimated shipping date ISO 8601
     ↳address object Yes Shipping address
             ↳country string Yes Shipping address country
             ↳street string Yes Shipping address street
             ↳number string Yes Shipping address number
             ↳complement string Yes Shipping address complement
             ↳neighborhood string Yes Shipping address neighborhood
             ↳postalCode string Yes Shipping address postal code
            ↳city string Yes Shipping address city
             ↳state string Yes Shipping address state
items array of object Yes List of items data, in the cart
id string Yes VTEX product ID. The ID of the item
     ↳name string Yes Item name
     ↳price decimal Yes Item price
     ↳quantity integer Yes Quantity of this item in the cart
     ↳deliveryType string max 255 Yes Type of delivery configured by the store. ex. Normal
     ↳deliverySlaInMinutes integer Yes Each item can have a separate shipping sla in minutes
     ↳categoryId integer Yes Category ID for the Item. Configured by each store
     ↳categoryName string max 255 Yes Category name for the Item. Configured by each store
     ↳discount decimal Yes Discount applied on item(s) two decimal places
     ↳sellerId string Yes In case of a marketplace transaction, this is the Id of the seller for this specific item. Otherwise, this is filled with a '1'
taxValue decimal Yes Total tax value
listRegistry object List registry indicates the existence of a list, like wishList, giftList or any other defined by the store
     ↳name string max 255 List name defined by the store
     ↳deliveryToOwner boolean Flag to mark if the order will be delivered to list creator or not.
payments array of object Yes Describes the payments used for the current order
id string max 255 Yes Payment ID unique identifier in VTEX
method string max 255 Yes Payment method used for the buyer. See Payment Methods
name string max 255 Yes Payment name used for the buyer. This name could be the brand card or the VTEX payment method ex. Visa
value decimal Yes Payment value. Two decimal places
currencyIso4217 string Yes The currency used in each payment in the Transaction. It must be in the ISO 4217 format.
instalments integer Yes Number of installments
Details array of object Yes Payment details
bin string max 255 Yes Abbreviation for 'Bank Indetification Number'. It's a code that identifies the institution responsable for issuing the credit card
lastDigits string Yes Credit card identifier number last digits
holder string Yes Credit card owner
hook string Yes URL to be called when the payment has it's status changed
transactionStartDate string Yes The date and time when the transaction started. It must be in the ISO 8601 format

Response Body


Name TypeMandatory Description
id stringYes VTEX transaction ID. The ID of this transaction must be in the response.
tid stringYes Provider transaction ID. The ID of this transaction must be in the response. The antifraud provider MUST generates an unique transaction Id.
status stringYes Pre-analysis status from provider. Must be one of the values approved or denied
score decimalYes The value of the risk score. 100.00 as max value means total fraud
analysisType stringYes Pre-analysis type. Must be authomatic
responses dictionary or string, stringYes Key Value dictionary to add custom responses from analysis
code stringYes Error code returned from provider. Will be logged in transaction interactions log
message stringYes Error message returned from provider. Will be logged in transaction interactions log

REQUEST EXAMPLES AND THEIR RESPONSES

curl --location --request POST '{{antifraud-provider-service-url}}/pre-analysis' \
--header 'Content-Type: application/json' \
--header 'X-PROVIDER-API-AppKey: ProviderAppKey' \
--header 'X-PROVIDER-API-AppToken: ProviderAppToken' \
--data-raw '{
  "id": "D3AA1FC8372E430E8236649DB5EBD08E",
  "reference": "v32478982vtx-01",
  "value": 10,
  "ip": "10.0.0.1",
  "deviceFingerprint": "Generated_using_GTM_Store_Is_Responsible_To_Configure",
  "miniCart": {
    "buyer": {
      "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
      "firstName": "John",
      "lastName": "Doe",
      "document": "012.345.678-90",
      "documentType": "CPF",
      "email": "[email protected]",
      "phone": "+5521987654321",
      "address": {
        "country": "BRA",
        "street": "Rua Praia de Botafogo",
        "number": "518",
        "complement": "2o. andar",
        "neighborhood": "Botafogo",
        "postalCode": "22250-040",
        "city": "Rio de Janeiro",
        "state": "RJ"
      }
    },
    "shipping": {
      "value": 8.41,
      "estimatedDate": "2017-08-02T14:46:47",
      "address": {
        "country": "BRA",
        "street": "Rua Praia de Botafogo",
        "number": "518",
        "complement": "2o. andar",
        "neighborhood": "Botafogo",
        "postalCode": "22250-040",
        "city": "Rio de Janeiro",
        "state": "RJ"
      }
    },
    "items": [
      {
        "id": "132981",
        "name": "Some useful product",
        "price": 20.51,
        "quantity": 2,
        "deliveryType": "Normal",
        "deliverySlaInMinutes": 4320,
        "categoryId": "111",
        "categoryName": "Electronica",
        "discount": 1.99,
        "sellerId": "vtexargentina"
      },
      {
        "id": "123242",
        "name": "Some useless product",
        "price": 21.98,
        "quantity": 1,
        "deliveryType": "Normal",
        "deliverySlaInMinutes": 4320,
        "categoryId": "123",
        "categoryName": "Lar",
        "discount": 1.01,
        "sellerId": "vtexargentina"
      }
    ],
    "taxValue": 5.58,
    "listRegistry": {
      "name": "Minha lista Presente",
      "deliveryToOwner": false
    }
  },
  "payments": [
    {
      "id": "2D00FEBB5D7A43D598A99CFC43ADF158",
      "method": "CreditCard",
      "name": "Visa",
      "value": 63.98,
      "installments": 3,
      "details": {
        "bin": "507860",
        "lastDigits": "2798",
        "holder": "John Doe",
        "address": {
          "country": "BRA",
          "street": "Rua Praia de Botafogo",
          "number": "518",
          "complement": "2o. andar",
          "neighborhood": "Botafogo",
          "postalCode": "22250-040",
          "city": "Rio de Janeiro",
          "state": "RJ"
        }
      }
     "currencyIso4217": "BRL"
    },
    {
      "id": "04D430E517B2494FBC3DF7721CCDACC7",
      "method": "GiftCard",
      "value": 10.01,
      "installments": 1
    }
  ],
  "hook": "https://hook.vtex,com/notifyIfChangeStatus",
  "transactionStartDate": "2020-10-30T18:08:23Z"
}'
{
  "id": "D3AA1FC8",
  "tid": "4692c1f5",
  "code": "customCode",
  "message": "customMessage",
  "status": "approved",
  "score": 5.01,
  "analysisType": "authomatic",
  "responses": {
    "foo": "anyFoo",
    "custom": "customAnyValue"
  }
}
{
  "id": "D3AA1",
  "tid": "4692c1f0",
  "code": "customCode",
  "message": "customMessage",
  "status": "denied",
  "score": 85.01,
  "analysisType": "authomatic",
  "responses": {
    "foo": "anyFoo",
    "custom": "customAnyValue"
  }
}
Language
Authentication
URL
Click Try It! to start a request and see the response here!