You've chosen Hosted Checkout

Quickly configure your checkout page to securely accept payments.

Pre-built hosted page readily available to integrate with your online website or mobile applications.

Introduction

Hosted Checkout is a proprietary JavaScript SDK from TNS, designed to provide merchants with an iframe for seamless integration into their ecommerce websites. This integration facilitates secure online payments while keeping sensitive payment data out of the merchant's server. Rather than entering card data directly on the merchant's website, TNS handles the card data, enhancing security and compliance.

How it works

Hosted Checkout integration involves two parts: server-side integration and client-side integration. In the client-side integration, you specify non-editable <div> elements for payment information in your checkout flow, maintaining your UI's look and feel. Our SDK then replaces these with a secure iframe that captures card data. When our SDK is called from your client, the card data is sent to our servers, transactions are processed and transient tokens are issued.

The server-side integration is needed to authenticate your session. You can also use tokens issued by TNS to execute transactions.

  • Start Checkout
    1

    When the customer is ready to pay or clicks the checkout button, the merchant's online application requests the checkout page from its server.

  • Create Session
    2

    The merchant's server initiates a secure session from the hosted checkout server, specifying the type of payment transaction, display configurations, and merchant credentials, all secured by signing the request with HMAC. This session is then utilized by the online application. See Create Session for more details.

  • Checkout Page
    3

    The merchant's server sends the checkout page with the payment form to the online application.

  • Initialize Hosted Checkout
    4

    The merchant's online application initializes Hosted Checkout with the specified initialization parameters. See Initialization Parameters and Callbacks for more details.

  • Hosted Checkout Iframe
    5

    Once initialized, the Hosted Checkout SDK replaces the payment form linked to the specified container ID with a Hosted Checkout Iframe that contains elements for capturing payment data.

  • Submit Transaction
    6

    The customer enters payment card details into the iframe and clicks Pay button. Hosted Checkout collects card information, processes the transaction and sends the results back to the online application via callbacks.

  • 7 & 8. Process Transaction Response
    7

    The transaction response received for the transactions, which will contain the transaction identifier that can be used for secondary transactions like void, capture and refunds. See Secondary Transactions for more information.

What we offer

Pre-built payment form to embed into your checkout flow
Address verification
Google Pay, Apple Pay, PayPal
Built-in validation of payment fields
Simple integration with online web application and mobile application

Using our SDK, you can integrate a payment form in just two steps and begin accepting payments in your online or mobile application.

Step 1

Create Hosted Checkout session

When utilizing our Hosted Checkout system, initiate a session and embed our scripts on your webpage. Subsequently, our iframe will automatically render. The initial step involves creating a session. For illustrative purposes, we will showcase this process using our test credentials in the demonstration environment to offer a fundamental example. Please refer to the following cURL request to commence a session. For more information on the request fields or to see the cURL request in multiple languages, see Create Session Request section of our documentation.

This curl request example contains the minimum mandatory fields required to get a successful session.

                                                

                                                

                                                
                                                

                                                    
                                                    Run in API Explorer

We have successfully generated our session ID, which will remain active for a period of up to 15 minutes. During the course of this initial implementation, should you require a new session ID, please revisit this page and execute the request once more. Jump to step 2

Response for the session request.

                                                    

                                                        RESPONSE
                                                    

                                                    
201 Created
{
    "sessionId": "cf896190-32fb-44d5-819e-7f9eb0ec8f2f"
}

The mandatory fields of the session request are listed in the below table. For information on complete fields list including mandatory and optional fields, see Session Fields and Configurations section of our documentation.

Field Description Type Example

sessionMode
Required

Specifies the purpose of the requested session. This value is formatted as a string, and the allowed enum values are listed below.

PERFORM_TRANSACTION Perform a payment transaction and generate a token for the card number.
CREATE_TOKEN Generate a token for the card number without running a payment transaction.
PERFORM_TOKEN_TRANSACTION Perform a payment transaction with the token instead of the card number.
UPDATE_TOKEN Update the token information.
string PERFORM_TRANSACTION

transactionType
Required

Specifies what transaction will be performed. The value is formatted as a string, and the allowed enum values are listed below.

