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

Field Name

State

Data Type

Description

isTestMode

Optional

Boolean

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.

true	Transaction will be processed as a test transaction; No live funds will be reserved
false	Transaction will be processed to the live platform and funds will be reserved.

isEnableDonation

Optional

Boolean

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

true	Charitable donation will be offered.
false	Charitable 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.

autoRedirectDelayInMs

Optional

Decimal

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)

paymentTimeoutInSeconds

Optional

Integer

The payment form displays the number of seconds left available to the cardholder when the last 60 seconds have been reached. When it is reached, the cardholder is presented with a dialogue box to close.
This will either reject (if a payment was attempted) or close (if no payment was attempted) the payment attempt.

The default value is 20 minutes = 1200

You can use this field to set a different timeout value if desired.

The timeout only affects Card payments, not any Additional Payment Methods.

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 Name	State	Data Type	Description
opened	Optional	String	A callback function that is called when the payment form is opened.
cancelled	Optional	String	A callback function that is called when the form is closed without payment attempts.
paid	Optional	String	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.
declined	Optional	String	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 Name

State

Data Type

Description

container

Optional

String

ID of the container selector where the block will be rendered. Default is dna-embedded-widget-container

orderButtonText

Optional

String

Text used on the button used to start the payment process. Default is “Order and Pay”.

widgetType

Optional

String

Integration type used by the solution for the transaction

Seamless	JavaScript Lightbox - content hosted on merchant site.
Embedded	JavaScript Lightbox - content delivered via iFrame.
Hosted	Full page re-direct.

If no value is supplied the full page re-direct Hosted type will be used.

maxVisiblePaymentMethods

Optional

Decimal

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 Name

State

Data Type

Description

merchantTokenId

Mandatory

String

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

panStar

Mandatory

String

The masked PAN as it will appear when presented to the consumer. This must be passed as it was received when the token was registered.

cardSchemeId

Mandatory

String

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

cardName

Mandatory

String

A ‘friendly name’ given to the card to allow the consumer to identify which card to use easily.

expiryDate

Mandatory

String

Cards expiration date - must be supplied in the MMYY format. Another item used to help make the consumers identification process as easy as possible.

isCSCRequired

Optional

Boolean

Informs Checkout whether the CSC should be captured and validated as part of the transaction in the event the card is chosen by the consumer.

true	Consumer will be requested to enter the CSC.
false	Consumer will not be requested to enter the CSC.

useStoredBillingData

Optional

Boolean

Informs Checkout whether previously supplied billing data, e.g. Cardholder Name, should be re-used for this card.

true	Use the previously supplied Billing Data
false	Do 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 Name	State	Data Type	Description
cardSchemeId	Optional	Integer	The ID of the Card Scheme being disabled. See Scheme ID's for more details.
cardSchemeName	Optional	string	The 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 Name

State

Data Type

Description

name

Optional

string

Name of the payment method. Possible values are shown below.

window.DNAPayments.paymentmethods.BankCard

window.DNAPayments.paymentmethods.GooglePay

window.DNAPayments.paymentmethods.ApplePay

window.DNAPayments.paymentmethods.PayByBank

window.DNAPayments.paymentmethods.PayPal

window.DNAPayments.paymentmethods.EcoSpend

window.DNAPayments.paymentmethods.Klarna

message

Optional

string

Optional 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

URL

https://test-pay.dnapayments.com/checkout/payment-api.js

Configuration Options​

Configuration​

Configuration.events​

Configuration.embdeddedWidget​

Stored Cards - Token Wallet​

Configuration.cards​

Configuration.disabledCardSchemes​

Configuration.paymentMethods​

Example Configuration​

Testing​

Configuration Options

Configuration

Configuration.events

Configuration.embdeddedWidget

Stored Cards - Token Wallet

Configuration.cards

Configuration.disabledCardSchemes

Configuration.paymentMethods

Example Configuration

Testing