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 NameStateData TypeDescription
invoiceIdMandatoryString

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.

descriptionOptionalStringMessage from host website to consumer, displayed on the payment form.
paymentSettingsMandatoryObjectSee the paymentSettings table.
customerDetailsMandatoryObjectSee the customerDetails table.
orderLinesConditionalArray
Max 1000 Objects
See the orderLines table.

Mandatory if using Klarna.
amountBreakdownOptionalObjectSee the amountBreakdown table.

Optional if using Klarna.
periodicConditionalObjectSee the periodic table.

Mandatory if transaction is Recurring.
orderDetailsOptionalObjectSee the orderDetails table.
requestorDetailsOptionalObjectSee the requestorDetails table.
sdkDetailsConditionalObjectSee the sdkDetails table.

Mandatory if using a Mobile SDK solution.
authMandatoryObjectSee the auth table.
transactionTypeOptionalBooleanTransaction type being requested. If this field is not supplied the value configured on the platform is used.
AUTHAuthorisation only
SALEAuthorisation and Settlement
TOKENIZATIONCard Token Registration only
VERIFICATIONCard verification and tokenisation
PRE-AUTHPre-authorisation
REFUNDRefund
amountMandatoryDecimal

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.

currencyMandatoryString
GBPPound Sterling
attachmentConditionalString

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
entryModeConditionalString

Confirms the MOTO (Mail Order/Telephone Order) mode being used for the transaction.

telephone-orderCard details have been input on behalf of a cardholder and not stored in any way
mail-orderCard 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.

merchantCustomDataOptional

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.

softDescriptorOptionalString

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

paymentSettings

paymentRequest > paymentSettings
Field NameStateData TypeDescription
allowNonThreeDSOptionalBoolean

Confirms whether 3D Secure should be disabled for transaction. Default is false.

true3DS checking not performed
false3DS checking is performed

This option is only available with prior approval

threeDSVersionOptionalString

Version of the 3D Secure sevice to use in the transaction. Default value is 2

13D Secure v1
23D Secure v2
paMatrixV2OptionalStringReserved for future use.
avsPostCodeMatrixOptionalInteger

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.

0Reject None (all results will be accepted)
2Reject "Not Provided" results
4Reject "Not Checked" results
8Reject "Matched" results
16Reject "Not Matched" results
32Reject "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.

avsHouseMatrixOptionalInteger

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.

0Reject None (all results will be accepted)
2Reject "Not Provided" results
4Reject "Not Checked" results
8Reject "Matched" results
16Reject "Not Matched" results
32Reject "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.

cscMatrixOptionalInteger

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.

0Reject None (all results will be accepted)
2Reject "Not Provided" results
4Reject "Not Checked" results
8Reject "Matched" results
16Reject "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.

paMatrixOptionalInteger

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.

0Reject None (all results will be accepted)
1U on Enrolment - Enrolment did not complete
2U 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.

terminalIdMandatoryString

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.

returnUrlMandatoryURLAddress where the consumer is to be returned following a successful payment
failureReturnUrlMandatoryURLAddress where the consumer is to be returned following a unsuccessful payment.
callbackUrlMandatoryURLAddress where we will send the payment notification in the event of a successful result.
failureCallbackUrlOptionalURL

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.

notificationUrlOptionalURL

Confirms where ACS is to send the Payer Authentication results in the specific case where 3D Secure v2 and direct API integration is used.

customerDetails

paymentRequest > customerDetails
Field NameStateData TypeDescription
addressMatchOptionalStringIndicates whether the Cardholder Shipping Address and the Cardholder Billing address are the same.
YShipping & billing addresses match
NShipping & billing addresses do not match
accountDetailsOptionalObjectSee the accountDetails table.
billingAddressMandatoryObjectSee the billingAddress table.
deliveryDetailsMandatoryObjectSee the deliveryDetails table.
browserDetailsConditionalObjectSee the browserDetails table.
emailConditionalString

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.

homePhoneConditionalString

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.

mobilePhoneConditionalString

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.

workPhoneConditionalString

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.

titleConditionalStringTitle prefixing the cardholders name e.g. Mr, Miss, Mrs
firstNameConditionalString

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.