PAYMENT A sale transaction involves both authorization and capture of funds simultaneously, commonly utilized by merchants who provide goods instantly, such as retail stores where customers receive their purchases immediately.
PRE_AUTH An authorization transaction involves verifying the card's validity and ensuring sufficient funds in the cardholder's account without transferring funds. To complete the transfer from the cardholder to the merchant, the approved transaction must be captured. Merchants commonly use authorization transactions when goods are delivered post-purchase.
ACCOUNT_VERIFICATION Zero-value account verification enables merchants to check the status of an account and its validity without impacting their open-to-buy limit.
string PRE_AUTH

transactionInitiator
Required

Specifies who initiated the transaction. The value is formatted as string, and the allowed enum values are listed below. The default value is CARDHOLDER.

CARDHOLDER The cardholder is accessing the checkout page and will use Hosted Checkout directly for the payment.
MERCHANT The merchant is requesting this session to process a transaction on behalf of the cardholder.
string CARDHOLDER

transactionMode
Required

This specifies whether the transaction is an ECOMMERCE or MOTO (Mail Order/Telephone Order) transaction. The value is formatted as a string, and the allowed enum values are listed below. The default value is ECOMMERCE.

ECOMMERCE The Hosted Checkout page is being requested to process an online transaction as part of the checkout process on the merchant's website or from their mobile application.
MOTO The Hosted Checkout page is being requested to process a mail order or telephone order transaction.
string ECOMMERCE

merchantId
Required

TNS provided unique merchant identifier.

string 102606

order
Required

This outlines the specifics of an order comprising one or more line items. Each line item includes details such as its name, description, quantity, and cost. It is mandatory to include at least one line item. Additionally, the subtotal, country, and currency fields must be included as they are integral parts of the order details.

Field Description Example Value
lineItemList
Required
Field Description Example Value
lineItem
Required 		A string representing the name or identifier of the line item. This field can be used for name or stock keeping unit(SKU) of the item. 4409
lineItemDescription
Required 		A string providing a description of the line item. Sun Glasses
quantity
Required 		An integer indicating the quantity of the line item being ordered. 2
lineItemCost
Required 		Total line item amount, excluding taxes and fees, in the designated currency and transmitted as a string. The amount should be in decimal format, such as “10.12” for a transaction totaling $10.12. 125.00
country
Required 		This is the ISO 3166-2 country code. Use “AU” for Australia, “US” for United States, “GB” for United Kingdom. Please refer https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes for list of all country codes. US
currency
Required 		This is the ISO 4217 currency code. Use "AUD" for Australian dollar, "USD" for United States dollar, "GBP" for Pound sterling. Please refer https://en.wikipedia.org/wiki/ISO_421 for list of all currency codes. USD
subtotal
Required 		This is the sum of all total costs of the items, before any taxes and fees in the designated currency and transmitted as a string. The amount should be in decimal format, such as “10.12” for a transaction totaling $10.12. 250.00

cardBrands
Required

Supported card types during the checkout session must be specified by the user. It is essential to indicate the accepted card brands during the checkout process. Failure to include at least one brand will result in no cards being accepted.

Field Description Example Value
card
Required 		Card brand information must be provided to ensure that Hosted Checkout can process payments for the specified card brand during the checkout process. VISA

For information on the complete list of fields for a session request, see Session Fields and Configurations section of our documentation.

Step 2

Create a sample HTML page to embed the Hosted Checkout Iframe

Now we need to create a basic HTML page to embed our checkout iframe. This involves incorporating script references and a '<div>' element to showcase the iframe. Let's proceed by creating an HTML page titled index.html. Subsequently, let's insert the specified script references within the '<head>' segment of our page. It is imperative to substitute [YOUR_SESSION_ID] with the session ID obtained from the API request mentioned earlier. The containerId can be any chosen ID, as long as it corresponds to the ID of the '<div>' designated for displaying the iframe. Our example operates in the UAT environment, with en_US as the selected locale.

Now add the following HTML to the '<body>' section of our page. Make sure the id of the '<div>' matches the containerId used above. 

                                                    

                                                        HTML
                                                    

                                                        

