Send Payment Request

Once the configuration has been completed and the consumer presses “Pay” the Payment Request needs to be sent to start the transaction.

A full breakdown of the Payment Request options are shown below.

Payment Request

Payment Request
Field Name	State	Data Type	Description
invoiceId	Mandatory	String	Order/invoice/transaction/basket number generated by the host website. This ID must be unique for this transaction. This value must match the value provided during authorisation or the request will be rejected.
description	Optional	String	Message from host website to consumer, displayed on the payment form.
paymentSettings	Mandatory	Object	See the paymentSettings table.
customerDetails	Mandatory	Object	See the customerDetails table.
orderLines	Conditional	Array Max 1000 Objects	See the orderLines table. Mandatory if using Klarna.
amountBreakdown	Optional	Object	See the amountBreakdown table. Optional if using Klarna.
periodic	Conditional	Object	See the periodic table. Mandatory if transaction is Recurring.
orderDetails	Optional	Object	See the orderDetails table.
requestorDetails	Optional	Object	See the requestorDetails table.
sdkDetails	Conditional	Object	See the sdkDetails table. Mandatory if using a Mobile SDK solution.
auth	Mandatory	Object	See the auth table.
transactionType	Optional	Boolean	Transaction type being requested. If this field is not supplied the value configured on the platform is used. AUTH Authorisation only SALE Authorisation and Settlement TOKENIZATION Card Token Registration only VERIFICATION Card verification and tokenisation PRE-AUTH Pre-authorisation REFUND Refund
amount	Mandatory	Decimal	Total amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account will be processed as £1.00. This value must match the value provided during authorisation or the request will be rejected.
currency	Mandatory	String	GBP Pound Sterling
attachment	Conditional	String Serialized JSON object	This field is only required when processing Klarna payments, and is Conditional for Klarna as well. If your solution has access to one of the below pieces of information and does NOT supply it, you may be denied payment authorisation from Klarna.More detail on the format and schema of the JSON Object can be found on the Klarna page. air_reservation_details bus_reservation_details train_reservation_details ferry_reservation_details hotel_reservation_details car_rental_reservation_details event voucher subscription marketplace_seller_info marketplace_winner_info customer_account_info payment_history_full payment_history_simple other_delivery_address
entryMode	Conditional	String	Confirms the MOTO (Mail Order/Telephone Order) mode being used for the transaction. telephone-order Card details have been input on behalf of a cardholder and not stored in any way mail-order Card details have been input on behalf of a cardholder from a stored source Mandatory if a MOTO transaction is being processed. As the transaction is not being actioned by the consumer directly Payer Authentication will not be performed. This field must be omitted if the transaction is eCommerce.
merchantCustomData	Optional	String Max 1024 bytes	Free text field for integrated system to pass custom data that will be stored against the transaction. This data will be available via the Transaction Management functions.
softDescriptor	Optional	String String Max 21 Characters	The Soft Descriptor is the line of copy that identifies transactions on a cardholder’s account activity and statement. It is recommended to write your descriptors clearly, as it helps cardholders recognise when and where the transaction took place. Currently only supported for PayPal transactions. The format of the entries of the cardholder statements will be; PAYPAL_prefix+(space)+merchant_descriptor+(space)+soft_descriptor For example; A merchant with the ‘Merchant Descriptor’ configured as ‘Test Ltd’ and passing a softDescriptor of “Clothing Sale” will show as; PAYPAL * Test Ltd Clothing Sale

Personally Identifiable Information

In the softDescriptor field above, you are free to pass a wide variety of data. You must however be careful to not include any Personally Identifiable Information. This can include vehicle registration details, cardholder name, and many other data. Please refer to European General Data Protection Regulations (Article 4) for detailed guidance on what should not be included here.

paymentSettings

