Send Antifraud Data

Receives a new transaction antifraud data. This step is performed only if all payments are authorized.

VTEX expects that your antifraud provider process this request and retrieves the process result, VTEX order flow will follow your response status in order to cancel or approve the transaction


REQUEST HEADERS


Header Value
X-PROVIDER-API-AppKey {{X-PROVIDER-API-AppKey}}
X-PROVIDER-API-AppToken {{X-PROVIDER-API-AppToken}}
Content-Type 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


id string VTEX transaction ID. The ID of this transaction must be in the response.
tid string Provider transaction ID. The ID of this transaction must be in the response. The antifraud provider MUST generates an unique transaction Id.
status string Transaction status from provider. Must be one of the values: received
score decimal The value of the risk score. 100.00 as max value means total fraud
analysisType string analysis type. Valid values are authomatic or manual
responses dictionary or string, string Key Value dictionary to add custom responses from analysis
code string Error code returned from provider. Will be logged in transaction interactions log
message string 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}}/transactions' \
--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": "D3AA1FC8372E430E8236649DB5EBD08E",
  "tid": "4692c1f54d514fe69da0b472a3b2a770",
  "code": "customCode",
  "message": "customMessage",
  "status": "received",
  "score": 5.01,
  "analysisType": "authomatic",
  "responses": {
    "foo": "anyFoo",
    "custom": "customAnyValue"
  }
}
Language
Authentication
URL
Click Try It! to start a request and see the response here!