<html lang="en">
<head>
  <title>Hosted Checkout Demo</title>
  <script>
      var exports = {};
  </script>
  <script
      src="https://developer.uat.paymentgateway.tnsi.com/hosted-checkout/dist/index.js">
  </script>
  <script>
      document.addEventListener("DOMContentLoaded", function () {
          var hostedCheckoutSdk = new exports.HostedCheckoutSDK();
              hostedCheckoutSdk.initialize({
                    containerId: "hosted-checkout",
                    sessionId: [YOUR SESSION ID],
                    environment: "uat",
                    onApprove: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onError: function (error) {
                        console.log(JSON.stringify(error));
                        //use the error object for subsequent actions
                    },
                    onSessionExpired: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onSessionError: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onInvalidData: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onGooglePayAuthorized: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onGooglePayCanceled: function () {
                        //onGooglePayCanceled should not send back any response object. This section should be utilized for subsequent actions
                    },
                    onGooglePayError: function (error) {
                        console.log(JSON.stringify(error));
                        //use the error object for subsequent actions
                    },
                    onPaypalAuthorized: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onPaypalCaptured: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onPaypalCanceled: function () {
                        //onPaypalCanceled should not send back any response object. This section should be utilized for subsequent actions
                    },
                    onApplePayAuthorized: function (response) {
                        console.log(JSON.stringify(response));
                        //use the response object for subsequent actions
                    },
                    onApplePayCanceled: function () {
                        //onApplePayCanceled should not send back any response object. This section should be utilized for subsequent actions
                    },
                    onApplePayError: function (error) {
                        console.log(JSON.stringify(error));
                        //use the error object for subsequent actions
                    }
              });
      });
  </script>
</head>
<body>
  <div id="hosted-checkout"></div>
</body>
</html>
                                                    
                                                    

                                                        View Initialization Parameters and Callback

Now just use a browser to display the index.html file. You should see the Hosted Checkout Form, and you're ready to submit a test payment.

For more information on PayPal, Apple Pay and Google Pay, see our documentation sections.

PayPal
Apple Pay
Google Pay

Congratulations!

You've successfully integrated Hosted Checkout with your checkout process. You’ll now receive a response that is sent via the onApprove callback method as configured in the SDK initialization above. Below is the sample transaction response. 

                                                

                                                        JSON
                                                    

                                                
{
    "type": "APPROVE",
    "data": {
        "authCode": "OK1249",
        "approvedAmount": "250.20",
        "accountFirst6": "499977",
        "accountLast4": "9004",
        "hostNetwork": "1",
        "expiryMonth": "12",
        "expiryYear": "2034",
        "cardHolderName": "Sivam K",
        "avs": {
            "avsResult": "Y"
        },
        "clientTransactionId": "88af81f2-6b37-4e6a-8105-46180b713c39",
        "transactionDateUtc": "2024-07-12T06:13:51.522Z",
        "tnsResponseCode": "00",
        "tnsResponseText": "TRANSACTION_APPROVED",
        "hostResponseCode": "00",
        "hostResponseText": "APPROVAL",
        "token": "6485251555209004",
        "status": "00: APPROVAL",
        "stan": "458045",
        "transactionId": "d75f422e-ec8a-44b2-84a2-7b5a94d9a1df",
        "subtotalAmount": "250",
        "totalAmount": "250.00",
        "requestId": "742ba5fd-679a-92d0-a275-30c3d79ba4f8",
        "successful": true
    }
}

Step 3

Test payment

Let's submit a payment. Use the following test card information to make a payment transaction.

To test the Hosted Checkout sample page, click Run Create Session in API Explorer , copy the session ID from the response, and paste it into the input box below.

Test Card

4111 1111 1111 1111

Card Holder Valid Thru
Any valid cardholder name
Any future date in MM/YY format
CVV - Any three digit number
Address information - Any valid address
VISA

For more test cards to use, see Test Cards.

That's It, You're Done!

You just made a payment. For more detailed information on configuration, formatting options and callbacks, see Hosted Checkout.

We use cookies to personalize your browsing experience. By continuing to visit this website you agree to our use of cookies. You may read more about this on our Terms & Conditions.
×