Widget Integration

Widget Example

Using the widget implementation, you can embed our provided payment method selection onto the merchant’s checkout page, as shown here

This integration is made up of three main stages:

  1. Create the HTML Element
  2. Configure Widget (Optional)
  3. Add Function

Create the HTML Element

Create a div element (HTML) on the host website's 'Checkout' page, in the position where you wish to render the block. Then, assign a default ID dna-embedded-widget-container or use your own:

<div id="dna-embedded-widget-container"></div>

The CSS class name can also be used as the ID:

<div class="customClassName"></div>

Configure Widget (Optional)

Configuration can optionally be supplied in two objects within the window.DNAPayments.configure() method, choosing one of the widgetTypes. The example below uses hosted.

Embedded Widget
embeddedWidget: {
container: '.customClassName',
widgetType: 'HOSTED',
maxVisiblePaymentMethods: 5,
orderButtonText: 'Order and Pay'
paymentMethods: [
name: window.DNAPayments.paymentMethods.BankCard,
message: 'NO FEE'
name: window.DNAPayments.paymentMethods.PayPal,
message: 'NO FEE'

If these settings are not supplied the values configured on the platform are used. Configuration provided using the window.DNAPayments.configure() method are given priority over the values configured on the platform.

Configuration Options

A full breakdown of the configuration options are shown below.


Field NameStateData TypeDescription
isTestModeOptionalBooleanFlag 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.
isEnableDonationOptionalBooleanControls 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.


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.

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.


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


A maximum of four cards can be passed to Checkout.


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.


Best Practice - Usage Guidelines

This optional array allows you to exclude specific card schemes on a per-transaction basis. You might want to set a minimum value for Amex to be 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
Field NameStateData TypeDescription
nameOptionalstringName of the payment method. Possible values are shown below.
messageOptionalstringOptional information regarding additional processing fees. Defaults to “NO FEE”.

Example Configuration

<div id="dna-embedded-widget-container"></div>
isTestMode: true,
isEnableDonation: true,
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: () => {
console.log('Transaction successful')
declined: () => {
console.log('Transaction declined')
embeddedWidget: {
container: '#dna-embedded-widget-container',
widgetType: 'SEAMLESS' | 'EMBEDDED' | '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
disabledCardSchemes: [
cardSchemeId: 1,
cardSchemeName: 'Amex'
cardSchemeId: 11,
cardSchemeName: 'Visa'
window.addEventListener("load", function(){
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'


For test transactions the URL below should be used

Add Function

To manage the starting of the transaction the method window.DNAPayments.openPaymentIframeWidget() is used. Within the window.DNAPayments.openPaymentIframeWidget() the payment request parameters need to be supplied.

This function will automatically receive the configuration stored on the platform (if not provided) and render the widget. You may however want to use transaction specific Payment Request settings, such as when supplying extended cardholder information for 3DS2, or payment details for Klarna payments.

Next Steps

To continue your Widget integration, please go to the Payment Request section if you are sending transaction specific data. This will provide guidance on the extended settings you can set, in addition to the truncated example above.

If you have completed this, or are able to rely on the configuration stored on the platform, then you can proceed straight to interpreting the Payment Result.

transaction specific data

This will be required if you are using 3D Secure V2 for Ecommerce, or for many of our Additional Payment Methods. You can find more information on their required Payment Request fields here