Order fields
| FIELD | DATATYPE | REQUEST | RESPONSE | SIZE | DESCRIPTION |
|---|---|---|---|---|---|
| userInformation.browserInformation.acceptHeader | String | (O) | (O) | Unlimited (BD 400KB) | This is the HTTP accept header as retrieved from the cardholder’s browser in the HTTP request. In case it is longer than 2048 it has to be truncated. It is strongly recommended to provide this field to prevent rejections from the ACS server side. |
| userInformation.browserInformation.userAgentHeader | String | (O) | (O) | Unlimited (BD 400KB) | This is the User Agent as retrieved from the card holder’s browser in the HTTP request. In case it is longer than 256 Byte it has to be truncated. It is strongly recommended to provide this field to prevent rejections from the ACS server side. |
| userInformation.browserInformation.screenHeight | Integer | (O) | (O) | Unlimited (BD 400KB) | Screen height received by the client. Positive values allowed only. |
| userInformation.browserInformation.timeZone | Integer | (O) | (O) | Unlimited (BD 400KB) | Time zone received by the client. Allowed integer values between -720 and 840. |
| userInformation.browserInformation.enableJava | Boolean | (O) | (O) | Unlimited (BD 400KB) | Indicates if java is enabled. |
| userInformation.browserInformation.screenColorDepth | Enum | (O) | (O) | Unlimited (BD 400KB) | Supported screen color depth. Allowed values are: 1, 4, 8, 15, 16, 24, 32, 48. |
| userInformation.browserInformation.windowSize | String | (O) | (O) | Unlimited (BD 400KB) | Indicates the client’s window size. Example: “200px“. |
| userInformation.browserInformation.fingerprint | String | (O) or (M) for Order Insight C.E. 3.0) | (O) | 512 | Device/browser fingerprint ID. Optional field (Mandatory for Order Insight C.E 3.0), ensure backward compatibility if not sent |
| userInformation.billingAddress.name | String | (O) or (Recommended) for Order Insight C.E. 3.0) | (O) | Unlimited (BD 400KB) | The name of the billing person provided by the user for billing purposes. |
| userInformation.billingAddress.street | String | (O) or (Recommended) for Order Insight C.E. 3.0) | (O) | Unlimited (BD 400KB) | The street provided by the user for billing purposes. |
| userInformation.billingAddress.city | String | (O) or (Recommended) for Order Insight C.E. 3.0) | (O) | Unlimited (BD 400KB) | The city provided by the user for billing purposes. |
| userInformation.billingAddress.postcode | String | (O) or (Recommended) for Order Insight C.E. 3.0) | (O) | Unlimited (BD 400KB) | The postcode provided by the user for billing purposes. |
| userInformation.billingAddress.country | String | (O)or (Recommended) for Order Insight C.E. 3.0) | (O) | Unlimited (BD 400KB) | The country in ISO 3166-2 format provided by the user for billing purposes. |
| userInformation.billingAddress.state | String | (O) or (Recommended) for Order Insight C.E. 3.0) | (O) | Unlimited (BD 400KB) | The state provided by the user for billing purposes. The ISO 3166-2 of the country. Example: “US-AK”. |
| userInformation.country | String | (M) | (O) | 2 | This is the end-consumer’s country. |
| userInformation.email | String | (M) | (O) | Unlimited (BD 400KB) | This is the end-consumer’s email-address. |
| userInformation.ip | String | (M) | (O) | IPV4(XXX.XXX.XXX.XXX) | The global (internet) IP address of the consumer's computer. |
| userInformation.language | String | (M) | (O) | 2 | Code ISO 639-1 of the language. Can be any of CZ, DA, EN, DE, ES, FI, FR, IT, NL, PL, GR, RO, RU, SV and TR. |
| concept | String | (M) | (O) | Unlimited (BD 400KB) | Description on the settlement of the account holder’s account about a transaction (bank statement). The following characters are allowed: 0-9, a-z, A-Z. The concept can be defined as static or dynamic, depending on the acquiring bank providing the MID. Static concept: the parameters which define the concept of the transaction are given by the acquiring bank. These parameters are fixed and not customizable. Dynamic concept: the parameters which define the concept of the transaction are composed by the acquiring bank and the Merchant. The Merchant is allowed to add customizable characters/digits to the fixed parameters of the acquiring bank. |
| customerId | String | (O) | (O) | 250 | A customer ID is an optional parameter which is sent by the Merchant to identify the user within their business strategy. If the request contains the Customer ID, the response will show the same information with the transaction result. |
| description | String | (O) | (O) | Unlimited (BD 400KB) | Optional free text description for Merchant. It usually helps the Merchant as an internal reference to locate the transaction. |
| domain | String | (M) | (O) | Unlimited (BD 400KB) | The URL to be used for proceeding with payment on provider side. |
| generateToken | Boolean | (M) | (O) | true/false | The value is to be set to true as soon as Cardholder card data was stored by Merchant for future transactions. Must be false when consumer_initiated or recurrence not initial. |
| money.amount | BigDecimal | (M) | (O) | 38 | This is the total amount requested in the transaction. The amount of the decimal place is dependent on the currency. |
| money.currency | String | (M) | (O) | 3 | This is the currency of the transaction. Format: 3-character abbreviation according to ISO 4217. |
| parentTransactionId | String | (O) | (O) | 36 | This is the unique identifier of the referenced transaction. It is used for Non-Present Payments where Merchants are the payment initiators (not Consumers). Format UUID. Only required for not initial recurrences and consumer_initiated payments. |
| customTag | String | (O) | (O) | Unlimited (BD 400KB) | The item or product to be purchased in the transaction. This variable is optional and can be used as an additional information of the order. |
| orderId | String | - | (O) | 36 | This is the unique identifier assigned to each order. Format UUID. |
| notificationUrl | String | (O) | (O) | Unlimited (BD 400KB) | The URL to which any transaction state change notification will be sent. When this parameter is not present, the default notification URL specified in the merchant configuration is used instead. |
| redirectUrl.fail | String | (O) | (O) | Unlimited (BD 400KB) | The URL to which the consumer will be redirected after he has canceled a payment or payment has failed. This is normally a page on the merchant’s website. |
| redirectUrl.success | String | (O) | (O) | Unlimited (BD 400KB) | The URL to which the consumer will be redirected after a successful payment. This is normally a success confirmation page on the merchant’s website. |
| redirectUrl.threeDSChallengeResult | String | (O) | (O) | Unlimited (BD 400KB) | The URL where the consumer wants to receive the result of the challenge for 3DS payments or APM Paypal and Stripe Link redirect. Format: URI. |
| paymentDetails.type | String | (O) | (O) | Unlimited (BD 400KB) | Possible values: consumer_initiated, recurrence or credit_card_present. Required if payment details are informed. consumer_initiated: when the order is created by the consumer and it is going to pay by token. recurrence: when the order is created by the merchant and it is going to pay by token. Exceptionally, the initial recurrence could be paid by credit card. credit_card_present: when the order is created by the consumer and it is going to paid by credit card. |
| paymentDetails.minPeriod | Integer | (O) | (O) | 32 | Minimum period in days to charge a recurrence. Minimum value is 1. |
| paymentDetails.sequence | String | (O) | (O) | Unlimited (BD 400KB) | Possible values: sequence one of: initial, recurring or final. initial: first order of a recurrence recurring: order of a recurrence final: final order of a recurrence |
| threeDSSupport | String (Enum) | (O) | - | 13 | It indicates the interest level in paying the order through the 3DS process. This attribute admits the following values: no_3ds indifferent preferred_3ds required_3ds |
| purchaseId | String | (O) | - | Unlimited (BD 400KB) | Used to check whether a given order was already processed. |
| items.name | String | (O) or (M) for Order Insight C.E. 3.0) | (O) | 512 | Name of the product or service |
| items.sku | String | (O) or (M) for Order Insight C.E. 3.0) | (O) | 512 | Stock Keeping Unit identifier |
| items.quantity | Integer | (O) or (M) for Order Insight C.E. 3.0) | (0) | - | Number of units. Must be ≥ 1 |
| items.url | String | (O) or (M) for Order Insight C.E. 3.0) | (O) | 512 | URL to product/service details (optional) |
| items.unitPrice | decimal | (O) or (M) for Order Insight C.E. 3.0) | (O) | - | Price per unit. Must be > 0 |
| items.category | String | (O) or (M) for Order Insight C.E. 3.0) | (O) | 512 | Category of the item (e.g., books, services) |
| items.tax | decimal | (O) or (M) for Order Insight C.E. 3.0)) | (O) | - | Tax amount for the item (optional) |
| 3DS v2.0 FIELDS | |||||
| threeDSDetails .cardHolderAccountInformation .accountAge | String (Enum) | (O) | - | 17 | Period of time for which the cardholder has had an account with the 3DS requester. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails .cardHolderAccountInformation .accountLastChangeDate | String | (O) | - | 10 | Date in which the cardholder’s account with the 3DS Requestor was last changed, including billing or shipping address, new payment account, or new user(s) added. Format: ISO 8641/ YYYY-MM-DD. |
| threeDSDetails .cardHolderAccountInformation .accountLastChangeAge | String (Enum) | (O) | - | 17 | Period of time since the cardholder’s account information with the 3DS requester was last changed, including billing or shipping address, new payment account, or new user(s) added. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails .cardHolderAccountInformation .accountDate | String | (O) | - | 10 | Date in which the cardholder opened the account with the 3DS Requestor. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails .cardHolderAccountInformation .accountPasswordDate | String | (O) | - | 10 | Date in which the cardholder’s account with the 3DS requester had a password change or account reset. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails .cardHolderAccountInformation .accountPasswordAge | String (Enum) | (O) | - | 17 | Period of time since the cardholder’s account with the 3DS requester had a password change or account reset. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails .cardHolderAccountInformation . accountPurchaseCount | Integer | (O) | - | 9999 | Number of purchases with this cardholder account during the previous six months. |
| threeDSDetails .cardHolderAccountInformation .accountStoredCardAttempts | Integer | (O) | - | 999 | Number of add card attempts in the last 24 hours. |
| threeDSDetails .cardHolderAccountInformation .accountDailyTransactions | Integer | (O) | - | 999 | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 Hours. |
| threeDSDetails .cardHolderAccountInformation .accountYearlyTransactions | Integer | (O) | - | 999 | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. |
| threeDSDetails .cardHolderAccountInformation .accountEnrollmentDate | String | (O) | - | 10 | Date in which the payment account was enrolled in the cardholder’s account with the 3DS requester. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails .cardHolderAccountInformation .accountEnrollmentAge | String (Enum) | (O) | - | 17 | Period of time since the payment account was enrolled in the cardholder’s account with the 3DS requester. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails .cardHolderAccountInformation .accountShippingDate | String | (O) | - | 10 | Date in which the shipping address used in this transaction was first used with the 3DS requester. Format: ISO 8641/ YYYY-MM-DD. |
| threeDSDetails .cardHolderAccountInformation .accountShippingAge | String (Enum) | (O) | - | 17 | Period of time since the shipping address used for the transaction was first used with the 3DS requester. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails .cardHolderAccountInformation .accountShippingEqual | String (Enum) | (O) | - | 22 | Indicates whether the cardholder name on the account is identical to the shipping name used in this transaction. This attribute admits the following values: account_name_identical account_name_different |
| threeDSDetails .cardHolderAccountInformation .accountSuspiciousActivity | String (Enum) | (O) | - | 31 | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. This attribute admits the following values: no_suspicious_activity_observed suspicious_activity_observed |
| threeDSDetails .merchantRiskIndicator.deliveryEmailAddress | String | (O) | - | 254 | For electronic delivery, the email address to which the merchandise was delivered. |
| threeDSDetails .merchantRiskIndicator.deliveryTimeframe | String (Enum) | (O) | - | 25 | Indicates the merchandise delivery timeframe. This attribute admits the following values: electronic_delivery same_day_shipping overnight_shipping two_or_more_days_shipping |
| threeDSDetails .merchantRiskIndicator.giftCardAmount | Integer | (O) | - | 38 | For prepaid or gift card purchase, the total purchase amount of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). |
| threeDSDetails .merchantRiskIndicator.giftCardCount | Integer | (O) | - | 99 | For prepaid or gift card purchase, total count of individual prepaid or gift card(s)/code(s) purchased. |
| threeDSDetails .merchantRiskIndicator.giftCardCurrency | String | (O) | - | 3 | For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card. |
| threeDSDetails .merchantRiskIndicator.preOrderDate | String | (O) | - | 10 | For a pre-ordered purchase, the expected date that the merchandise will be available. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails .merchantRiskIndicator.preOrderAvailability | String (Enum) | (O) | - | 21 | Indicates whether the cardholder is placing an order for merchandise with a future availability or release date. This attribute admits the following values: merchandise_available future_availability |
| threeDSDetails .merchantRiskIndicator.reorderItemsInd | String (Enum) | (O) | - | 18 | Indicates whether the cardholder is reordering previously purchased merchandise. This attribute admits the following values: first_time_ordered reordered |
| threeDSDetails .merchantRiskIndicator.shippingIndicator | String (Enum) | (O) | - | 32 | Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator value that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the shipping indicator value for the physical goods, or if they are all digital goods, use the shipping indicator value that describes the most expensive item. This attribute admits the following values: ship_cardholders_billing_address: ship to cardholder’s billing address. ship_another_verified_address: ship to another verified address on file with merchant. ship_another_address: ship to address that is different from the cardholder’s billing address. ship_to_store: ship to store / pick-up at local store. Store address shall be populated in shipping address fields. digital_goods: includes online services, electronic gift cards and redemption codes. travel_and_event_tickets: travel and Event tickets, not shipped. others: for example, gaming, digital services not shipped, e-media subscriptions, etc. |
| threeDSDetails .threeDSRequestorAuthenticationInfo .threeDSReqAuthData | String | (O) | - | 20000 | Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS requester authentication method, this field carries data that the ACS can use to verify the authentication process. E.g., if the 3DS requester authentication method is: login_using_federated_id: then this element can carry information about the provider of the federated ID and related information. login_using_fido_authenticator: then this element can carry the FIDO attestation data (including the signature). login_using_fido_authenticator_data_signed: then this element can carry FIDO Attestation data with the FIDO assurance data signed. src_assurance_data: then this element can carry the SRC assurance data. |
| threeDSDetails .threeDSRequestorAuthenticationInfo .threeDSReqAuthMethod | String (Enum) | (O) | - | 42 | Mechanism used by the cardholder to authenticate to the 3DS requester. This attribute admits the following values: no_3ds_authentication: no 3DS requester authentication occurred - i.e. cardholder “logged in” as guest. login_using_own_credentials: login to the cardholder account at the 3DS requester system using 3DS requester’s own credentials. login_using_federated_id: login to the cardholder account at the 3DS requester system using federated ID. login_using_issuer_credentials: login to the cardholder account at the 3DS requestrr system using issuer credentials. login_using_third_party_authentication: login to the cardholder account at the 3DS Requestor system using third-party authentication. login_using_fido_authenticator: login to the cardholder account at the 3DS requester system using FIDO authenticaton. login_using_fido_authenticator_data_signed: login to the cardholder account at the 3DS Requestor system using FIDO authenticator (FIDO assurance data signed). src_assurance_data: SRC assurance data. |
| threeDSDetails .threeDSRequestorAuthenticationInfo .threeDSReqAuthTimestamp | String | (O) | - | 20 | Date and time in UTC of the cardholder authentication. Format: ISO 8601 in UTC / YYYY-MM-DDTHH:mm:ssZ. |
| threeDSDetails .threeDSRequestorPriorTransactionAuthenticationInfo .threeDSReqPriorAuthData | String | (O) | - | 2048 | Data that documents and supports a specific authentication process. In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS requester authentication method, this field carries data that the ACS can use to verify the authentication process. In future versions of the specification, these details are expected to be included. |
| threeDSDetails .threeDSRequestorPriorTransactionAuthenticationInfo .threeDSReqPriorAuthMethod | String (Enum) | (O) | - | 31 | Mechanism used by the cardholder to authenticate beforehand with the 3DS requester. This attribute admits the following values: acs_frictionless_authentication: frictionless authentication occurred by ACS. acs_cardholder_challenge: cardholder challenge occurred by ACS. avs_verified: AVS verified. other_issuer_method: any other mechanism not listed above. |
| threeDSDetails .threeDSRequestorPriorTransactionAuthenticationInfo .threeDSReqPriorAuthTimestamp | String | (O) | - | 20 | Date and time in UTC of the prior cardholder authentication. Format: ISO 8601 in UTC / YYYY-MM-DDTHH:mm:ssZ. |
| threeDSDetails .threeDSRequestorPriorTransactionAuthenticationInfo .threeDSReqPriorRef | String | (O) | - | 36 | This data element provides additional information to the ACS to determine the best approach for handling a request. |
| threeDSDetails .acsRenderingType.acsInterface | String (Enum) | (O) | - | 9 | This is the ACS interface that the challenge will present to the cardholder. This attribute admits the following values: native_ui html_ui |
| threeDSDetails .acsRenderingType.acsUiTemplate | String (Enum) | (O) | - | 13 | Identifies the UI template format that the ACS first presents to the consumer. Valid values for each Interface: Native UI: text, single_select, multi_select and OOB. HTML UI: all values. Note that html_other is only valid in combination with html_ui. If used with native_ui, the DS will respond with an error. This attribute admits the following values: text single_select multi_select OOB html_other |
| threeDSDetails .deviceRenderingOptionsSupported.sdkInterface | String (Enum) | (O) | - | 6 | Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. This attribute admits the following values: native html both |
| threeDSDetails .deviceRenderingOptionsSupported.sdkUiType | String (Enum) | (O) | - | 13 | Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Valid values for each Interface: Native UI: text, single_select, multi_select and OOB. HTML UI: all values. Currently, all SDKs need to support all UI types. In the future, however, this may change (for example, smart watches may support a UI Type not yet defined by this specification). This attribute admits the following values: text single_select multi_select OOB html_other |