Checkout PHP SDK Integration Guide

DNA Payments integration is based on REST API. A full description and additional information can be found here.

1. Installation

There are two types of the library installation:

Download from the GitHub repository
Install via Composer

Example: Install via Composer

composer require dna/dnapayments-sdk-php

2. Configuration

Create an instance of the class and set the settings.

Field	State	Type	Default Value	Description
isTestMode	Mandatory	Boolean	false	Allows the checking of test transactions processed during the development and test process.
scopes	Mandatory	Array	[]	Confirm scope of the action to be performed with credentials. allowHosted Full re-direct. allowEmbedded JavaScript Lightbox - content delivered via iFrame. allowSeamless JavaScript Lightbox - content hosted on merchant site.

note

Checkout currently supports three different operation modes when integrating directly, all of which are referred to individually within this document as “scope”. When developing, assert which scope you are using.

Example: Configuration
use DNAPayments\DNAPayments;

$dnaPaymentInstance = new DNAPayments(
    [
        'isTestMode' => false,
        'scopes' => [
            'allowHosted' => true
        ]
    ]
);

3. Authentication

Prior to attempting to process a transaction the host website must complete authentication with the DNA platform. This authentication is only valid for the transaction currently in progress and must be re-run before attempting the next.

Authentication request
Field Name	State	Data Type	Description
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.
terminal	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. This ID must be unique for this transaction.
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.
currency	Mandatory	String	Currency of the transaction. GBP Pound Sterling
paymentFormURL	Optional	String	You need to specify the address of the site or page where the payment form will be located if JavaScript Lightbox is used.

Example: Authentication
use DNAPayments\Util\RequestException;

try {
    $token = $dnaPaymentInstance->auth([
        'client_id' => 'Your client ID',
        'client_secret' => 'Your client secret',
        'terminal' => 'Your terminal ID',
        'invoiceId' => 'Example123',
        'currency' => 'GBP',
        'amount' => 123
    ]);
} catch (RequestException $e) {
    echo 'Caught exception: ',  $e->getMessage(), "\n";
} catch (Exception $e) {
    echo 'Caught exception: ',  $e->getMessage(), "\n";
}

4. Initiate payment

4.1 Full re-direct

The consumer is redirected to the Checkout payment page hosted by DNA Payments. As this is a full re-direct the consumer will leave the merchant site whilst the payment is being made and re-directed back once complete. Using this method ensures that the merchant site has no visibility of any card data as all sensitive data is entered on the hosted page.

When implementing the Full Redirect payment form, you need to get a token according to the order data, generate a URL and a redirect for it.

There are 2 ways to generate a link:

Front-end with JS-library
Back-end with PHP SDK library

4.1.1 Generate link with JS-library

4.1.1.1 Generate token

There are 2 ways to generate a token:

Create an endpoint, which will return a token
Generate a token when the page is opened

4.1.1.2 Include the DNA Payments JS-library

Add the following code to the head part of your webpage (this URL is subject to change). The URL is a script for creating Payment form on your webpage.

<script type="text/javascript" src="https://pay.dnapayments.com/checkout/payment-api.js"></script>

4.1.1.3 Configure payment form module

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
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 against the 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.

window.addEventListener('load', function() {
    window.DNAPayments.configure({
        isTestMode: true
    })
})

4.1.1.4 Provide payment form module

On the host website’s ‘Checkout’ page (the button where the consumer is provided with the option to pay) a JS-library link is required to be added with the method window.DNAPayments.openPaymentPage() chosen.

Within the window.DNAPayments.openPaymentPage() method the “Payment Request” parameters need to be supplied. The list and description of the fields can be found here.

document.querySelector('.open-page-btn').onclick = function () {
    window.DNAPayments.openPaymentPage({
        'postLink': 'https://example.com',
        'failurePostLink': 'https://example.com',
        'backLink': 'https://example.com',
        'failureBackLink': 'https://example.com',
        'description': 'Car Service',
        'terminal': 'Your terminal ID',
        'invoiceId': 'example123',
        'currency': 'GBP',
        'amount': 123,
        'accountId': 'uuid000001',
        'accountCountry': 'GB',
        'accountCity': 'London',
        'accountStreet1': 'Fulham Rd',
        'accountEmail': 'demo@dnapayments.com',
        'accountFirstName': 'John',
        'accountLastName': 'Doe',
        'accountPostalCode': 'SW6 1HS',
        'language': 'EN',
        auth
    })
}

4.1.2 Generate link with PHP SDK library

4.1.2.1 Generate token

You need to create an endpoint, which you will use to get a token and generate a link to redirect to. The list and description of the fields can be found here.

note

In this case, you don't need to use JS-library.

public function generateUrl() {
    $token = $dnaPaymentInstance->auth($authData);
    return $dnaPaymentInstance->generateUrl([
        'postLink' => 'https://example.com',
        'failurePostLink' => 'https://example.com',
        'backLink' => 'https://example.com',
        'failureBackLink' => 'https://example.com',
        'description' => 'Car Service',
        'terminal' => 'Your terminal ID',
        'invoiceId' => 'example123',
        'currency' => 'GBP',
        'amount' => 123,
        'accountId' => 'uuid000001',
        'accountCountry' => 'GB',
        'accountCity' => 'London',
        'accountStreet1' => 'Fulham Rd',
        'accountEmail' => 'demo@dnapayments.com',
        'accountFirstName' => 'John',
        'accountLastName' => 'Doe',
        'accountPostalCode' => 'SW6 1HS',
        'language' => 'EN'
    ], $token);
}

5. Handle payment result

The full description can be found here

