# 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. - Host Direct See the Integration Methods and URLs Section sections of the Development Quick Start guide for details regarding each processing option. See the JSON Body Schemas for more details on the various JSON body formats. Endpoint: POST /risk/assess Version: 1.7.43 Security: AccessToken ## Header parameters: - `InterfaceVersion` (string, required) Refers to the version of the program or application that is sending requests to Shift4. The following special characters are not allowed: $ % : ^ - ~ , ? “ ” ‘ ’ { } [ ] \ + = Example: "2.1" - `InterfaceName` (string, required) Refers to the name of the program or application that is sending requests to Shift4. This should be the name of the program that you purchased or created. The following special characters are not allowed: $ % : ^ - ~ ` , ? “ ” ‘ ’ { } [ ] \ + = Example: "ForwardPOS" - `CompanyName` (string, required) Refers to the vendor or partner that designed and certified the interface. The information you use in this field should match what Shift4 has on file or what was agreed upon in your Integration Plan. The following special characters are not allowed: $ % : ^ - ~ ` , ? “ ” ‘ ’ { } [ ] \ + = Example: "PAWS" - `AccessToken` (string, required) A security credential used to authenticate API requests and all i4Go® authorizeClient/preauthorizeClient requests. An Access Token is the alias for the merchant account and interface being used. The Access Token is required in all requests except an Access Token Exchange request, which generates an Access Token using an and . Example: "EA79FB05-3AA7-4500-AF9A-73F986FF2C1D" ## Response 200 fields (application/json): - `result` (array) - `result.dateTime` (string, 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 - `result.amount` (object, required) - `result.amount.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. - `result.risk` (object, required) - `result.risk.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. - `result.risk.assessment` (string, 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. Enum: "A", "D", "R", "E" - `result.transaction` (object, required) - `result.transaction.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. - `result.transaction.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. - `result.transaction.orderId` (string) Merchant’s Order Number - `result.card` (object) - `result.card.token` (object) - `result.card.token.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. - `result.merchant` (object) - `result.merchant.mid` (number) The merchant ID associated with the merchant account. - `result.merchant.name` (string) The merchant’s business name as configured with Shift4. ## Response 400 fields (application/json): - `result` (array) Example: [{"error":{"longText":"format error","primaryCode":9151,"secondaryCode":0,"shortText":"format error"},"transaction":{"s4RiskId":"EC52377F-5A8E-4534-BE7A-CF779A35BE45","invoice":"0207123502","orderId":"orderId","hostResponse":{"reasonCode":"232","reasonDescription":"The credit card information is missing"}}}] - `result.error` (object) - `result.error.code` (integer) Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details. - `result.error.severity` (string) Severity level of the error. | Severity | Description | | -------- | ---------------------------------------------------------------- | | Info | Action not required - Data input/formatting is incorrect | | Error | Action may be required - Communication, timeout or network issue | | Alert | Action required - System issue | Enum: "Info", "Error", "Alert" - `result.error.shortText` (string) Abbreviated error message that is always returned if an error condition exists - `result.error.longText` (string) Extended error message that is returned if an error condition exists. - `result.error.primaryCode` (integer) Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details. - `result.error.secondaryCode` (integer) This code supplements the code specified in the field to provide additional information about the error that occurred. - `result.transaction` (object) - `result.transaction.s4RiskId` (string) Unique transaction identification number generated by Shift4 to identify a specific risk transaction and a field that can be searched in LTM. - `result.transaction.invoice` (string) 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. - `result.transaction.hostResponse` (object) - `result.transaction.hostResponse.reasonCode` (string) Returns a response code from the host. Value |Reason Description ------|------------------ 201 | Missing version of provider, this is built into SDK but must be supplied by merchant if not using the SDK 202 | The mode type for post is missing. 203 | The six digit Merchant ID was not sent 204 | The unique session ID was not sent 205 | Transaction ID number 211 | The currency was missing in the RISK submission 212 | The total amount was missing 221 | The email address was missing 222 | For MODE = P RISK inquiries the caller ID is missing 223 | The website identifier that was created in the Agent Web Console (DEFAULT is the default website ID) is missing 231 | The payment type is missing. 232 | The credit card information is missing 233 | Missing Magnetic Ink Character Recognition string 234 | The PayPal Payer ID is missing 235 | The payment token is missing. 241 | The IP address is missing 251 | The merchant acknowledgement is missing 261 | The RISK query submitted to provider contained no data 271 | The shopping cart data array attribute is missing. 272 | The shopping cart data array attribute is missing. 273 | The shopping cart data array attribute is missing. 274 | The shopping cart data array attribute is missing. 275 | The shopping cart data array attribute is missing. 301 | The version of provider supplied by merchant does not fit the four integer parameter 302 | The mode type is invalid. 303 | The six digit Merchant ID is malformed or wrong 304 | The unique session ID is invalid. Refer to the Data Collector 305 | Transaction ID number is malformed 311 | The currency was wrong in the RISK submission 312 | The total amount is wrong. TOTL is the whole number amount charged to customer 321 | The email address does not meet required format or is greater than 64 characters in length 322 | For MODE = P RISK inquiries the caller ID is malformed 323 | The website identifier that was created in the Agent Web Console (DEFAULT is the default w website ID) does not match what was created in the AWC. 324 | The specified format is wrong. Format options are key value pairs, XML, JSON, YAML 331 | The payment type is wrong. 332 | The credit card information is malformed or wrong, test cards do not work in the production environment 333 | Malformed or improper Magnetic Ink Character Recognition string. 334 | The PayPal Payer ID is malformed or corrupt. 335 | Malformed or improper Google Checkout Account ID string. 336 | Malformed or improper Bill Me Later account number. 337 | The encryption method specified is wrong. 338 | The GreenDot payment token is not a valid payment token 339 | When payment type equals CARD, PTYP = CARD and payment encryption type equals KHASH, `PENC = KHASH the value must be 20 characters in length. 340 | Invalid or excessive characters in the PTOK field 341 | The IP address does not match specifications 342 | The Gift Card payment token is invalid due to invalid characters, null, or exceeding character length 351 | The merchant acknowledgement must be Y or N 362 | There is a discrepancy in the shopping cart key count and the number of items actually being sent in the cart 371 | The shopping cart data array attribute is missing. 372 | The shopping cart data array attribute is corrupt or missing. 373 | The shopping cart data array attribute is corrupt or missing. 374 | The shopping cart data array attribute is corrupt or missing. 375 | The shopping cart data array attribute is corrupt or missing. 399 | A UDF has been mistyped or does not exist in the Agent Web Console 401 | RISK keys submitted by merchant were not part of SDK 404 | When PTYP equals NONE and a PTOK is submitted 413 | The RISK Post to provider exceeded the 4K limit. 501 | Error regarding certificate - Using test certificate in prod 502 | Invalid Merchant ID has been entered 601 | Unspecified system error - Contact Merchant Services 602 | Provider will not process particular transaction 701 | No header found with merchantId = [XXXXX], session_id = [htot2kk5khpamo45f777q455], trans=[122347] This error occurs when a RISK request goes to the database and there is no data available in the reply. The Update post had an invalid transaction ID#. Check all required fields for update post and confirm they are being passed correctly. - `result.transaction.hostResponse.reasonDescription` (string) Returns a description from the host. - `result.transaction.orderId` (string) Merchant’s Order Number ## Response 504 fields (application/json): - `result` (array) Example: [{"error":{"longText":"Timeout waiting for response across the internet","primaryCode":9951,"secondaryCode":0,"shortText":"RESPONSE TIMEOUT"},"transaction":{"s4RiskId":"EC52377F-5A8E-4534-BE7A-CF779A35BE45","invoice":"0207123502","orderId":"orderId"}}] - `result.error` (object) - `result.error.code` (integer) Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details. - `result.error.severity` (string) Severity level of the error. | Severity | Description | | -------- | ---------------------------------------------------------------- | | Info | Action not required - Data input/formatting is incorrect | | Error | Action may be required - Communication, timeout or network issue | | Alert | Action required - System issue | Enum: "Info", "Error", "Alert" - `result.error.shortText` (string) Abbreviated error message that is always returned if an error condition exists - `result.error.longText` (string) Extended error message that is returned if an error condition exists. - `result.error.primaryCode` (integer) Code indicating the type of error that occurred. Refer to the [Error Codes](/guides/appendices/error-codes) section of this document for more details. - `result.error.secondaryCode` (integer) This code supplements the code specified in the field to provide additional information about the error that occurred. - `result.transaction` (object) - `result.transaction.s4RiskId` (string) Unique transaction identification number generated by Shift4 to identify a specific risk transaction and a field that can be searched in LTM. - `result.transaction.invoice` (string) 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. - `result.transaction.orderId` (string) Merchant’s Order Number