Skip to main content

Request Fields

Request Fields​

These fields should be sent in addition to the Basic Request Fields.

Field NameMandatory?Description
riskCheckRequiredNo[1]

Is risk checking required for this transaction?

Possible values are:

N – risk checking is not required.

Y – risk checking is required.

riskCheckPrefNo[1]

List of riskCheck response values and the action to be taken for those responses.

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.

riskCheckOptionsNoRecord 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 NameSub-Field NameDescription
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]]*$

channeln/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]]*$

creationDateTimen/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”

accountThe 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"

typeMerchant-provided categorisation of the account.
creationDateTimeThe date and time that the user's account was created. Format: Must be in RFC3339 format.
usernameThe username of the user's account.
accountIsActiveA boolean indicating whether the user's account is still active.
itemsThe 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".
nameThe 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.

categoryA high level or generalised description of the item added to the shopping cart. For example, "TV".
subCategoryA lower-level or more specific description of the item added to the shopping cart. For example, "OLED TV".
isDigitalA 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".
upcA string containing the item's UPC code, when available. For example: "03600029145".
brandThe 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"

physicalAttributesAn object containing data on the physical attributes of a physical good.
physicalAttributes.colorThe color of the item, when there are different color options. For example: "Midnight Purple"
physicalAttributes.sizeThe 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"
descriptorsAn array of keywords associated with the item. For example: ["halloween", "mask"]
isServiceA boolean that indicates if the item being ordered is a service (true), or if it is a digital or physical product (false).
fulfillmentThe fulfillment details. This field contains sub-fields as detailed below:
merchantFulfillmentIdThe 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.
Possible values are:

  • SHIPPED
  • DIGITAL
  • STORE_PICK_UP
  • LOCAL_DELIVERY
  • STORE_DRIVE_UP
  • IN_PERSON
itemsAn 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:

  • PENDING – Awaiting fulfillment info
  • UNFULFILLED – In progress, but not shipped
  • ON_HOLD – Waiting on upsell opportunities
  • FULFILLED – Shipped (formerlySUCCESSFUL)
  • SCHEDULED – Waiting for release (such as prepaid subscriptions)
  • PARTIALLY_FULFILLED – Portion is shipped
  • DELAYED – Delayed
  • CANCELED – Canceled
accessUrlA string containing the URL the customer needs to visit to retrieve the digital good. For example: "https://example.com/digitalgood/1213901281290"
shippingAn object containing the shipping details properties.
shipping.amountThe 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.providerThe 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.trackingNumberA 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.

recipientPersonThe object containing the properties of the recipient of the order.
recipientPerson.nameAn 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.middleThe middle name of the person the order is shipped to.
recipientPerson.name.familyThe last name of the person the order is shipped to.
recipientPerson.name.prefixThe prefix of the name of the person the order is shipped to.
recipientPerson.name.suffixThe suffix of the name of the person the order is shipped to.
recipientPerson.name.preferredThe 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.addressAn 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.line2The 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".
storeAn 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.nameA string containing the human-readable name of the store. Example: “10th & Main Acme Inc.”
store.addressAn object containing the properties of a physical or mailing address.
store.address.line1The first line of the address. For example, "12345 MyStreet Ave".
store.address.line2The second line of the address. For example, "Suite 256”.
store.address.cityThe city of the address. For example, "Poplar Bluff".
store.address.regionThe state or province of the address. For example, “CO”.
store.address.countryCodeThe country code of the address in the ISO-3166 format. For example, "US".
store.address.postalCodeThe postal code of the address. For example, "63901-0000".
transactionThe transaction details. This field contains sub-fields as detailed below:
taxThe tax details of the payment.
tax.isTaxableA boolean indicating whether the order is taxable (true) or not (false).
tax.taxableCountryCodeThe 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.outOfStateTaxAmountThe 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”.
billedPersonAn object containing the properties of the person who placed the order.
billedPerson.nameAn 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.middleThe middle name of the person/company billed for the order.
billedPerson.name.familyThe last name (surname) of the person/company billed for the order. For example, “Doe”.
billedPerson.name.prefixThe prefix of the name of the person/company billed for the order.
billedPerson.name.suffixThe suffix of the name of the person/company billed for the order.
billedPerson.name.preferredThe 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.addressAn 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.line2The 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.
itemsIndicates 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:
idThe unique identifier of the item that was specified in the items property of this order that was paid for in this transaction.
quantityThe quantity of this item that were paid for in this transaction.
promotionsAn array containing all of the promotions applied to this order. This field contains sub-fields as detailed below:
idThe merchant-provided identifier for the promotion. Uniqueness for this property is not enforced. Example: "BOGO10"
descriptionThe merchant-provided promotion description. For example: "Buy one, get one 10% off"
statusThe merchant-provided promotion status. For example: "accepted".
statusReasonThe merchant-provided promotion status reason. For example: "Promotion cannot be combined."
discountThe object containing the details of the discount.
discount.percentageThe 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.amountThe 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.currencyThe 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.currencyThe 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).
creditAn object containing the details of the amount of credit that was applied to this order.
credit.creditTypeA merchant-defined identifier for the type of credit that was applied. For example: "GIFT_CARD"
credit.amountThe 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”.
loyaltyThe details of a credit that was applied from a loyalty account. This field contains sub-fields as detailed below:
idThe unique identifier for the loyalty transaction. Uniqueness for this property is not enforced. Example: "d121ea2210434ffc8a90daff9cc97e76"
descriptionA description of the loyalty program being applied. For example: "Pizza Points"
loyalty.creditThe details of the loyalty credit that was applied to the order. This field contains sub-fields as detailed below:
creditTypeA merchant-defined identifier for the type of credit that was applied. For example: "PIZZA_POINTS"
amountThe 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”.
currencyThe 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).
customFieldsAn 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.

Footnotes

  1. Overrides any Merchant Account setting configured via the Merchant Management System (MMS).