Authentication

Prior to attempting to process a transaction the host website must complete authentication with the DNA platform. The authentication process is unique for each transaction and utilises the test account credentials which are supplied following the configuration of the merchant test account, namely;

• TerminalID
• ClientID
• ClientSecret

Authentication POST - Request

Authentication is completed via a POST request to the URLs shown below.

URL

TEST: https://test-oauth.dnapayments.com/oauth2/token

LIVE: https://oauth.dnapayments.com/oauth2/token

Security Risk

The “client_secret” must always be stored securely. Do not send authorisation requests from the front-end as the user could access the data via the web browser’s console.

The POST must contain the below data.

Method:	POST
Request Body Format (Content-Type):	application/x-www-form-urlencoded or form-data

Authentication Request
Field Name	State	Data Type	Description
grant_type	Mandatory	String	Authorisation type required to confirm the action required. client_credentials Obtain credentials required to process a transaction.
scope	Mandatory	String	Confirm scope of the action to be performed with credentials. payment integration_hosted Full re-direct. payment integration_embedded JavaScript Lightbox - content delivered via iFrame. payment integration_seamless JavaScript Lightbox - content hosted on merchant site. webapi Transaction management. payment integration_seamless must be used if you are using our Hosted Fields solution.
client_id	Mandatory	String	Provided to the integrator following the successful creation of a test account.
client_secret	Mandatory	String	Provided to the integrator following the successful creation of a test account.
invoiceId	Mandatory	String	Order/invoice/transaction/basket number generated by the host website. By default, this ID must be unique for each transaction and must match the "invoiceId" field in the Payment Request unless the integrator account is configured to allow authentication token re-use. We recommend simply generating a UUID/GUID. This field may not be required when the integrator account is configured to allow the re-use of authentication tokens. This value must not contain any Personally Identifiable Information such as a vehicle registration number or cardholder name. See the warning below for more details.
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. By default, this field must match the "amount" field in the Payment Request unless the integrator account is configured to allow authentication token re-use. This field may not be required when the integrator account is configured to allow the re-use of authentication tokens.
currency	Mandatory	String	Currency of the transaction. GBP Pound Sterling By default, this field must match the "currency" field in the Payment Request unless the integrator account is configured to allow authentication token re-use. This field may not be required when the integrator account is configured to allow the re-use of authentication tokens.
terminal	Mandatory	String	Provided to the integrator following the successful creation of a test account. By default, this field must match the "paymentSettings" -> "terminalId" field in the Payment Request unless the integrator account is configured to allow authentication token re-use. This field may not be required when the integrator account is configured to allow the re-use of authentication tokens.

caution

If using Apple Pay in a Lightbox, you will need to register the URL of your website with us. Apple Pay requires all websites to be whitelisted and the Lightbox prevents our own whitelisting from being considered. See guide for more information.

Authentication POST - Response

Following the receipt of a correctly formatted authorisation POST the DNA platform will respond with the below.

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(s) passed in the authorisation request.
token_type	String	Type of token issued Bearer Bearer token

Example Request and Response

Request

Example: Authentication Request (NodeJs)

var request = require("request");

var options = {
    method: 'POST',
    url: 'https://test-oauth.dnapayments.com/oauth2/token',
    formData:
    {
        scope: 'payment integration_hosted',
        client_id: 'ExampleShop',
        client_secret: 'mFE454mEF6kmGb4CDDeN6DaCnmQPf4KLaF59GdqwP',
        grant_type: 'client_credentials',
        invoiceId: '1234567',
        amount: '1',
        currency: 'GBP',
        terminal: 'b95c9d1f-132f-4e04-92d2-32335c7486ea'
    }
};
request(options, function (error, response, body)
{
    if (error) throw new Error(error);
    console.log(body);
});

Response

Example: Authentication Response

{
  "access_token":"qy/ZWj049WHUZj+8i1pUwmYxswo4GXK+Z5",
  "expires_in": 7200,
  "refresh_token":"",
  "scope":"payment integration_hosted",
  "token_type":"Bearer"
}

The Response you receive is passed in almost verbatim, later in the Apple Pay Direct process.