paymentRequest > paymentSettings
Field Name	State	Data Type	Description
allowNonThreeDS	Optional	Boolean	Confirms whether 3D Secure should be disabled for transaction. Default is false. true 3DS checking not performed false 3DS checking is performed This option is only available with prior approval
threeDSVersion	Optional	String	Version of the 3D Secure sevice to use in the transaction. Default value is 2 1 3D Secure v1 2 3D Secure v2
paMatrixV2	Optional	String	Reserved for future use.
avsPostCodeMatrix	Optional	Integer	Only validated when the Cardholder's billing address is in the uk. If the merchant wishes to validate the numerics of the Post Code as part of the transaction this field is used to determine which results should be rejected. 0 Reject None (all results will be accepted) 2 Reject "Not Provided" results 4 Reject "Not Checked" results 8 Reject "Matched" results 16 Reject "Not Matched" results 32 Reject "Partial Match" results When more than one condition is required the above values need to be combined. For example, if the requirement is to reject “Not Provided” 2 and “Not Checked” 4 a value of 6 would need to be passed. If this matrix is not supplied or configured all results will be approved.
avsHouseMatrix	Optional	Integer	Only validated when the Cardholder's billing address is in the uk. If the merchant wishes to validate the House Number as part of the transaction this field is used to determine which results should be rejected. 0 Reject None (all results will be accepted) 2 Reject "Not Provided" results 4 Reject "Not Checked" results 8 Reject "Matched" results 16 Reject "Not Matched" results 32 Reject "Partial Match" results When more than one condition is required the above values need to be combined. For example, if the requirement is to reject “Not Provided” 2 and “Not Checked” 4 a value of 6 would need to be passed. If this matrix is not supplied or configured all results will be approved.
cscMatrix	Optional	Integer	If the merchant wishes to validate the Card Security Code (CSC) as part of the transaction this field is used to determine which results should be rejected. 0 Reject None (all results will be accepted) 2 Reject "Not Provided" results 4 Reject "Not Checked" results 8 Reject "Matched" results 16 Reject "Not Matched" results When more than one condition is required the above values need to be combined. For example, if the requirement is to reject “Not Provided” 2 and “Not Checked” 4 a value of 6 would need to be passed. If this matrix is not supplied all results will be approved.
paMatrix	Optional	Integer	If the merchant wishes to validate the results of the Payer Authentication check as part of the transaction this field is used to determine which results the merchant wishes to REJECT. 0 Reject None (all results will be accepted) 1 U on Enrolment - Enrolment did not complete 2 U on Authentication - Authentication did not completed When more than one condition is required the above values need to be combined. For example, if the requirement is to reject “U on Enrolment” 1 and “U on Authentication” 2 a value of 3 would need to be passed. If this matrix is not supplied all results will be approved.
terminalId	Mandatory	String	Provided to the integrator following the successful creation of a test account. This value must match the value provided during authorisation or the request will be rejected.
returnUrl	Mandatory	URL	Address where the consumer is to be returned following a successful payment
failureReturnUrl	Mandatory	URL	Address where the consumer is to be returned following a unsuccessful payment.
callbackUrl	Mandatory	URL	Address where we will send the payment notification in the event of a successful result.
failureCallbackUrl	Optional	URL	Address where Checkout is to send the payment notification (payment result callback) in the event of an unsuccessful result. If not provided the postLink URL will be used.
notificationUrl	Optional	URL	Confirms where ACS is to send the Payer Authentication results in the specific case where 3D Secure v2 and direct API integration is used.

LOCALHOST URL's

Remember when developing and testing your solution that you are directing the browser to an external site. You should take care to ensure any URL's you specify can be accessed from the World Wide Web. localhost URL's will be unreachable from our platform.

customerDetails