6. Transaction management

To provide integrators with maximum flexibility when using the Checkout solution several transaction functions can be requested after the transaction has been completed. These functions do not rely on the consumer being present as all consumer interaction has been completed at this point.

Other than the Authentication request all functions require the “id” (the unique transaction ID generated returned in the Payment result message) to be present as a minimum.

6.1 Transaction settlement

info

Transaction settlement can only be performed when a transaction has been completed as an authorisation only and is in a AUTH state. In this state the funds have been reserved but not yet sent for settlement. Any attempts to perform settlement on a transaction not in this state will be rejected.

The transaction settlement is usually utilised by merchants who wish to authorise when the consumer is present on Checkout but only charge when the goods are shipped. This allows for the final amount charged to the consumer to accurately reflect the value of goods that have been sent to them. This is seen as a preferential process than charging the customer the full amount up front and then having to perform a refund using the token Id as a separate transaction

Transactions can only be charged/sent for settlement successfully once.

info

Authorisation codes issued during the authorisation process have a limited lifespan. Unfortunately, there are no clear rules as to the validity period, but this is typically anything between three and ten days depending on the card issuer. There is also no way for the validity to be checked.

It is recommended that if there is expected to be a significant delay in the charge process a transaction reversal is performed against the original authorisation and the transaction processed when the goods are available using the token Id gained in the initial transaction.

Example: Transaction settlement request
try {
    $result = $dnaPaymentInstance->charge([
        'client_id' => 'Your client ID',
        'client_secret' => 'Your client secret',
        'terminal' => 'Your terminal ID',
        'invoiceId' => 'example123',
        'amount' => 123,
        'currency' => 'GBP',
        'transaction_id' => '1234-1234-1234-1234'
    ]);
    if( !empty($result) && $result['success'] ) {
        // Do something 
        return true;
    }
} catch (Exception $e) {
    echo 'Caught exception: ',  $e->getMessage(), "\n";
    return false;
}

6.2 Transaction reversal

info

Transaction reversal can only be performed when a transaction has been completed as an authorisation only and is in an AUTH state. In this state the funds have been reserved but not yet sent for settlement. Any attempts to perform settlement on a transaction not in this state will be rejected.

The transaction reversal function is a companion to the transaction settlement request, in that it is also used for merchants who wish to manage their transactions as a two-step process. Where the transaction settlement request allows the merchant to complete the transaction and claim the funds the transaction reversal request allows the merchant to cancel the authorisation in place and return the available balance to the consumers card.

This is most likely to be used in scenarios where the merchant has discovered that they are unable to fulfil the order as planned, for example when items ordered have gone permanently out of stock.

Authorisation codes issued but not charged/settled will automatically expire but it is best practice to reverse where possible - thus giving the consumer back the amount into their available balance sooner.

Example: Transaction reversal request
try {
    $result = $dnaPaymentInstance->cancel([
        'client_id' => 'Your client ID',
        'client_secret' => 'Your client secret',
        'terminal' => 'Your terminal ID',
        'invoiceId' => 'example123',
        'amount' => 123,
        'currency' => 'GBP',
        'transaction_id' => '1234-1234-1234-1234'
    ]);
    if( !empty($result) && $result['success'] ) {
        // Do something 
        return true;
    }
} catch (Exception $e) {
    echo 'Caught exception: ',  $e->getMessage(), "\n";
    return false;
}

6.3 Transaction refund

info

Transaction refund can only be performed when a transaction has been charged/settled and is in a CHARGE state. Any transaction which is not yet settled/charged should be cancelled via the transaction reversal function.

Merchant’s will encounter scenario where they are required to refund a consumer, either for the full transaction amount (in the case of a return of goods) or in some cases for a reduced amount (such as a gesture of goodwill for issues experienced).

To simplify the process Checkout has introduced the ability for a merchant to perform a refund against the transaction Id, removing the requirement to store the consumers token id. The refund request can be for any value up to the value of the original transaction.

Example: Transaction refund request
try {
    $result = $dnaPaymentInstance->refund([
        'client_id' => 'Your client ID',
        'client_secret' => 'Your client secret',
        'terminal' => 'Your terminal ID',
        'invoiceId' => 'example123',
        'amount' => 123,
        'currency' => 'GBP',
        'transaction_id' => '1234-1234-1234-1234'
    ]);
    if( !empty($result) && $result['success'] ) {
        // Do something 
        return true;
    }
} catch (Exception $e) {
    echo 'Caught exception: ',  $e->getMessage(), "\n";
    return false;
}

1. Installation​

2. Configuration​

3. Authentication​

4. Initiate payment​

4.1 Full re-direct​

4.1.1 Generate link with JS-library​

4.1.1.1 Generate token​

4.1.1.2 Include the DNA Payments JS-library​

4.1.1.3 Configure payment form module​

4.1.1.4 Provide payment form module​

4.1.2 Generate link with PHP SDK library​

4.1.2.1 Generate token​

5. Handle payment result​

6. Transaction management​

6.1 Transaction settlement​

6.2 Transaction reversal​

6.3 Transaction refund​

1. Installation

2. Configuration

3. Authentication

4. Initiate payment

4.1 Full re-direct

4.1.1 Generate link with JS-library

4.1.1.1 Generate token

4.1.1.2 Include the DNA Payments JS-library

4.1.1.3 Configure payment form module

4.1.1.4 Provide payment form module

4.1.2 Generate link with PHP SDK library

4.1.2.1 Generate token

5. Handle payment result

6. Transaction management

6.1 Transaction settlement

6.2 Transaction reversal

6.3 Transaction refund