lastNameConditionalString

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 NameStateData TypeDescription
accountAgeIndicatorOptionalString

Length of time that the cardholder has had the account with the merchant.

01No account (Guest checkout)
02Created during this transaction
03Less than 30 days
04Between 30 - 60 days
05More than 60 days
accountChangeDateOptionalDatetimeDate that the cardholders account with the merchant was last changed including billing or shipping address, new payment account or new user(s) added.
accountChangeIndicatorOptionalString

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.

01Changed during this transaction
02Less than 30 days
03Between 30 - 60 days
04More than 60 days
accountDateOptionalDatetimeDate that the cardholder opened the account with the merchant.
accountDayTransactionsOptionalInteger

Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous 24 hours.

accountIdOptional

String

Max. 64 Characters
Additional information about the account optionally provided by the merchant.
accountPasswordChangeDateOptionalDatetimeDate that cardholder’s account with the merchant had a password change or account reset.
accountPasswordChangeIndicatorOptionalString

Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset.

01No change
02Changed during this transaction
03Less than 30 days
04Between 30 - 60 days
05More than 60 days
accountProvisioningAttemptsOptionalIntegerNumber of “Add Card” attempts in the last 24 hours.
accountPurchaseCountOptionalIntegerNumber of purchases with this cardholder account during the previous six months.
accountTypeOptionalStringIndicates the type of account. For example, for a multi-account card product.
01Not applicable
02Credit
03Debit
accountYearTransactionsOptionalInteger

Number of transactions (successful and abandoned) for this cardholder account with the merchant across all payment accounts in the previous year.

paymentAccountAgeIndicatorOptionalStringIndicates the length of time that the payment account was enrolled in the cardholder’s account with the merchant.
01No account (Guest checkout)
02Created during this transaction
03Less than 30 days
04Between 30 - 60 days
05More than 60 days
paymentAccountDateOptionalDatetimeDate that the payment account was enrolled in the cardholder’s account with the merchant.
priorAuthenticationDataOptional

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.

priorAuthenticationMethodOptionalStringMechanism used by the Cardholder to previously authenticate to the merchant.
01Frictionless authentication occurred by ACS
02Cardholder challenge occurred by ACS
03AVS verified
04Other Issuer methods
priorAuthenticationReferenceOptionalString
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).
priorAuthenticationTimestampOptionalString
Length: 12 Characters
Date and time in UTC of the prior cardholder authentication.

Date format = YYYYMMDDHHMM
suspiciousAccountActivityOptionalStringIndicates whether the merchant has experienced suspicious activity (including previous fraud) on the cardholder account.
01No suspicious activity has been observed.
02Suspicious 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 NameStateData TypeDescription
titleConditionalString
Max 20 chars.
Cardholder's title.

If using Klarna, this field is Optional and is restricted to these values:
MrDesignates a Male cardholder.
MsDesignates a Female cardholder.
firstNameMandatoryString
Max 32 Char.
Cardholder's First Name
lastNameMandatoryString
Max 32 Char.
Cardholder's Surname or Last Name
addressLine1MandatoryString
Max 50 Char.
Address line 1 of the cardholders billing address.The house number passed here (numerics only) will be used in AVS checks.
addressLine2OptionalString
Max 50 Char.
Address line 2 of the cardholders billing address.
addressLine3OptionalString
Max 50 Char.
Address line 3 of the cardholders billing address.
postCodeMandatoryString
Max 13 Char.
Post code of the cardholders billing address.The house number passed here (numerics only) will be used in AVS checks.
cityConditionalString
Max 100 Char.
City of the cardholders billing address.

If using Klarna, this field is Mandatory.
regionOptionalString
Max 3 Char.
Region, state or province of the cardholder.
Format: ISO 3166-2
phoneOptionalStringCardholder's home phone number.

If using Klarna, this field is Mandatory.
countryMandatoryString
Max 2 Char.
ISO country code
Format: ISO 3166-1

customerDetails.deliveryDetails