paymentRequest > customerDetails
Field Name	State	Data Type	Description
addressMatch	Optional	String	Indicates whether the Cardholder Shipping Address and the Cardholder Billing address are the same. Y Shipping & billing addresses match N Shipping & billing addresses do not match
accountDetails	Optional	Object	See the accountDetails table.
billingAddress	Mandatory	Object	See the billingAddress table.
deliveryDetails	Mandatory	Object	See the deliveryDetails table.
browserDetails	Conditional	Object	See the browserDetails table.
email	Conditional	String	The email address associated with the account that is either entered by the Cardholder or is on file with the 3DS Requestor. Shall meet requirements of Section 3.4 of IETF RFC 5322. Required unless market or regional mandate restricts sending this information.
homePhone	Conditional	String	The home phone number provided by the Cardholder. Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899) CC: 1-3 characters Subscriber: Variable, maximum 15 characters Required, if available, unless market or regional mandate restricts sending this information.
mobilePhone	Conditional	String	The mobile phone number provided by the Cardholder. Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899) CC: 1-3 characters Subscriber: Variable, maximum 15 characters Required, if available, unless market or regional mandate restricts sending this information.
workPhone	Conditional	String	The work phone number provided by the Cardholder. Phone numbers must be specified in the following format: CountryCode-Subscriber (e.g. 1-1234567899) CC: 1-3 characters Subscriber: Variable, maximum 15 characters Required, if available, unless market or regional mandate restricts sending this information.
title	Conditional	String	Title prefixing the cardholders name e.g. Mr, Miss, Mrs
firstName	Conditional	String	First name of the cardholder. Alphanumeric & Special Characters as per ISO/IEC 8859 Common Character Set. Required unless market or regional mandate restricts sending this information.
lastName	Conditional	String	Last name of the cardholder. Alphanumeric & Special Characters as per ISO/IEC 8859 Common Character Set. Required unless market or regional mandate restricts sending this information.

customerDetails.accountDetails

Best Practice Advice

The following customerDetails.accountDetails block is entirely optional, but it is recommended to be included when using 3D Secure version 2. Inclusion of these fields makes it less likely the Cardholder will be subjected to an Authentication Challenge.

paymentRequest > customerDetails > accountDetails
Field Name	State	Data Type	Description
accountAgeIndicator	Optional	String	Length of time that the cardholder has had the account with the merchant. 01 No account (Guest checkout) 02 Created during this transaction 03 Less than 30 days 04 Between 30 - 60 days 05 More than 60 days
accountChangeDate	Optional	Datetime	Date that the cardholders account with the merchant was last changed including billing or shipping address, new payment account or new user(s) added.
accountChangeIndicator	Optional	String	Length of time since the cardholder’s account information with the merchant was last changed, including billing or shipping address, new payment account or new user(s) added. 01 Changed during this transaction 02 Less than 30 days 03 Between 30 - 60 days 04 More than 60 days
accountDate	Optional	Datetime	Date that the cardholder opened the account with the merchant.
accountDayTransactions	Optional	Integer	Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous 24 hours.
accountId	Optional	String Max. 64 Characters	Additional information about the account optionally provided by the merchant.
accountPasswordChangeDate	Optional	Datetime	Date that cardholder’s account with the merchant had a password change or account reset.
accountPasswordChangeIndicator	Optional	String	Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset. 01 No change 02 Changed during this transaction 03 Less than 30 days 04 Between 30 - 60 days 05 More than 60 days
accountProvisioningAttempts	Optional	Integer	Number of “Add Card” attempts in the last 24 hours.
accountPurchaseCount	Optional	Integer	Number of purchases with this cardholder account during the previous six months.
accountType	Optional	String	Indicates the type of account. For example, for a multi-account card product. 01 Not applicable 02 Credit 03 Debit
accountYearTransactions	Optional	Integer	Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous year.
paymentAccountAgeIndicator	Optional	String	Indicates the length of time that the payment account was enrolled in the cardholder’s account with the merchant. 01 No account (Guest checkout) 02 Created during this transaction 03 Less than 30 days 04 Between 30 - 60 days 05 More than 60 days
paymentAccountDate	Optional	Datetime	Date that the payment account was enrolled in the cardholder’s account with the merchant.
priorAuthenticationData	Optional	String Max. 2048 Characters in JSON format	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 Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. In future versions of the specification, these details are expected to be included.
priorAuthenticationMethod	Optional	String	Mechanism used by the Cardholder to previously authenticate to the merchant. 01 Frictionless authentication occurred by ACS 02 Cardholder challenge occurred by ACS 03 AVS verified 04 Other Issuer methods
priorAuthenticationReference	Optional	String Max. 36 Characters	This data element provides additional information to the ACS to determine the best approach for handing a request. This data element contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).
priorAuthenticationTimestamp	Optional	String Length: 12 Characters	Date and time in UTC of the prior cardholder authentication. Date format = YYYYMMDDHHMM
suspiciousAccountActivity	Optional	String	Indicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account. 01 No suspicious activity has been observed. 02 Suspicious activity has been observed.

customerDetails.billingAddress

Best Practice Advice

