Checkout PHP SDK Integration Guide
DNA Payments integration is based on REST API. A full description and additional information can be found here.
There are two types of the library installation:
- Download from the GitHub repository
- Install via Composer
Create an instance of the class and set the settings.
|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.|
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.
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.
|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.|
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
184.108.40.206 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
220.127.116.11 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.
18.104.22.168 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.
|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.|
22.214.171.124 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() method the “Payment Request” parameters need to be supplied. The list and description of the fields can be found here.
4.1.2 Generate link with PHP SDK library
126.96.36.199 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.
In this case, you don't need to use JS-library.
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
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.
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.
6.2 Transaction reversal
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.
6.3 Transaction refund
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.