payment Request > customer Details > deliveryDetails
Field NameStateData TypeDescription
deliveryAddressUsageDateOptionalDatetimeDate when the shipping address used for this transaction was first used with the 3DS Requestor.
deliveryAddressUsageIndicatorOptionalStringIndicates when the shipping address used for this transaction was first used with the 3DS Requestor.
01This transaction.
02Less than 30 days ago.
0330-60 days ago.
04More than 60 days ago.
deliveryEmailAddressOptionalString
Max 254 Chars.
For Electronic delivery, the email address to which the merchandise was delivered.
deliveryIndicatorOptionalStringIndicates 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.
01Ship to cardholder’s billing address.
02Ship to another merchant verified address.
03Ship to address that is different from billing.
04Ship to Store or local pick up. Store address should be used in shipping address fields.
05Digital goods.
06Travel and Event tickets not shipped.
07Other (e.g. Gaming, digital services, subs).
deliveryNameIndicatorOptionalStringIndicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
01Account name identical to shipping name.
02Account name different to shipping name.
deliveryTimeFrameMandatoryStringIndicates the merchandise delivery timeframe.
01Electronic Delivery.
02Same day shipping.
03Overnight shipping.
04Two-day or more shipping.
deliveryAddressMandatoryObjectSee 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 NameStateData TypeDescription
titleConditionalString
Max 20 chars.
Cardholder's title.

If using Klarna, this field is Optional and is restricted to these values:
MrDesignates a Male cardholder.
MsDesignates a Female cardholder.
firstNameMandatoryString
Max 32 Char.
Consumer's First Name
lastNameMandatoryString
Max 32 Char.
Consumer's Surname or Last Name
addressLine1MandatoryString
Max 50 Char.
Address line 1 of the consumers delivery address.
addressLine2OptionalString
Max 50 Char.
Address line 2 of the consumers delivery address.
addressLine3OptionalString
Max 50 Char.
Address line 3 of the consumers delivery address.
postCodeMandatoryString
Max 13 Char.
Post code of the cardholders billing address.The house number passed here (numerics only) will be used in AVS checks.
cityConditionalString
Max 100 Char.
City of the cardholders billing address.

If using Klarna, this field is Mandatory.
regionOptionalString
Max 3 Char.
Region, state or province of the consumer's delivery address.
Format: ISO 3166-2
phoneOptionalStringConsumer's home phone number.
countryMandatoryString
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 NameStateData TypeDescription
acceptHeaderMandatoryString
Max 2048 Chars.
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser.
challengeWindowSizeMandatoryString
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.
01250 x 40004600 x 400
02390 x 40005Full Screen
03500 x 600
javaEnabledMandatoryBooleanConfirms whether JavaScript is enabled in the consumer's browser.
trueJavaScript enabled.
falseJavaScript not enabled.
languageMandatoryString
Max 8 Chars.
Value representing the browser language as defined in IETF BCP47.
Returned from navigator.language property.
screenColorDepthMandatoryStringValue representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
11 bit.1616 bit.
44 bit.2424 bit.
88 bit.3232 bit.
1515 bit.4848 bit.
screenHeightMandatoryString
Max 6 Chars.
Total height of the Cardholder's screen in pixels.
Value is returned from the screen.height property.
screenWidthMandatoryString
Max 6 Chars.
Total width of the cardholder's screen in pixels.
Value is returned from the screen.width property.
timeZoneMandatoryString
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.
userAgentMandatoryString
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 NameStateData TypeDescription
nameConditionalStringDescriptive name of the order line item.

Mandatory if using Klarna.
quantityConditionalIntegerQuantity of the order line item.

Mandatory if using Klarna.
unitPriceConditionalIntegerPrice for a single unit of the order line. Includes tax.

Mandatory if using Klarna.
taxRateConditionalIntegerTax rate of the order line. The percentage value is represented with two implicit decimals. I.e 1900 = 19%

Mandatory if using Klarna.
totalAmountConditionalIntegerTotal price for the order line. Includes tax.

Mandatory if using Klarna.
totalTaxAmountConditionalIntegerTotal tax amount of the order line.

Mandatory if using Klarna.
imageUrlOptionalString
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.
productUrlOptionalString
Max 1024 Chars.
URL to the product in the merchant’s webshop that can be later used in communications between Klarna and the customer.
typeOptionalStringThe nature of the product being purchased. Must be one of the following values:
physicaldiscount
shipping_feesales_tax
digitalgift_card
store_creditsurcharge
referenceOptionalString
Max 64 Chars.
Client facing article number, SKU or similar.