The following customerDetails.billingAddress block contains several Mandatory Fields. If known, but not included, our solution may prompt for them. It is therefore recommended that you pass in what you know, to prevent the Cardholder from needing to enter information more than once.

payment Request > customer Details > billing Address
Field Name	State	Data Type	Description
title	Conditional	String Max 20 chars.	Cardholder's title. If using Klarna, this field is Optional and is restricted to these values: Mr Designates a Male cardholder. Ms Designates a Female cardholder.
firstName	Mandatory	String Max 32 Char.	Cardholder's First Name
lastName	Mandatory	String Max 32 Char.	Cardholder's Surname or Last Name
addressLine1	Mandatory	String Max 50 Char.	Address line 1 of the cardholders billing address.The house number passed here (numerics only) will be used in AVS checks.
addressLine2	Optional	String Max 50 Char.	Address line 2 of the cardholders billing address.
addressLine3	Optional	String Max 50 Char.	Address line 3 of the cardholders billing address.
postalCode	Mandatory	String Max 13 Char.	Post code of the cardholders billing address.The house number passed here (numerics only) will be used in AVS checks.
city	Conditional	String Max 100 Char.	City of the cardholders billing address. If using Klarna, this field is Mandatory.
region	Optional	String Max 3 Char.	Region, state or province of the cardholder. Format: ISO 3166-2
phone	Optional	String	Cardholder's home phone number. If using Klarna, this field is Mandatory.
country	Mandatory	String Max 2 Char.	ISO country code Format: ISO 3166-1

customerDetails.deliveryDetails

payment Request > customer Details > deliveryDetails
Field Name	State	Data Type	Description
deliveryAddressUsageDate	Optional	Datetime	Date when the shipping address used for this transaction was first used with the 3DS Requestor.
deliveryAddressUsageIndicator	Optional	String	Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 01 This transaction. 02 Less than 30 days ago. 03 30-60 days ago. 04 More than 60 days ago.
deliveryEmailAddress	Optional	String Max 254 Chars.	For Electronic delivery, the email address to which the merchandise was delivered.
deliveryIndicator	Optional	String	Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code 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 code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item. 01 Ship to cardholder’s billing address. 02 Ship to another merchant verified address. 03 Ship to address that is different from billing. 04 Ship to Store or local pick up. Store address should be used in shipping address fields. 05 Digital goods. 06 Travel and Event tickets not shipped. 07 Other (e.g. Gaming, digital services, subs).
deliveryNameIndicator	Optional	String	Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. 01 Account name identical to shipping name. 02 Account name different to shipping name.
deliveryTimeFrame	Mandatory	String	Indicates the merchandise delivery timeframe. 01 Electronic Delivery. 02 Same day shipping. 03 Overnight shipping. 04 Two-day or more shipping.
deliveryAddress	Mandatory	Object	See the deliveryAddress table.

customerDetails.deliveryDetails.deliveryAddress

Best practice Advice

The following customerDetails.deliveryDetails.deliveryAddress block contains several Mandatory Fields. If the billing address and delivery address match however, you can re-use the details from the previous customerDetails.billingAddress block.

payment Request > customer Details > deliveryDetails > deliveryAddress
Field Name	State	Data Type	Description
title	Conditional	String Max 20 chars.	Cardholder's title. If using Klarna, this field is Optional and is restricted to these values: Mr Designates a Male cardholder. Ms Designates a Female cardholder.
firstName	Mandatory	String Max 32 Char.	Consumer's First Name
lastName	Mandatory	String Max 32 Char.	Consumer's Surname or Last Name
addressLine1	Mandatory	String Max 50 Char.	Address line 1 of the consumers delivery address.
addressLine2	Optional	String Max 50 Char.	Address line 2 of the consumers delivery address.
addressLine3	Optional	String Max 50 Char.	Address line 3 of the consumers delivery address.
postalCode	Mandatory	String Max 13 Char.	Post code of the cardholders billing address.The house number passed here (numerics only) will be used in AVS checks.
city	Conditional	String Max 100 Char.	City of the cardholders billing address. If using Klarna, this field is Mandatory.
region	Optional	String Max 3 Char.	Region, state or province of the consumer's delivery address. Format: ISO 3166-2
phone	Optional	String	Consumer's home phone number.
country	Mandatory	String Max 2 Char.	ISO country code Format: ISO 3166-1

