Request Fields
Request Fields
These fields should be sent in addition to the Basic Request Fields.
| Field Name | Mandatory? | Description |
|---|---|---|
| riskCheckRequired | No[1] | Is risk checking required for this transaction? Possible values are: N – risk checking is not required. Y – risk checking is required. |
| riskCheckPref | No[1] | List of Value is a comma separated list containing one or more of the following risk check results and associated actions: Results: not known, not checked, approve, decline, review, escalate. Actions: continue, decline1, decline2, authonly, finished. |
| riskCheckOptions | No | Record containing options used to customise the risk checking. Refer to the Risk Check Options section for details. |
Risk Check Options
The following options may be sent in the riskCheckOptions field to customise the risk checking. Where possible, the options will be initialised from standard integration fields as shown in brackets below the option name. The options must be formatted using the record or serialised record formats.
| Option Name | Sub-Field Name | Description |
|---|---|---|
| merchantOrderId (merchantOrderRef) | n/a | The merchant-provided unique identifier for this order. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76" Format: Empty string or max 256 character string. Must match regex ^[[0-9A-Za-z]]*$ |
| channel | n/a | Unique identifier of the website or app from where the order originated. For example, "ACME_IOS_APP" Format: Empty string or max 256 character string. Cannot match regex [><&'\"] |
| deviceSessionId (Set by Hosted Form or sent in for Direct) | n/a | Unique identifier for the customer’s end-user’s session on the site/app. Must be the same session ID used in the device data collection from the client-side Kount SDK. Uniqueness for this property is not enforced, but customers should provide unique values. Example: "d121ea2210434ffc8a90daff9cc97e76" Format: Empty string or max 256 character string. Must match regex ^[[0-9A-Za-z]]*$ |
| creationDateTime | n/a | The date and time that the order was placed. Format: Must be in RFC3339 format. |
| userIp (deviceIpAddress) | n/a | The customer/merchant’s end-user’s IPv4 address (in dotted decimal notation) as identified by the customer/merchant. For example, “192.168.1.27” |
| account | The account details. This field contains sub-fields as detailed below: | |
| id (merchantCustomerRef) | The merchant-provided unique account ID of the user that placed the order. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76" | |
| type | Merchant-provided categorisation of the account. | |
| creationDateTime | The date and time that the user's account was created. Format: Must be in RFC3339 format. | |
| username | The username of the user's account. | |
| accountIsActive | A boolean indicating whether the user's account is still active. | |
| items | The item details. This field contains sub-fields as detailed below: | |
| id | The merchant-provided unique item ID of the item in the order. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76" | |
| price (XX.amount) | The price of the single item in the lowest currency factor. For example, the lowest currency in USD is pennies, so $1.00 would have the value of “100”. Must be a natural number including 0. For example, 100. | |
| description (XX.description) | The description of the item being purchased. For example, "Samsung 46' LCD HDTV". | |
| name | The name of the item being purchased, typically the SKU. For example, "LN46B610". | |
| quantity (XX.quantity) | The quantity of the item being purchased. For example, 1. Format: Minimum of 1. | |
| category | A high level or generalised description of the item added to the shopping cart. For example, "TV". | |
| subCategory | A lower-level or more specific description of the item added to the shopping cart. For example, "OLED TV". | |
| isDigital | A boolean indicating whether the item being ordered is a physical item or a service (false), or whether it is a digital good or service (true). | |
| sku (XX.productCode) | A string containing the item's SKU, when available. For example: "TSH-000-S". | |
| upc | A string containing the item's UPC code, when available. For example: "03600029145". | |
| brand | The item's brand name. | |
| url (XX.productURL) | The URL to the page that describes the item in the merchant's store. For example: "https://www.example.com/store/tsh-000-s" | |
| imageUrl (XX.imageURL) | The URL to the item's thumbnail image. For example: "https://www.example.com/store/tsh-000-s/thumbnail.png" | |
| physicalAttributes | An object containing data on the physical attributes of a physical good. | |
| physicalAttributes.color | The color of the item, when there are different color options. For example: "Midnight Purple" | |
| physicalAttributes.size | The size of the item, when there are different size options. For example: "XL" | |
| physicalAttributes.weight (XX.Weight) | The item's weight and units. For example: "5 lbs." | |
| physicalAttributes.height (XX.Size) | The item's height and units. For example: "12 in." | |
| physicalAttributes.width (XX.Size) | The item's width and units. For example: "6 in." | |
| physicalAttributes.depth (XX.Size) | The item's depth and units. For example: "36 cm" | |
| descriptors | An array of keywords associated with the item. For example: ["halloween", "mask"] | |
| isService | A boolean that indicates if the item being ordered is a service (true), or if it is a digital or physical product (false). | |
| fulfillment | The fulfillment details. This field contains sub-fields as detailed below: | |
| merchantFulfillmentId | The merchant-provided unique identifier for this fulfillment. Uniqueness for this property is not enforced. | |
| type | A string from an enumeration of types of fulfillment. For example: "DIGITAL" Format: Value must be in enum.
| |
| items | An array of string values made up of the merchant-provided item IDs that are being fulfilled in this fulfillment. | |
| status | A string of an enumeration of statuses of the current status of the fulfillment. Format: Value must be in en Possible values are:
| |
| accessUrl | A string containing the URL the customer needs to visit to retrieve the digital good. For example: "https://example.com/digitalgood/1213901281290" | |
| shipping | An object containing the shipping details properties. | |
| shipping.amount | The total amount of the shipping cost in its lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”. | |
| shipping.provider | The service used to deliver the order to the recipient. If the merchant fulfills the order itself, should have the value "FBM" (fulfilled by merchant). | |
| shipping.trackingNumber | A string containing the tracking number from the shipping provider for shipped goods. For example: "TBA056059680404". | |
| shipping.method | A string from an enumeration of types of shipping methods used to deliver the goods to the recipient. Types: “STANDARD”, “EXPRESS”, “SAME_DAY”, “NEXT_DAY”, “SECOND_DAY” Format: Value must be in enum. | |
| recipientPerson | The object containing the properties of the recipient of the order. | |
| recipientPerson.name | An object containing the properties of the name of the person. | |
| recipientPerson.name.first (deliveryName) | The first name of the person the order is shipped to. | |
| recipientPerson.name.middle | The middle name of the person the order is shipped to. | |
| recipientPerson.name.family | The last name of the person the order is shipped to. | |
| recipientPerson.name.prefix | The prefix of the name of the person the order is shipped to. | |
| recipientPerson.name.suffix | The suffix of the name of the person the order is shipped to. | |
| recipientPerson.name.preferred | The name the person the order is shipped to would like to be addressed by. For example: "Bill". | |
| recipientPerson.dateOfBirth | The date that the person was born. Format: "yyyy-mm-dd", the ISO 8601 calendar date extended format. | |
| recipientPerson.emailAddress (deliveryEmail) | The email address of the person the order is shipped to. For example, "john.doe@example.com". | |
| recipientPerson.phoneNumber (deliveryPhone) | The phone number of the person the order is being shipped to in the E.123 standard format. For example, "+12081234567". | |
| recipientPerson.address | An object containing the properties of a physical or mailing address. | |
| recipientPerson.address.line1 (deliveryStreet, deliveryAddress) | The first line of the shipping address. For example, "12345 MyStreet Ave". | |
| recipientPerson.address.line2 | The second line of the shipping address. For example, "Suite 256”. | |
| recipientPerson.address.city (deliveryTown) | The city of the shipping address. For example, "Poplar Bluff". | |
| recipientPerson.address.region (deliveryCounty) | The state or province of the shipping address. For example, “CO”. | |
| recipientPerson.address.countryCode (deliveryCountryCode) | The country code of the shipping address in the ISO-3166 format. For example, "US". | |
| recipientPerson.address.postalCode (deliveryPostcode) | The postal code of the shipping address. For example, "63901-0000". | |
| store | An object containing the properties of the store where the order is being fulfilled. | |
| store.id | A string containing the merchant-provided unique identifier for the store. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76" | |
| store.name | A string containing the human-readable name of the store. Example: “10th & Main Acme Inc.” | |
| store.address | An object containing the properties of a physical or mailing address. | |
| store.address.line1 | The first line of the address. For example, "12345 MyStreet Ave". | |
| store.address.line2 | The second line of the address. For example, "Suite 256”. | |
| store.address.city | The city of the address. For example, "Poplar Bluff". | |
| store.address.region | The state or province of the address. For example, “CO”. | |
| store.address.countryCode | The country code of the address in the ISO-3166 format. For example, "US". | |
| store.address.postalCode | The postal code of the address. For example, "63901-0000". | |
| transaction | The transaction details. This field contains sub-fields as detailed below: | |
| tax | The tax details of the payment. | |
| tax.isTaxable | A boolean indicating whether the order is taxable (true) or not (false). | |
| tax.taxableCountryCode | The country code of the taxable country in the ISO-3166 format. For example, "US". | |
| tax.taxAmount (taxAmount) | The amount that was charged in taxes for this order in the currency's lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”. | |
| tax.outOfStateTaxAmount | The amount that was charged in out-of-state taxes for this order in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”. | |
| billedPerson | An object containing the properties of the person who placed the order. | |
| billedPerson.name | An object containing the properties of the person's name. | |
| billedPerson.name.first (customerName) | The first name (forename) of the person/company billed for the order. For example, “William”. | |
| billedPerson.name.middle | The middle name of the person/company billed for the order. | |
| billedPerson.name.family | The last name (surname) of the person/company billed for the order. For example, “Doe”. | |
| billedPerson.name.prefix | The prefix of the name of the person/company billed for the order. | |
| billedPerson.name.suffix | The suffix of the name of the person/company billed for the order. | |
| billedPerson.name.preferred | The name the person/company billed for the order would like to be addressed by. For example: "Bill". | |
| billedPerson.emailAddress (customerEmail) | The email address of the person/company billed for the order. For example, “john.doe@example.com” | |
| billedPerson.phoneNumber (customerPhone) | The phone number of the person billed for the order in the E.123 standard format. For example, "+15551234567". | |
| billedPerson.address | An object containing the properties of a physical or mailing address. | |
| billedPerson.address.line1 (customerStreet, customerAddress) | The first line of the billing address. For example, “12345 Mystreet Ave”. | |
| billedPerson.address.line2 | The optional second line of the billing address. For example, “Suite 123”. | |
| billedPerson.address.city (customerTown) | The city of the billing address. For example, "Poplar Bluff" | |
| billedPerson.address.region (customerCounty) | The state or province of the billing address. For example, “CO”. | |
| billedPerson.address.postalCode (customerPostcode) | The postal code of the billing address. For example, "63901-0000". | |
| billedPerson.address.countryCode (customerCountryCode) | The country code of the billing address in the ISO-3166 format. For example, "US". | |
| billedPerson.dateOfBirth (customerDateOfBirth) | The date that the person was born.Format: "yyyy-mm-dd", the ISO 8601 calendar date extended format. | |
| items | Indicates which of the items described in the items array were paid for in this transaction, indicated by an item ID and a quantity. This field contains sub-fields as detailed below: | |
| id | The unique identifier of the item that was specified in the items property of this order that was paid for in this transaction. | |
| quantity | The quantity of this item that were paid for in this transaction. | |
| promotions | An array containing all of the promotions applied to this order. This field contains sub-fields as detailed below: | |
| id | The merchant-provided identifier for the promotion. Uniqueness for this property is not enforced. Example: "BOGO10" | |
| description | The merchant-provided promotion description. For example: "Buy one, get one 10% off" | |
| status | The merchant-provided promotion status. For example: "accepted". | |
| statusReason | The merchant-provided promotion status reason. For example: "Promotion cannot be combined." | |
| discount | The object containing the details of the discount. | |
| discount.percentage | The percentage of the total amount that was reduced due to the promotion being applied, represented as a floating point number. For example: 0.1 means 10% discounted. | |
| discount.amount | The amount that the total was reduced by due to the promotion being applied in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”. | |
| discount.currency | The three-letter ISO-4217 code of the currency used in the promotion’s discount. If a code is not provided, it defaults to "USD”. | |
| credit.currency | The three-letter ISO-4217 code of the currency used in the promotional credit. If a code is not provided, it defaults to "USD”. If the credit is in a non-monetary format, such as loyalty points, the value of this property should be "XXX”, (no currency). | |
| credit | An object containing the details of the amount of credit that was applied to this order. | |
| credit.creditType | A merchant-defined identifier for the type of credit that was applied. For example: "GIFT_CARD" | |
| credit.amount | The amount of the total order that was paid for through a credit in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”. | |
| loyalty | The details of a credit that was applied from a loyalty account. This field contains sub-fields as detailed below: | |
| id | The unique identifier for the loyalty transaction. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76" | |
| description | A description of the loyalty program being applied. For example: "Pizza Points" | |
| loyalty.credit | The details of the loyalty credit that was applied to the order. This field contains sub-fields as detailed below: | |
| creditType | A merchant-defined identifier for the type of credit that was applied. For example: "PIZZA_POINTS" | |
| amount | The amount of the total order that was paid for through a loyalty credit in the currency's lowest denomination. This amount should be included in the taxAmount property. For example, the lowest denomination in USD is the penny, so $1.00 has a “total” of “100”. The total must be a natural number, which includes “0”. | |
| currency | The three-letter ISO-4217 code of the currency used in the loyalty credit. If a code is not provided, it defaults to "USD”. If the credit is in a non-monetary format, such as loyalty points, the value of this property should be "XXX”, (no currency). | |
| customFields | An object that allows passing in Custom Fields. Each key is the custom field’s name as a string (max length: 32 characters). Each value is the custom field’s value as a date, boolean, string (max length: 256 characters), or number. Supported date format is RFC 3339 (ex: 2023-03-30T15:41:58Z). No object or array values are allowed. |
For further information on the options, refer to the Kount 360 Integration documentation.