Implementing a <<checkout>> Integration

Prerequisites

  • Ensure that your merchant profile is enabled for the <<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.
  • Before you start your integration, see Best Practices and Tips.

Request a <<checkout>> Interaction

Requesting a <<checkout>> interaction is a simple process:

  1. Request a checkout session using the Create Checkout Session operation. The request should include payment and interaction data, as well as completion instructions. A sample curl snippet for the Create Checkout Session operation is shown below.
    curl https://test-bankalfalah.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"
    
    For information on how to generate the API password, see Generating API Password.

    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. See Obtaining the Payment Result.

    Create Checkout Session API Reference [REST][NVP]

  2. Reference the checkout.js file from the gateway servers. This will place a Checkout object into global scope.
    <script src="https://test-bankalfalah.gateway.mastercard.com/checkout/version/57/checkout.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
    
    If you are enabled for both Authorization and Purchase transaction types, you must use <<checkout>> version 52 or above.

    checkout.js Reference[JavaScript]

  3. Call Checkout.configure(), passing in a JSON object that includes the returned session.id and other request parameters.
    Checkout.configure({
                  session: { 
                	id: '<your_create_checkout_session_ID>'
           			},
                  interaction: {
                        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 Checkout Session operation.
  4. Start the payment process by calling one of the following:
    • To display the checkout interaction in a <<hostedCheckoutLightbox>>:
      Checkout.showLightbox()
    • To display the checkout interaction on a <<hostedPaymentPage>>:
      Checkout.showPaymentPage()

Example HTML code to Request a Checkout Interaction

<html>
    <head>
        <script src="https://test-bankalfalah.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>
Values controlling the behaviour of <<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

<script src="https://test-bankalfalah.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 <<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 <<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.

checkout.js Reference[JavaScript]

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 <<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 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 <<reportingAPI>>

If you subscribe to <<reportingAPI>>, you can download <<checkout>> payment data in a formatted report from the <<paymentGateway>>.

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

<<checkout>> allows you to control the display of information about your business and the interaction with the payer using either the Create Checkout Session operation or the Checkout.configure() method. Note that data provided in the Create Checkout 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 Checkout Session operation.

Example Create Checkout Session Request
URL https://test-bankalfalah.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( ) Request
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.

Display Brand Information

This includes your logo as well as contact details.

For more details see:

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 <<checkout>> to display the fields.
  • MANDATORY: If you want <<checkout>> to display the fields and make data entry compulsory for the payer.
  • OPTIONAL: If you want <<checkout>> to display the fields, but allow the payer to opt out of entering data into them.
  • READ_ONLY: If you want <<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 <<checkout>> to display order summary.
  • SHOW_PARTIAL: If you want <<checkout>> to display order summary, which may not include payment details.
  • SHOW: If you want <<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 <<checkout>> to display the fields.
  • READ_ONLY: If you want <<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 <<checkout>> to display payment confirmation.
  • HIDE: If you do not want <<checkout>> to display payment confirmation.

Manage Language and Theme

By default, the language displayed with <<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 <<paymentGateway>>, <<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 <<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 <<hppThemes>>.

Dynamic Currency Conversion

If you are configured for Dynamic Currency Conversion and the card home currency differs from the order currency, <<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.

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

If a DCC offer is accepted, <<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 <<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 <<paymentGateway>> will automatically generate one for you.

3-D Secure Authentication

With <<checkout>> integrations version 55 and later, EMV 3DS authentication will automatically be available when your payment service provider has successfully enabled it.

Achieve WCAG (Web Content Accessibility Guidelines) Compliance

<<checkout>> may be configured to provide a user experience compliant with WCAG 2.0 Level AA. See WCAG 2.0 guidelines and ensure your website conforms to this technical standard.

Details
Checkout.configure({
    merchant   : '<your_merchant_id>',
    order      : {
        amount     : function () { //Dynamic calculation of amount
            return 80 + 20
        },
        currency   : 'USD',
        description: 'Ordered goods',
        id: '<unique_order_id>'
    },
    ....
    ....
    ....
    interaction: {
        ....
        ....
        ....
        displayControl: {
            orderSummary    	: 'SHOW',
            paymentConfirmation	: 'SHOW',
            billingAddress 	: 'OPTIONAL',
            customerEmail   	: 'OPTIONAL',
            shipping        	: 'HIDE'
        }
    }
});

To be WCAG compliant, you must display the order summary and payment confirmation to the payer before they submit their payment. Set the following display parameters to "SHOW" in the Checkout.configure() method:

  • interaction.displayControl.orderSummary=SHOW
  • interaction.displayControl.paymentConfirmation=SHOW

Set the lang attribute

Add lang attribute to the html element.

<html lang="en">
    <head></head>
    <body></body>
</html>

Offer Payment Plans

If you have payment plans configured on your merchant profile, by default all payment plans on your merchant configuration will be displayed to the payer during <<checkout>>. However, payment plans available to the payer will be determined by the card number entered by the payer and the currency for the order.

Limit the Available Payment Plans

You can limit payment plans available on offer by specifying constraints on payment plans on a per transaction basis. This is useful if you wish to ensure that payment options offered to the payer conform to pre-defined criteria thereby preventing payment processing if the payer tampers with the payment plan data. You can use the following fields in the request to specify constraints:

  • constraints.paymentPlans.supported[n]: The payment plans offered for this transaction.
  • constraints.paymentPlans.numberOfPayments: The allowable number of installments for the payment plan.
  • constraints.paymentPlan.numberOfDeferrals: The allowable number of deferral months for the payment plan.
Display Payment Terms for a Payment Plan

By default, the payment terms for a payment plan, if available, are displayed on <<checkout>>. You can hide them by setting interaction.displayControl.paymentTerms=HIDE in Checkout.configure().

Offering Plan AMEX in some regions may require you to inform the payer of payment terms before processing the payment.

Support for Payment Details Verification

For gift cards and <<ach>> payments, <<checkout>> only supports payment details verification.

You can do this by setting interaction.operation=VERIFY in the Create Checkout Session request.

<<checkout>> uses the verification methods supported by the configured acquirer and the data provided in the request.

You can determine the success of the verification operation by comparing resultIndicator to successIndicator.

If the interaction was not successful, <<checkout>> displays a message indicating that verification has failed and prompts the payer to try again.

Support for non-eCommerce Integrations

You can use <<checkout>> with any transaction source configured on the merchant profile (Internet, Call Centre, Telephone Order, etc).

Details

You can do this by providing transaction.source in the Create Checkout Session request.

If a <<checkout>> is requested with transaction.source other than INTERNET, payment options that require the payer to be present will not be supported.

If you do not provide transaction.source in the request:

  • It defaults to INTERNET if supported on the merchant-acquirer link.
  • If not supported, it defaults to the transaction source in your merchant profile.

Control Card Security Code

You can control whether payers are required to provide the Card Security Code to process the payment by setting interaction.displayControl.cardSecurityCode in the Create Checkout Session request to one of the following values:

  • OPTIONAL: If you want <<checkout>> to display the Card Security Code input field but input to this field is not mandatory.
  • MANDATORY (default): If you want <<checkout>> to display the Card Security Code input field and make it mandatory.
Be careful about making the Card Security Code optional, as some acquirers may require it to process the transaction.

Create Checkout Session API Reference [REST][NVP]

Bypass Security Features

If you are configured for 3-D Secure authentication or a risk management service, you have the option to bypass these should you wish to do so.

Details
  • Bypass Payment Authentication: Set interaction.action.3DSecure=BYPASS in the Create Checkout Session request.
  • Bypass Risk Assessment: Set risk.bypassMerchantRiskRules=ALL in the Create Checkout Session request.

Test Your Integration

Before going live, you must test your integration to ensure correct functionality.

Troubleshooting and FAQs

What should I do if <<checkout>> returns an error?

<<checkout>> can return a number of integration errors. See Test Your Integration.

Why am I getting an error page?

An error page is provided when an incorrect <<checkout>> request is attempted. Common causes for errors include:

  • The mandatory fields have not been supplied.
  • URLs provided in the request are not absolute.
What happens if the payer double submits (double clicks) the "Pay" button?

If the payer double submits the "Pay" button, the transaction will not be repeated with your or the payer's bank.

Where can I find the PAGE protocol and <<hostedPaymentPage>> PAY request API reference page?

The PAGE protocol is being deprecated by the <<checkout>> JavaScript integration.

For existing <<hostedPaymentPage>> integrations, see integration guidelines and API Reference (Click here (HTML) or here (WADL)).

Are Microsoft browsers supported by <<checkout>>?

Yes. IE 11 (non-enterprise mode) and Edge 18 are supported.

Best Practices and Tips

How secure is the <<checkout>> integration?

The <<checkout>> model is secure as it requires you to authenticate to the gateway, and the payment details collected on the payment page are submitted directly from the payer's browser to the gateway.

If you choose not to return the payer to your shop site, it is recommended that you check the notification email or log onto Merchant Administration to ensure that the order details are correct before you ship the goods or services to the payer.
Are there any restrictions on the file size and dimensions for the merchant logo displayed on the payment page?

Although by design there are no restrictions on the file size, we recommended that it does not exceed 100 kB to ensure quick page loading. The recommended dimensions for the logo are <<pageMerchantLogoSize>>.

Can I use any hosted provider for hosting the logo image?

Yes, you can host your logo image on any provider, however; it's mandatory that the URL is secure (HTTPS). If your hosted provider does not support a secure URL, here's a list of providers that can offer you free HTTPS hosting: https://www.google.com.au/search?q=secure+image+hosting+providers

Why is the Same as Shipping checkbox sometimes not shown?

This checkbox is visible only if all required fields in the shipping address have been provided. You must ensure that either the payer has completed these, or that you supply any missing ones (such as shipping.country, in the case where goods are not being shipped internationally).

How can I optimize my mobile interactions with <<checkout>>?

If you would like to offer your customers a good mobile experience including optimizing your <<checkout>> experience on mobile, it is a best practice to add a 'viewport' meta tag to your site's page. For example,

<meta name="viewport" content="width=device-width, initial-scale=1">

Please note that it's important to choose the right viewport values for your pages and to test your own site with these changes.

Copyright © 2020 <<company>>