customerDetails.browserDetails

Object Block Usage Advice

Checkout captures and supplies this block on your behalf, so this section is only needed if you are integrating directly.

payment Request > customer Details > browserDetails
Field Name	State	Data Type	Description
acceptHeader	Mandatory	String Max 2048 Chars.	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
challengeWindowSize	Mandatory	String Max 2 Chars.	Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window. 01 250 x 400 04 600 x 400 02 390 x 400 05 Full Screen 03 500 x 600
javaEnabled	Mandatory	Boolean	Confirms whether JavaScript is enabled in the consumer's browser. true JavaScript enabled. false JavaScript not enabled.
language	Mandatory	String Max 8 Chars.	Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.
screenColorDepth	Mandatory	String	Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. 1 1 bit. 16 16 bit. 4 4 bit. 24 24 bit. 8 8 bit. 32 32 bit. 15 15 bit. 48 48 bit.
screenHeight	Mandatory	String Max 6 Chars.	Total height of the Cardholder's screen in pixels. Value is returned from the screen.height property.
screenWidth	Mandatory	String Max 6 Chars.	Total width of the cardholder's screen in pixels. Value is returned from the screen.width property.
timeZone	Mandatory	String Max 5 Chars.	Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead.
userAgent	Mandatory	String Max 2048 Chars.	Exact content of the HTTP user-agent header.

orderLines

Array Usage Advice

This array only needs to be populated if the transaction uses Klarna. You can pass a maximum of 1000 Objects. Each Object in the Array should consist of the following:

payment Request > orderLines
Field Name	State	Data Type	Description
name	Conditional	String	Descriptive name of the order line item. Mandatory if using Klarna.
quantity	Conditional	Integer	Quantity of the order line item. Mandatory if using Klarna.
unitPrice	Conditional	Integer	Price for a single unit of the order line. Includes tax. Mandatory if using Klarna.
taxRate	Conditional	Integer	Tax rate of the order line. The percentage value is represented with two implicit decimals. I.e 1900 = 19% Mandatory if using Klarna.
totalAmount	Conditional	Integer	Total price for the order line. Includes tax. Mandatory if using Klarna.
totalTaxAmount	Conditional	Integer	Total tax amount of the order line. Mandatory if using Klarna.
imageUrl	Optional	String Max 1024 Chars.	URL to an image that can be later embedded in communications between Klarna and the customer. A minimum of 250x250 px resolution is recommended for the image to look good in the Klarna app, and below 50x50 px won't even show. We recommend using a good sized image (650x650 px or more), however the file size must not exceed 12MB.
productUrl	Optional	String Max 1024 Chars.	URL to the product in the merchant’s webshop that can be later used in communications between Klarna and the customer.
type	Optional	String	The nature of the product being purchased. Must be one of the following values: physical discount shipping_fee sales_tax digital gift_card store_credit surcharge
reference	Optional	String Max 64 Chars.	Client facing article number, SKU or similar.

Personally Identifiable Information

In the reference field above, you are free to pass a wide variety of data. You must however be careful to not include any Personally Identifiable Information. This can include vehicle registration details, cardholder name, and many other data. Please refer to European General Data Protection Regulations (Article 4) for detailed guidance on what should not be included here.

amountBreakdown

payment Request > amountBreakdown
Field Name	State	Data Type	Description
shipping	Optional	Object	See the shipping table. Optional if using Klarna.
discount	Optional	Object	See the discount table. Optional if using Klarna.

shipping

payment Request > amountBreakdown > shipping
Field Name	State	Data Type	Description
totalAmount	Optional	Decimal	The shipping amount as a sub total of the total amount. Only used in Klarna payments.

discount

payment Request > amountBreakdown > discount
Field Name	State	Data Type	Description
totalAmount	Optional	Decimal	The discount amount as a sub total of the total amount. Only used in Klarna payments.

periodic

Object Block Usage Advice

This object should only be populated if the transaction is recurring.

