Hosted Checkout Integration Guide

The Hosted Checkout model allows you to collect payment details from your payer through an interaction hosted and displayed by the Tyro eCommerce Payment Gateway.

You never see or handle payment details directly because these are collected by the hosted payment interface. They are submitted directly from the payer’s browser to the Tyro eCommerce Payment Gateway. Hosted Checkout is similar to Hosted Session in this regard.

Hosted Checkout is a PCI version 3 compliant integration method. For up-to-date information about PCI compliance see the PCI Security Standards Council website.

Checkout is recommended in cases where you’ll be creating a new session each time your customer attempts to pay (one-time purchases or subscriptions are often processed through Checkout).

You will be using the checkout.js library.

Hosted Checkout can be implemented as:

  • A Lightbox in a modal dialog over the top of your existing merchant website.

  • A Hosted Payment Page (a web page hosted and displayed by the Tyro eCommerce Payment Gateway).

Key Benefits

  • Hosted Checkout is simple and quick to integrate.
  • You do not need to handle or store any payment details, thereby lowering PCI compliance costs.
  • You can leverage the brand of your payment service provider by using the provided theme to display your Hosted Checkout interface.
  • You can customize the content of the Hosted Checkout interface to display your business information.
  • You have the option of subscribing to notifications and being informed if the payment is successful.

Request a Hosted Checkout interaction

Prerequisites

  • Ensure that your merchant profile is enabled for the Hosted Checkout service.
  • It is recommended that you opt for the Notifications service to receive notifications (email/Webhook) if the payment is successful. The gateway (on behalf of you) can also send email notifications to the payer.

You must modify the script below to reflect your preferences for the payment page before you make an API call.

Configure the Payment Page or Lightbox - Hosted Checkout
Full script
  <html>
    <head>
        <script src="https://test-tyro.mtf.gateway.mastercard.com/checkout/version/57/checkout.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
        <script type="text/javascript">
            function errorCallback(error) {
                  console.log(JSON.stringify(error));
            }
            function cancelCallback() {
                  console.log('Payment cancelled');
            }
            Checkout.configure({
              session: { 
            	id: '<your_create_checkout_session_ID>'
       			},
              interaction: {
                    merchant: {
                        name: 'Your merchant name',
                        address: {
                            line1: '200 Sample St',
                            line2: '1234 Example Town'            
                        }    
                    }
               }
            });
        </script>
    </head>
    <body>
       ...
      <input type="button" value="Pay with Lightbox" onclick="Checkout.showLightbox();" />
      <input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" />
       ...
    </body>
</html>

Instructions

1.1. Request a checkout session using the Create Hosted Checkout Session operation. The request should include payment and interaction data, as well as completion instructions. A sample curl snippet for the Create Hosted Checkout Session operation is shown below.

Sample curl
Create Hosted Checkout Session
curl https://test-tyro.mtf.gateway.mastercard.com/api/nvp/version/57 \
-d "apiOperation=CREATE_CHECKOUT_SESSION" \
-d "apiPassword=$PWD" \
-d "apiUsername=merchant.<your_merchant_id>" \
-d "merchant=<your_merchant_id>" \
-d "interaction.operation=AUTHORIZE" \
-d "order.id=<unique_order_id>" \
-d "order.amount=100.00" \
-d "order.currency=USD"

A successful response to this operation will contain session.id and successIndicator parameters. You can save the value returned in the successIndicator parameter on your shop system to verify the success or failure of the payment.

1.2. Reference the checkout.js file from the gateway servers. This will place a Checkout object into global scope.

Configure the Payment Page or Lightbox - Hosted Checkout
Step 1.2
<script src="https://test-tyro.mtf.gateway.mastercard.com/checkout/version/57/checkout.js" data-error="errorCallback" data-cancel="cancelCallback"></script>

1.3. Call Checkout.configure(), passing in a JSON object that includes the returned session.id and other request parameters.

Configure the Payment Page or Lightbox - Hosted Checkout
Step 1.3
Checkout.configure({
              session: { 
            	id: '<your_create_checkout_session_ID>'
       			},
              interaction: {
                    merchant: {
                        name: 'Your merchant name',
                        address: {
                            line1: '200 Sample St',
                            line2: '1234 Example Town'            
                        }    
                    }
               }
            });

Please check that you are passing in an appropriate JSON object with operation type (AUTHORIZE or PURCHASE), payment details, interface configuration, and user interaction specifications.

The operation type appears in the code block as follows (line 3):

Configure the Payment Page or Lightbox - Hosted Checkout
Step 1.3

