Configuration

In order to provide configuration at the same time as initiating the payment the following JS function must be used window.DNAPayments.configure();

Configuration Options

A full breakdown of the configuration options are shown below.

Configuration

Configuration
Field NameStateData TypeDescription
isTestModeOptionalBoolean

Flag which provides the merchant with the ability to process a transaction in test mode. This must always be set to true when processing aginst the PPE Test Platform.

trueTransaction will be processed as a test transaction; No live funds will be reserved
falseTransaction will be processed to the live platform and funds will be reserved.
isEnableDonationOptionalBoolean

Controls whether the consumer is offered the ability to make a charitable donation.

trueCharitable donation will be offered.
falseCharitable donation will not be offered.

This setting is only used if the merchant configuration is configured to allow charitable donations. If this setting is not provided the platform configuration is used, if both are present the configuration here takes precedence.

autoRedirectDelayInMsOptionalDecimal

The number of milliseconds that the Payment Result screen will be displayed to the consumer prior to them being redirected back to the host site. If this value is passed as “0” the screen will not be displayed.

The default value for this setting is 30000 (30 seconds)

Configuration.events

Callback Events

The events field that is passed in an object as an argument of the configure method is responsible for callbacks that are called at a certain point based on the type of fired events in the lifecycle of the payment form, which have the ability to change its behaviour. You will still receive full Payment Result information to your back-end system as specified in PaymentSettings, but these events will allow you to run your own code in your front-end.

Configuration > events
Field NameStateData TypeDescription
openedOptionalStringA callback function that is called when the payment form is opened.
cancelledOptionalStringA callback function that is called when the form is closed without payment attempts.
paidOptionalString

A callback function that is called after a successful payment.

It is recommended to call a function that is provided by the library - closePaymentWidget method, which closes the payment form and cancels all subscriptions and resets the state to the initial form. If it is not called, the form will show the success page and redirect to the specified backLink or returnUrl.

declinedOptionalString

A callback function that is called after the specified unsuccessful payment attempts count or after closing the payment form with at least one unsuccessful payment attempt.

It is recommended to call a function that is provided by the library - closePaymentWidget method, which closes the payment form and cancels all subscriptions and resets the state to the initial form. If it is not called, the form will show the success page and redirect to the specified backLink or returnUrl.

Configuration.embdeddedWidget

Configuration > embeddedWidget
Field NameStateData TypeDescription
containerOptionalStringID of the container selector where the block will be rendered. Default is dna-embedded-widget-container
orderButtonTextOptionalStringText used on the button used to start the payment process. Default is “Order and Pay”.
widgetTypeOptionalStringIntegration type used by the solution for the transaction
SeamlessJavaScript Lightbox - content hosted on merchant site.
EmbeddedJavaScript Lightbox - content delivered via iFrame.
HostedFull page re-direct.
If no value is supplied the full page re-direct Hosted type will be used.
maxVisiblePaymentMethodsOptionalDecimal

Maximum visible payment methods in the embedded widget, other items will be hidden.

Default is null (shows all APMs).

Stored Cards - Token Wallet

Checkout offers the merchant the option to pass several token Ids (representing cards previously used by the consumer) in the request, giving the consumer the choice to select a card for their ‘wallet’. The consumer does also have the chance to enter a new card if required.

caution

A maximum of four cards can be passed to Checkout.

Configuration.cards

Configuration > cards
Field NameStateData TypeDescription
merchantTokenIdMandatoryStringToken representing the card which is to be offered to the consumer in the token wallet. This is the token registered using any of our consistent token compatible solutions.
panStarMandatoryStringThe masked PAN as it will appear when presented to the consumer. This must be passed as it was received when the token was registered.
cardSchemeIdMandatoryStringCard scheme Id for the card represented by the token. This Id will need to have been stored from the request where the token was registered.
cardNameMandatoryStringA ‘friendly name’ given to the card to allow the consumer to identify which card to use easily.
expiryDateMandatoryStringCards expiration date - must be supplied in the MMYY format. Another item used to help make the consumers identification process as easy as possible.
isCSCRequiredOptionalBooleanInforms Checkout whether the CSC should be captured and validated as part of the transaction in the event the card is chosen by the consumer.
trueConsumer will be requested to enter the CSC.
falseConsumer will not be requested to enter the CSC.
useStoredBillingDataOptionalBooleanInforms Checkout whether previously supplied billing data, e.g. Cardholder Name, should be re-used for this card.
trueUse the previously supplied Billing Data
falseDo not use the previously supplied Billing Data
If not supplied, Checkout will prompt for the data where required.

Configuration.disabledCardSchemes

Best Practice - Usage Guidelines

This optional array allows you to exclude specific card schemes on a per-transaction basis.

For example, you might want to set a minimum value before Amex is allowed, or prevent the use of credit cards for some products.

Configuration >disabledCardSchemes
Field NameStateData TypeDescription
cardSchemeIdOptionalIntegerThe ID of the Card Scheme being disabled. See Scheme ID's for more details.
cardSchemeNameOptionalstringThe Name of the Card Scheme being disabled. See Scheme ID's for more details.

You can specify multiple Card Schemes simply by detailing additional objects in this array, see Example Configuration for more details.

Configuration.paymentMethods

Configuration >paymentMethods
Field NameStateData TypeDescription
nameOptionalstringName of the payment method. Possible values are shown below.
window.DNAPayments.paymentmethods.BankCardCard
window.DNAPayments.paymentmethods.PayPalPayPal
messageOptionalstringOptional information regarding additional processing fees. Defaults to “NO FEE”.

Example Configuration

<div id="dna-embedded-widget-container"></div>
window.DNAPayments.configure({
isTestMode: true,
isEnableDonation: true,
autoRedirectDelayInMs: 10000,
paymentMethods: [
{
name: window.DNAPayments.paymentMethods.BankCard
},
{
name: window.DNAPayments.paymentMethods.PayPal,
message: 'NO FEE'
}
],
events: {
opened: () => {
console.log('Checkout opened')
},
cancelled: () => {
console.log('Transaction cancelled')
},
paid: () => {
window.DNAPayments.closePaymentWidget()
console.log('Transaction successful')
},
declined: () => {
console.log('Transaction declined')
window.DNAPayments.closePaymentWidget()
}
}
embeddedWidget: {
container: '#dna-embedded-widget-container',
widgetType: 'HOSTED',
maxVisiblePaymentMethods: 5,
orderButtonText: 'Order and Pay'
},
cards: [
{
merchantTokenId: 'PDHGFJW42bDuWa/fP/KlsRmKWM5ST7PXF/gPlCECfbLNcYZ==',
panStar: '**** **** **** 2234',
cardSchemeId: '1',
cardName: 'AMEX Example Only',
expiryDate: '01/20',
isCSCRequired: true,
useStoredBillingData: true
}
]
})
window.addEventListener("load", function(){
window.DNAPayments.openEmbeddedWidget({
invoiceId: "Order123456",
amount: 12.83,
currency: "GBP",
description: "Order payment",
paymentSettings: {
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',
terminalId: 'TerminalID'
},
customerDetails: {
accountDetails: {
accountId: 'testuser'
},
billingAddress: {
firstName: 'Paul',
lastName: 'Smith',
addressLine1: '14 Tottenham Court Road',
postalCode: 'W1T 1JY',
city: 'London',
country: 'GB'
},
email: 'test@test.com'
},
auth: {
access_token: 'qy/ZWj049WHUZj+8i1pUwmYxswo4GXK+Z5',
expires_in: 7200,
scope: 'payment integration_seamless',
token_type: 'Bearer'
}
})
})
})

Testing

For test transactions the URL below should be used