payment Request > periodic
Field Name	State	Data Type	Description
recurringFrequency	Conditional	String	Indicates the minimum number of days between individual authorizations. Mandatory only for recurring payments (instalments or subscriptions).
recurringExpirationDate	Conditional	String	Expiration date of the recurring transaction, mandatory for instalment payments. Format: YYY-MM-DD
periodicType	Mandatory	String	Type of periodic transaction. ucof Unscheduled Credentials on File
numberOfInstalments	Conditional	String	Number of instalments, mandatory for instalment payments.

orderDetails

paymentRequest > orderDetails
Field Name	State	Data Type	Description
deviceChannel	Optional	String	Indicates the type of channel interface being used to initiate the transaction. 01 App-based (APP) 02 Browser (BRW) 03 3DS Requester Initiated (3RI) Default value 02
giftCardAmount	Optional	Integer	For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, GBP 123.45 is 123).
giftCardCount	Optional	Integer	For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
giftCardCurrencyId	Optional	String	For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.
preOrderDate	Optional	Datetime	For a pre-ordered purchase, the expected date that the merchandise will be available.
preOrderPurchaseIndicator	Optional	String	Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. 01 Merchandise available 02 Future availability
purchaseDate	Conditional	Datetime	Date and time of the purchase expressed in UTC.
reorderItemsIndicator	Optional	String	Indicates whether the cardholder is reordering previously purchased merchandise. 01 First time ordered 02 Reordered
transactionType	Conditional	String	Identifies the type of transaction being authenticated. 01 Goods/service purchase 03 Check acceptance 10 Account funding 11 Quasi-Cash transaction 28 Prepaid activation and load

requestorDetails

Object Block Usage Advice

Most of this block will be configured at our end as default values. Passing any of the fields in will use the new value for that transaction only.

paymentRequest > requestorDetails
Field Name	State	Data Type	Description
merchantName	Conditional	String Max 25 Char.	Merchant name used by the Payer Authentication process. Field is mandatory if processing Payer Authentication. Only numbers, letters and spaces supported.
visaMid	Conditional	String	Merchant number used for Payer Authentication when a VISA card is presented. If no MID is presented any Visa transactions will not be put through the Payer Authentication process.
mastercardMid	Conditional	String	Merchant number used for Payer Authentication when a Mastercard card is presented. If no MID is presented any Mastercard transactions will not be put through the Payer Authentication process.
amexMid	Conditional	String	Merchant number used for Payer Authentication when a Amex card is presented. If no MID is presented any Amex transactions will not be put through the Payer Authentication process.
merchantStoreId	Optional	Integer	Id for the Merchant Store for where the transaction is to be processed. If this field is not passed the value configured against the account is used.
merchantDepartmentId	Optional	Integer	Id for the Merchant Department for where the transaction is to be processed. If this field is not passed the value configured against the account is used.
merchantUrl	Conditional	String	Merchant URL used by the Payer Authentication process. Field is mandatory if processing Payer Authentication.
requestorAuthenticationData	Optional	String Max 20,000 Char.	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 Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. For example, if the 3DS Requestor Authentication Method is: 03 then this element can carry information about the provider of the federated ID and related information. 06 then this element can carry the FIDO attestation data (including the signature). 07 then this element can carry FIDO Attestation data with the FIDO assurance data signed. 08 then this element can carry the SRC assurance data.
requestorAuthenticationMethod	Optional	String	Mechanism used by the Cardholder to authenticate to the merchant. 01 No 3DS Requestor authentication (e.g. guest). 02 Login to the cardholder account at the 3DS Requestor system using 3DS Requestor system using 3DS Requestor’s own credentials. 03 Login to the cardholder account at the 3DS Requestor system using federated ID. 04 Login to the cardholder account at the 3DS Requestor system using issuer credentials. 05 Login to the cardholder account at the 3DS Requestor system using third-party authentication. 06 Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator. 07 Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO assurance data signed). 08 SRC Assurance Data.
requestorAuthenticationTimeStamp	Optional	Datetime	Date and time in UTC of the cardholder authentication. Format: YYYYMMDDHHMM
scaExemptionIndicator	Optional	String	Confirms any SCA exemptions held by the merchant. This field should only be populated when the merchant has a written agreement with their Acquirer.

sdkDetails

Object Block Usage Advice

These details should only be populated if the transaction is within a Mobile SDK