interaction: {
                operation: 'AUTHORIZE', //Set this field to 'PURCHASE' for Hosted Checkout to perform a Pay Operation

The payment details appear in the code block as follows (lines 3 - 9):

Configure the Payment Page or Lightbox - Hosted Checkout
Step 1.3
                
								order: {
                amount: function() {
                    //Dynamic calculation of amount
                    return 80 + 20;
                },
                currency: 'USD',
                description: 'Ordered goods',
               id: '<unique\_order\_id>'
            },

The interface configuration and user interaction specifications should look like this:

Configure the Payment Page or Lightbox - Hosted Checkout
Step 1.3.
   interaction: {
                operation: 'AUTHORIZE', // set this field to 'PURCHASE' for Hosted Checkout to perform a Pay Operation.
                merchant: {
                    name: 'Your merchant name',
                    address: {
                        line1: '200 Sample St',
                        line2: '1234 Example Town'            
                    }    
                }

Data passed in Checkout.configure() will never overwrite data you provided in the Create Hosted Checkout Session operation (step 1.1).

1.4. Start the payment process by calling one of the following:

  • To display the checkout interaction in a Lightbox :

    • Checkout.showLightbox()
    • See line 1 in the code block below
  • To display the checkout interaction on a Hosted Payment Page:

    • Checkout.showPaymentPage()
    • See line 2 in the code block below
Configure the Payment Page or Lightbox - Hosted Checkout
Step 1.4.
<input type="button" value="Pay with Lightbox" onclick="Checkout.showLightbox();" />
    <input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" />
    ...

Values controlling the behaviour of Hosted Checkout may be passed in Checkout.configure() as:

  • Literals – e.g. quantity : 300
  • Functions that return a value, e.g. quantity : function() { return 100 + 200 }.

Functions are executed when the payment process is triggered.

Callbacks

Callbacks
Script
<script src="https://test-tyro.mtf.gateway.mastercard.com/checkout/version/57/checkout.js"
         data-cancel="cancelCallback"
         data-beforeRedirect="Checkout.saveFormFields"
         data-afterRedirect="Checkout.restoreFormFields">
</script>

<script>
     function cancelCallback() { 
          confirm('Are you sure you want to cancel?');
         // code to manage payer interaction
    }
// or if you want to provide a URL:
// cancelCallback = "someURL"
</script>

Callbacks are provided to handle events that may occur during the payment interaction.

Use of callbacks is optional, but you must define those you need in the body of the same <script> tag that references checkout.js.

All defined callbacks must have an implementation. They will be invoked when the relevant event is triggered.

Basic callbacks

Basic callbacks are provided for handling the following events:

  • cancel: When the payer cancels the payment interaction.
  • error: When an error is encountered.
  • complete: When the payer completes the payment interaction.
  • timeout: When the payment is not completed within the duration available to the payer to make the payment.

These can be functions or URLs. If you provide a URL instead of a function in a callback, the payer will be redirected to this URL when the event is triggered.

Redirect callbacks

Since Hosted Checkout supports payment interactions that require the payer to be redirected away to other websites to progress the payment (e.g. PayPal), callbacks are provided to manage what happens before the redirect and after return to Hosted Checkout to finalize transaction processing.

  • beforeRedirect: Before the payer is presented with the payment interface. Returns data required to restore page state for use by afterRedirect.
  • afterRedirect: When the payer returns from completing the payment interaction. Uses the data saved by beforeRedirect to return the saved payment interface state.

The Checkout object also provides two functions to help you implement the beforeRedirect and afterRedirect callbacks:

  • saveFormFields: Saves all current form fields for use by restoreFormFields. Use in your beforeRedirect implementation or implement beforeRedirect as Checkout.saveFormFields.
  • restoreFormFields: Restores form fields saved by saveFormFields. Use in your afterRedirect implementation or implement afterRedirect as Checkout.restoreFormFields.

Obtain the Payment Result

By Returning the Payer to Your Shop Site

After the payment interaction completes, you can return the payer to your shop site and present your own receipt page to the payer. You can also update your shop system with the payment details.

To return the payer to your shop site, you must either:

  • provide interaction.returnUrl in the Create Checkout Session operation, OR
  • define the complete callback in the Hosted Checkout request. See Basic Callbacks.

The gateway sends the result of the payment in a resultIndicator parameter, which is either:

  • appended to the URL (interaction.returnUrl) used for returning the payer to your shop site, OR
  • provided as an input parameter to the function provided in the complete callback or appended to the URL provided in the complete callback.

You can determine the success of the payment by comparing the resultIndicator parameter to the successIndicator parameter returned in the Create Hosted Checkout Session response. A match indicates that the payment has been successful. The value in the resultIndicator parameter must never be used as the receipt number.

If successful, present a payment receipt to the payer on your shop site, and update your shop system with the payment details. You can retrieve these using the Retrieve Order operation.

Via Merchant Administration

The payment details are recorded in Merchant Administration in the Order and Transaction Details page. You can search for the payment and also perform subsequent operations.

Using Reporting

If you subscribe to Reporting, you can download Hosted Checkout payment data in a formatted report from the Tyro eCommerce Payment Gateway.

Via Email or Webhook Notifications

If you subscribe to email notifications in Merchant Administration, you will receive an email notification for every successful payment. You can also choose to subscribe to Webhook Notifications to receive an API notification for every payment update.

Customize the Payment Experience

Hosted Checkout allows you to control the display of information about your business and the interaction with the payer using either the Create Hosted Checkout Session operation or the Checkout.configure() method. Note that data provided in the Create Checkout Hosted Session request will always take precedence over data provided in the Checkout.configure() method. For enhanced security, it’s recommended that you provide data in a session using the Create Hosted Checkout Session operation.

Example Create Hosted Checkout Session Request
Script
URL 	https://test-tyro.mtf.gateway.mastercard.com/api/rest/version/57/merchant/{merchantId}/session
HTTP Method 	POST


{
    "apiOperation": "CREATE_CHECKOUT_SESSION",
    "interaction": {
        "operation": "AUTHORIZE"
    },
    "order"      : {
        "amount"     : "122.0",
        "currency"   : "USD",
        "description": "Ordered goods",
        "id": "232E32323ddd"
    }
}
Example Checkout.configure()
Script
Checkout.configure({
session: { 
           id: '<your_create_checkout_session_ID>'
       			},
    billing    : {
        address: {
            street       : '123 Customer Street',
            city         : 'Metropolis',
            postcodeZip  : '99999',
            stateProvince: 'NY',
            country      : 'USA'
        }
    },
    interaction: {
        merchant      : {
            name   : 'Your merchant name',
            address: {
                          line1: '200 Sample St',
                          line2: '1234 Example Town'            
            },
            email  : 'order@yourMerchantEmailAddress.com',
            phone  : '+1 123 456 789 012',
            logo   : 'https://imageURL'
        },
        locale        : 'en_US',
        theme         : 'default',
        displayControl: {
            billingAddress  : 'OPTIONAL',
            customerEmail   : 'OPTIONAL',
            orderSummary    : 'SHOW',
            shipping        : 'HIDE'
        }
    }
});

The fields provided in the interaction.merchant parameter group will be displayed on the receipt page for the Hosted Payment Page integration only, not for the Lightbox.

Manage Display of Payer Billing and Email Addresses

After collecting billing and email addresses from your payer, you can display these and control their editability by setting interaction.displayControl.billingAddress and interaction.displayControl.customerEmail fields to one of the following:

  • HIDE: If you do not want Hosted Checkout to display the fields.
  • MANDATORY: If you want Hosted Checkout to display the fields and make data entry compulsory for the payer.
  • OPTIONAL: If you want Hosted Checkout to display the fields, but allow the payer to opt out of entering data into them.
  • READ_ONLY: If you want Hosted Checkout to display the fields, but not allow the payer to edit them.

Manage Display of Order Summary

By default, order summary is displayed to the payer before the payer can submit the payment. However, you can control the display by setting interaction.displayControl.orderSummary field to one of the following:

  • HIDE: If you do not want Hosted Checkout to display order summary.
  • SHOW_PARTIAL: If you want Hosted Checkout to display order summary, which may not include payment details.
  • SHOW: If you want Hosted Checkout to display order summary, which may include payment details.

Manage Display of Shipping Details

After collecting shipping details from your payer, you can control their display by setting interaction.displayControl.shipping field to one of the following:

  • HIDE: If you do not want Hosted Checkout to display the fields.
  • READ_ONLY: If you want Hosted Checkout to display the fields, but not allow the payer to edit them.

The payer will not be able to edit any of the shipping details previously provided.

The functionality of the Same as Shipping checkbox will not be available if the required shipping details have not been supplied.

Manage Display of Payment Confirmation

By default, payment confirmation is not requested from the payer. However, you can control the display by setting interaction.displayControl.paymentConfirmation field to one of the following:

  • SHOW: If you want Hosted Checkout to display payment confirmation.
  • HIDE: If you do not want Hosted Checkout to display payment confirmation.

Manage Language and Theme

By default, the language displayed with Hosted Checkout is determined from the payer’s browser. However, you can override this behavior by specifying a language identifier or IETF language tag in the locale field; e.g. en_US, es, fr_CA. If the language you specify is not supported by the Tyro eCommerce Payment Gateway, Hosted Checkout is displayed in the best matching language.

By default, the theme set as default by your payment service provider controls the look and feel of Hosted Checkout. If your payment service provider supports multiple themes, you can choose to override the default theme by providing interaction.theme field in your request.

The theme available for you at this time is Hosted Payment Page Themes.

Dynamic Currency Conversion

If you are configured for Dynamic Currency Conversion and the card home currency differs from the order currency, Hosted Checkout will offer the payer the option of using Dynamic Currency Conversion instead of the card scheme conversion. The offer text is designed to be compliant with card scheme requirements and locale.

A payer’s choice can be collected by providing a gatewayDCCOfferCallback function. If defined, this will be called each time the payer makes a selection in the offer form.

If the payer does not make a choice, the callback is not called.

gatewayDCCOfferCallback function
Example
window.gatewayDCCOfferCallback = function(choice) {
    if (choice == 'Accept') {
        //dcc offer was accepted
    } else {
        //dcc offer was rejected
    }
}

If a DCC offer is accepted, Hosted Checkout will also provide a receipt text, localized in the same way as the offer text.

Order ID

It is recommended that you include order.id in your request to easily identify a payment initiated from Hosted Checkout. You can use an identifier generated by your shopping cart or supply your own. However, ensure that it is unique.

If you don’t supply a value in order.id, the Tyro eCommerce Payment Gateway will automatically generate one for you.