--- title: "Risk Assess" method: POST path: "/risk/assess" tags: ["Risk"] --- # Risk Assess `POST /risk/assess` Used to check the level of risk before processing a transaction. Risk assessment returns four possible values: approve, deny, escalate and review. If the risk transaction is approved or review, you will be able to make a payment call with the risk assessment, risk id and transaction id you get in response. **Integration Methods:** - Host Direct See the [Integration Methods](/guides/quickstart#integration-methods) and [URLs Section](/guides/quickstart#urls) sections of the Development Quick Start guide for details regarding each processing option. See the [JSON Body Schemas](/guides/quickstart#json-body-schemas) for more details on the various JSON body formats. ## Headers - `InterfaceVersion` string, required - `InterfaceName` string, required - `CompanyName` string, required - `AccessToken` string, uuid, required ## Request body - union - RiskAssessUnencryptedcard - `dateTime` string, ISO 8601, required — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00 - `transaction` object, required - `toShip` 'Y' | 'N' — Merchants acknowledgement to ship/process the order. - `orderId` string — Merchant’s Order Number - `invoice` string, required — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `vendorReference` string — Optional field for information that can be searched in the merchant portal. - `purchaseCard` object - `customerReference` string — A unique value used to identify the consumer or transaction. If a merchant has a significant amount of revenue from purchasing card customers, the interface would use this field to collect the consumer’s purchase order or employee identification number. In lodging transactions, this may be unique transaction details, such as a reservation code or third-party booking source. This field is part of Level 2 card data. - `card` object, required - `type` 'AP' | 'CC' | 'PP' | 'GC', required — Payment Type submitted by merchant: Value| Description -----|------------ AP | Apple Pay CC | Credit Card PP | PayPal GC | Gift Card - `number` string, required — The payment card number entered in an initial authorization/sale request. This field will always be masked when returned in a response. - `expirationDate` integer — **Conditional: Send only when card data is manually entered or when using a token. This field should not be specified when using an encrypted device.** Card expiration date in MMYY format. This value should only be populated in the initial sale/authorization request. - `entryMode` '1' | '2' | 'C' | 'E' | 'M' | 'Q' | 'R' — **Conditional: The Card Entry Mode should be sent in an initial request; in subsequent requests, it should be left blank or not sent. When using a Universal Transaction Gateway® (UTG®)-controlled PIN pad, this field should be left blank or not sent in a request; the UTG will capture the card entry mode and return it in the response. When P2PE data is being sent from a non-UTG controlled device, this field is not needed** The method used to capture a payment card in an authorization/sale request. Value|Description -----|----------- 1 | Track 1 Only or Dual Track (Track 1 & 2) 2 | Track 2 Only C | EMV Contactless via card or mobile wallet E | EMV Chip M | Manual Entry Q | QR Code R | Contactless MSD - `present` 'Y' | 'N' — **Conditional: Send in the initial authorization/sale request** Indicates whether a card was present (‘Y’) or not (‘N’) at the time a transaction took place. This should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `amount` AmountRisk, required — Object containing information regarding the amount being requested. The `total` field within the object is required and specifies the amount being requested. All other fields are for informational purposes and must also be included in the `total` field. For example, a purchase of $100 with $8 tax would be “108.00” in the `total` field and "8.00" in the `tax` field. Note: For merchants that are configured to allow multiple currencies, the amount fields can specify up to three decimal places. However, the number of decimal places can not exceed the number allowed for the specified currency. See the [Currency Codes](/guides/appendices/currency-codes) section for details. - `total` number, required — The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero. - `tax` number — The amount of sales tax charged for a transaction. The tax amount is used by businesses to track tax expenses for accounting purposes. Identifying the tax amount also helps consumers understand the total amount that they were billed. This field is part of Level 2 card data. - `currencyCode` string, ISO 4217 3 Character Alphabetic Code, required — Transaction currency code. See the [Currency Codes](/guides/appendices/currency-codes) section for details. **Note: This is currently supported when processing for a merchant outside of the US and Canada. If processing for a US or Canadian merchant then this field will be ignored and the transaction will process in the merchant's configured currency.** - `risk` object, required - `sessionId` string, required — Unique Session ID. Must be unique over a 30-day span. - `sourceIp` string, required — Public source IP Address where the request originates, not the IP Address of the web server. - `customer` object - `emailAddress` string — This is the email address submitted by the customer. - `fullName` string — Name submitted with the order - `addressLine1` string — Billing street address - Line 1 - `addressLine2` string — Billing street address - Line 2 - `city` string — Billing address - City - `region` string — Billing address - State/Province - `postalCode` string — Billing address - Postal Code - `country` string — Billing address - Country - `phoneNumber` string — Bill-to Phone Number - `shipping` object - `addressLine1` string — Shipping street address - Line 1 - `addressLine2` string — Shipping street address - Line 2 - `city` string — Shipping address - City - `country` string — Shipping address - 2 character ISO Country Code. - `emailAddress` string — Shipping address - Email address of recipient - `fullName` string — Shipping address - Name of recipient - `postalCode` string — Shipping address - Postal Code - `phoneNumber` string — Ship-to Phone Number - `region` string — Shipping address - A level 2 country subdivision code according to ISO-3166-2. - `type` 'SD' | 'ND' | '2D' | 'ST' — Shipping type. Value| Description -----|------------ SD | Same Day ND | Next Day 2D | Second Day ST | Standard - `shoppingCart` object[] — Array of objects detailing the individual items being purchased - `type` string — Shopping cart data array attribute high level or generalized description of the item added to the shopping cart; this value should be free from any markup or Unicode values. This value should be passed as plain text. - `description` string — Shopping cart data array attribute for a specific description of the item being purchased. - `sku` string — Shopping cart data array attribute typically the SKU for an item; this value should be free from any markup or Unicode values. This value should be passed as plain text. - `quantity` integer — Shopping cart data array attribute signifying the quantity of the item being purchased. - `price` number — Shopping cart data array attribute for the price of the single item. Must be a natural number including 0. - RiskAssessTokenGtv - `dateTime` string, ISO 8601, required — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00 - `transaction` object, required - `toShip` 'Y' | 'N' — Merchants acknowledgement to ship/process the order. - `orderId` string — Merchant’s Order Number - `invoice` string, required — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `vendorReference` string — Optional field for information that can be searched in the merchant portal. - `purchaseCard` object - `customerReference` string — A unique value used to identify the consumer or transaction. If a merchant has a significant amount of revenue from purchasing card customers, the interface would use this field to collect the consumer’s purchase order or employee identification number. In lodging transactions, this may be unique transaction details, such as a reservation code or third-party booking source. This field is part of Level 2 card data. - `card` object, required - `type` 'TK', required — Payment Type submitted by merchant: Value| Description -----|------------ TK | Token - `token` CardTokenRequired, required - `value` string, required — This field is used to specify a card token. Whenever CHD is sent in a request, a card token will be returned in this field. Your interface should be designed to store this card token for future use. The latest card token received should be used in any subsequent request that references the same card data. - `expirationDate` integer — **Conditional: Send only when card data is manually entered or when using a token. This field should not be specified when using an encrypted device.** Card expiration date in MMYY format. This value should only be populated in the initial sale/authorization request. - `entryMode` '1' | '2' | 'C' | 'E' | 'M' | 'Q' | 'R' — **Conditional: The Card Entry Mode should be sent in an initial request; in subsequent requests, it should be left blank or not sent. When using a Universal Transaction Gateway® (UTG®)-controlled PIN pad, this field should be left blank or not sent in a request; the UTG will capture the card entry mode and return it in the response. When P2PE data is being sent from a non-UTG controlled device, this field is not needed** The method used to capture a payment card in an authorization/sale request. Value|Description -----|----------- 1 | Track 1 Only or Dual Track (Track 1 & 2) 2 | Track 2 Only C | EMV Contactless via card or mobile wallet E | EMV Chip M | Manual Entry Q | QR Code R | Contactless MSD - `present` 'Y' | 'N' — **Conditional: Send in the initial authorization/sale request** Indicates whether a card was present (‘Y’) or not (‘N’) at the time a transaction took place. This should be set appropriately in the initial authorization/sale request. In subsequent requests, this field should be left blank or should not be sent. **Note:** Subsequent request here does not apply to the secondary request for card on file type transactions or reuse of the same card. An example of a subsequent request would be a capture after an authorization. You would not include `card.present` in the capture, which is the subsequent request. Another example is when performing an incremental authorization where you perform an authorization, followed by an incremental authorization then a capture. The second authorization (incremental) and the capture are the subsequent requests where you would not include `card.present`. - `amount` AmountRisk, required — Object containing information regarding the amount being requested. The `total` field within the object is required and specifies the amount being requested. All other fields are for informational purposes and must also be included in the `total` field. For example, a purchase of $100 with $8 tax would be “108.00” in the `total` field and "8.00" in the `tax` field. Note: For merchants that are configured to allow multiple currencies, the amount fields can specify up to three decimal places. However, the number of decimal places can not exceed the number allowed for the specified currency. See the [Currency Codes](/guides/appendices/currency-codes) section for details. - `total` number, required — The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero. - `tax` number — The amount of sales tax charged for a transaction. The tax amount is used by businesses to track tax expenses for accounting purposes. Identifying the tax amount also helps consumers understand the total amount that they were billed. This field is part of Level 2 card data. - `currencyCode` string, ISO 4217 3 Character Alphabetic Code, required — Transaction currency code. See the [Currency Codes](/guides/appendices/currency-codes) section for details. **Note: This is currently supported when processing for a merchant outside of the US and Canada. If processing for a US or Canadian merchant then this field will be ignored and the transaction will process in the merchant's configured currency.** - `risk` object, required - `sessionId` string, required — Unique Session ID. Must be unique over a 30-day span. - `sourceIp` string, required — Public source IP Address where the request originates, not the IP Address of the web server. - `customer` object - `emailAddress` string — This is the email address submitted by the customer. - `fullName` string — Name submitted with the order - `addressLine1` string — Billing street address - Line 1 - `addressLine2` string — Billing street address - Line 2 - `city` string — Billing address - City - `region` string — Billing address - State/Province - `postalCode` string — Billing address - Postal Code - `country` string — Billing address - Country - `phoneNumber` string — Bill-to Phone Number - `shipping` object - `addressLine1` string — Shipping street address - Line 1 - `addressLine2` string — Shipping street address - Line 2 - `city` string — Shipping address - City - `country` string — Shipping address - 2 character ISO Country Code. - `emailAddress` string — Shipping address - Email address of recipient - `fullName` string — Shipping address - Name of recipient - `postalCode` string — Shipping address - Postal Code - `phoneNumber` string — Ship-to Phone Number - `region` string — Shipping address - A level 2 country subdivision code according to ISO-3166-2. - `type` 'SD' | 'ND' | '2D' | 'ST' — Shipping type. Value| Description -----|------------ SD | Same Day ND | Next Day 2D | Second Day ST | Standard - `shoppingCart` object[] — Array of objects detailing the individual items being purchased - `type` string — Shopping cart data array attribute high level or generalized description of the item added to the shopping cart; this value should be free from any markup or Unicode values. This value should be passed as plain text. - `description` string — Shopping cart data array attribute for a specific description of the item being purchased. - `sku` string — Shopping cart data array attribute typically the SKU for an item; this value should be free from any markup or Unicode values. This value should be passed as plain text. - `quantity` integer — Shopping cart data array attribute signifying the quantity of the item being purchased. - `price` number — Shopping cart data array attribute for the price of the single item. Must be a natural number including 0. ## Response `200` Risk assessment was processed - object - `result` object[] - `dateTime` string, ISO 8601, required — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00 - `amount` object, required - `total` number, required — The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero. - `card` object - `token` CardTokenResponse - `value` string — This field is used to specify a card token. Whenever CHD is sent in a request, a card token will be returned in this field. Your interface should be designed to store this card token for future use. The latest card token received should be used in any subsequent request that references the same card data. - `merchant` MerchantResponse - `mid` number — The merchant ID associated with the merchant account. - `name` string — The merchant’s business name as configured with Shift4. - `risk` object, required - `tranId` string, required — This is the unique transaction ID for this response from the 3rd party risk provider. Store this value and use it to find additional details about this transaction within the 3rd party risk provider's UI. - `assessment` 'A' | 'D' | 'R' | 'E', required — This is the answer to the risk assessment. If the response is Escalate then transaction needs 3DS authentication. Value| Description -----|------------ A | Approve. Continue with the payment transaction. D | Deny. Try another payment method R | Review. Continue with the payment transaction. E | Escalate. The transaction needs 3DS authentication. - `transaction` object, required - `s4RiskId` string, required — Unique transaction identification number generated by Shift4 to identify a specific risk transaction and a field that can be searched in LTM. - `invoice` string, required — 10-digit invoice number assigned by the interface to identify a transaction. An invoice number serves as a unique key that identifies a transaction within a batch in Shift4's Gateway. **Note: For US and Canadian processing: Although the invoice number is sent as a JSON string it is a numeric value. No alpha characters are allowed.** **For processing outside of the US and Canada alpha characters are allowed.** - `orderId` string — Merchant’s Order Number ## Other responses - `400` — Error - `504` — Timeout --- [API](https://skmtc.dev/shift4/apis/shift4-payment-api.md) · [All operations](https://skmtc.dev/shift4/apis/shift4-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/shift4/shift4-payment-api/revisions/b923fc55b203/schema)