paymentRequest > sdkDetails
Field Name	State	Data Type	Description
clientAuthRequest	Conditional	String Max 2048 Char.	Json data received from 3DS SDK. This json object will contain the fields below and should be sent as received from the 3DS SDK.
encryptedDeviceInfo	Mandatory	String Max 64,000 Char.	WE Object (represented as a string) as defined in Section 6.2.2.1 containing data encrypted by the SDK for the DS to decrypt.
sdkAppId	Mandatory	String Max 36 Char.	Universally unique ID created upon all installations of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation.
sdkEphemeralPublicKey	Mandatory	String Max 256 Char.	Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.
sdkReferenceNumber	Mandatory	String Max 32 Char.	Identifies the vendor and version for the 3DS SDK that is integrated in a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.
sdkTransactionId	Mandatory	String Max 32 Char.	Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.

auth

paymentRequest > auth
Field Name	Data Type	Description
access_token	String	Access token provided by the DNA platform for this transaction. The token should be securely stored ready to be used in the transaction request.
expires_in	Integer	Number of seconds from generation until the access_token expires. If the token is not used before this time has passed a new token will need to be requested.
refresh_token	String	Reserved for future use.
scope	String	Confirmation of the scope passed in the authorisation request.
token_type	String	Type of token issued Bearer Bearer token

Example Code

window.DNAPayments.openPaymentPage(
{
    currency: 'GBP',
    description: 'CarService',
    paymentSettings: {
        terminalId: 'a398d836-aeae-44e8-90b3-6726ecbdb608',
        returnUrl: 'https: //test-pay.dnapayments.com/checkout/success.html',
        failureReturnUrl: 'https: //test-pay.dnapayments.com/checkout/failure.html',
        callbackUrl: 'https: //pay.dnapayments.com/checkout',
        failureCallbackUrl: 'https: //testmerchant/order/1123/fail'
    },
    customerDetails: {
        accountDetails: {
            accountId: 'uuid000001',
            accountPurchaseCount: 4,
            paymentAccountAgeIndicator: '05',
            suspiciousAccountActivity: '01'
        },
        billingAddress: {
            firstName: 'John',
            lastName: 'Doe',
            addressLine1: '12 FulhamRd',
            postalCode: 'SW61HS',
            city: 'London',
            country: 'GB'
        },
        deliveryDetails: {
            deliveryAddressUsageIndicator: '04',
            deliveryIndicator: '01',
            deliveryAddress: {
                firstName: 'John',
                lastName: 'Doe',
                addressLine1: '12 FulhamRd',
                addressLine2: 'Fulham',
                postalCode: 'SW61HS',
                city: 'London',
                phone: '0475662834',
                region: 'HMF',
                country: 'GB'
            }
        },
        email: 'demo@dnapayments.com',
        mobilePhone: '44-07123456789',
        firstName: 'John',
        lastName: 'Doe'
    },
    orderLines: [
        {
            name: 'Runningshoe',
            quantity: 1,
            unitPrice: 120,
            taxRate: 20,
            totalAmount: 120,
            totalTaxAmount: 20,
            imageUrl: 'https: //www.exampleobjects.com/logo.png',
            productUrl: 'https: //.../AD6654412.html'
        },
        {
            name: 'Tracksuit',
            quantity: 2,
            unitPrice: 30,
            taxRate: 20,
            totalAmount: 60,
            totalTaxAmount: 10,
            imageUrl: 'https: //www.exampleobjects.com/logo2.png',
            productUrl: 'https: //.../AD6654125.html'
        }
    ],
    amount: 24,
    amountBreakdown: {
    shipping: {
        totalAmount: 2
    },
    discount: {
        totalAmount: 2
    }
  },
  attachment: '{\"customer_account_info\":[{\"unique_account_identifier\":\"test@gmail.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]}',
    auth: {
        access_token: 'qy/ZWj049WHUZj+8i1pUwmYxswo4GXK+Z5',
        expires_in: 7200,
        scope: 'payment integration_seamless',
        token_type: 'Bearer'
    }
)

note

Once the request has been made successfully, the cardholder is redirected and the payment form is loaded. The cardholder needs to submit their payment details and press Pay to trigger a Payment Result.