amountBreakdown

payment Request > amountBreakdown
Field NameStateData TypeDescription
shippingOptionalObjectSee the shipping table.

Optional if using Klarna.
discountOptionalObjectSee the discount table.

Optional if using Klarna.

shipping

payment Request > amountBreakdown > shipping
Field NameStateData TypeDescription
totalAmountOptionalDecimalThe shipping amount as a sub total of the total amount. Only used in Klarna payments.

discount

payment Request > amountBreakdown > discount
Field NameStateData TypeDescription
totalAmountOptionalDecimalThe 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 NameStateData TypeDescription
recurringFrequencyConditionalStringIndicates the minimum number of days between individual authorizations. Mandatory only for recurring payments (instalments or subscriptions).
recurringExpirationDateConditionalString

Expiration date of the recurring transaction, mandatory for instalment payments.

Format: YYY-MM-DD

periodicTypeMandatoryStringType of periodic transaction.
ucofUnscheduled Credentials on File
numberOfInstalmentsConditionalStringNumber of instalments, mandatory for instalment payments.

orderDetails

paymentRequest > orderDetails
Field NameStateData TypeDescription
deviceChannelOptionalStringIndicates the type of channel interface being used to initiate the transaction.
01App-based (APP)
02Browser (BRW)
033DS Requester Initiated (3RI)

Default value 02

giftCardAmountOptionalInteger

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).

giftCardCountOptionalIntegerFor prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.
giftCardCurrencyIdOptionalStringFor prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.
preOrderDateOptionalDatetimeFor a pre-ordered purchase, the expected date that the merchandise will be available.
preOrderPurchaseIndicatorOptionalString

Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.

01Merchandise available
02Future availability
purchaseDateConditionalDatetimeDate and time of the purchase expressed in UTC.
reorderItemsIndicatorOptionalStringIndicates whether the cardholder is reordering previously purchased merchandise.
01First time ordered
02Reordered
transactionTypeConditionalStringIdentifies the type of transaction being authenticated.
01Goods/service purchase
03Check acceptance
10Account funding
11Quasi-Cash transaction
28Prepaid 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 NameStateData TypeDescription
merchantNameConditional

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.
visaMidConditionalStringMerchant 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.
mastercardMidConditionalStringMerchant 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.
amexMidConditionalStringMerchant 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.
merchantStoreIdOptionalIntegerId 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.
merchantDepartmentIdOptionalIntegerId 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.
merchantUrlConditionalStringMerchant URL used by the Payer Authentication process. Field is mandatory if processing Payer Authentication.
requestorAuthenticationDataOptional

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:

03then this element can carry information about the provider of the federated ID and related information.
06then this element can carry the FIDO attestation data (including the signature).
07then this element can carry FIDO Attestation data with the FIDO assurance data signed.
08then this element can carry the SRC assurance data.
requestorAuthenticationMethodOptionalStringMechanism used by the Cardholder to authenticate to the merchant.
01No 3DS Requestor authentication (e.g. guest).
02Login to the cardholder account at the 3DS Requestor system using 3DS Requestor system using 3DS Requestor’s own credentials.
03Login to the cardholder account at the 3DS Requestor system using federated ID.
04Login to the cardholder account at the 3DS Requestor system using issuer credentials.
05Login to the cardholder account at the 3DS Requestor system using third-party authentication.
06Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator.
07Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO assurance data signed).
08SRC Assurance Data.
requestorAuthenticationTimeStampOptionalDatetimeDate and time in UTC of the cardholder authentication.
Format: YYYYMMDDHHMM
scaExemptionIndicatorOptionalStringConfirms 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 NameStateData TypeDescription

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 NameData TypeDescription
access_tokenStringAccess token provided by the DNA platform for this transaction. The token should be securely stored ready to be used in the transaction request.
expires_inIntegerNumber 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_tokenStringReserved for future use.
scopeStringConfirmation of the scope passed in the authorisation request.
token_typeStringType of token issued
BearerBearer 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',
streetAddress1: '12 FulhamRd',
streetAddress2: '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.