Express Gateway

Documentation

Overview
Integration Guide
Request an Interaction
Callbacks
Obtain the Payment Result
Customize the Payment Experience
3-D Secure Authentication
Support for Payment Details Verification

Overview
Integration Guide
Request an Interaction
Callbacks
Obtain the Payment Result
Customize the Payment Experience
3-D Secure Authentication
Support for Payment Details Verification

I. Overview

This document will explain for the integration options for Sathapana Bank merchant to integrate with Express Gateway service.

II.Integration Guides

Your web or mobile app Shop

Payment Interface

Receipt

Prerequisites:

- Ensure that your merchant profile is enabled for the Express Gateway 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.

a.Request an Express Gateway Interaction

Requesting an Express Gateway interaction is a simple process:

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

curl https://test-gateway.mastercard.com/api/nvp/version/67 -d "apiOperation=INITIATE_CHECKOUT" -d "apiPassword=$PWD" -d "apiOperation=INITIATE_CHECKOUT" -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.

2.Reference the checkout.min.js file from the gateway servers. This will place a Checkout object into global scope. If you are enabled for both Authorization and Purchase transaction types, you must use Express Gateway version 52 or above.

<script  src="https://test-gateway.mastercard.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>

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

Checkout.configure({ 
      session: { 
      id:'<your_initiate_checkout_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 Initiate Checkout operation.

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

To display the checkout interaction in an Embedded Page:

Checkout.showEmbeddedPage('#embed-target')

b. Callbacks

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.

<script src="https://ap-gateway.mastercard.com/static
        /checkout/checkout.min.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>

<script src="https://ap-gateway.
   mastercard.com/static/checkout/
   checkout.min.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>

c. Obtain the Payment Result

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 Initiate Checkout operation, OR
define the complete callback in the Express Gateway request. This applies to both basic and redirect 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
provide interaction.returnUrl in the Initiate Checkout operation, OR

You can determine the success of the payment by comparing the resultIndicator parameter to the successIndicator parameter returned in the Initiate Checkout response. A match indicates that the payment has been successful.

Note: The value in the resultIndicator parameter must never be used as the receipt number.

d.Customize the Payment Experience

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

Example Initiate Checkout Request

URL	https://ap-gateway.mastercard.com/api/rest/version/65
/merchant/{merchantId}/session
HTTP Method	POST

{
    "apiOperation": "INITIATE_CHECKOUT",
    "interaction": {
        "operation": "AUTHORIZE"
    },
    "order"      : {
        "amount"     : "122.0",
        "currency"   : "USD",
        "description": "Ordered goods",
        "id": "232E32323ddd"
    }
}

URL	https://ap-gateway.mastercard.com
    /api/rest/version/65/merchant
    /{merchantId}/session
HTTP Method	POST

{
  "apiOperation": "INITIATE_CHECKOUT",
  "interaction": {
    "operation": "AUTHORIZE"
    },
    "order"      : {
      "amount"     : "122.0",
      "currency"   : "USD",
      "description": "Ordered goods",
      "id": "232E32323ddd"
    }
}

Example Checkout.configure() Request

Checkout.configure({
session: { 
           id: '<your_initiate_checkout_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',
        style: {

            theme: 'default'
         
         },
        displayControl: {
            billingAddress  : 'OPTIONAL',
            customerEmail   : 'OPTIONAL',
            shipping        : 'HIDE'
        }
    }
});

Checkout.configure({
session: { 
id: '<your_initiate_checkout_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@yourMerchant
    EmailAddress.com',
    phone  : '+1 123 456 789 012',
    logo  : 'https://imageURL'
    },
    locale : 'en_US',
    style: {
    theme: 'default'    
    },
  displayControl: {
  billingAddress  : 'OPTIONAL',
  customerEmail   : 'OPTIONAL',
  shipping        : 'HIDE'
  }
}
});

e.3D Secure Authentication

With Express Gateway integrations version 57 and later, you must select 3-D Secure Authentication from the Payer Authentication dropdown in the Admin > Integration Settings page of the Merchant Administration user interface.

f.Support for Payment Details Verification

For gift cards and Automated Clearing House payments, Express Gateway only supports payment details verification. You can do this by setting interaction.operation=VERIFY in the Initiate Checkout request. Express Gateway 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, Express Gateway displays a message indicating that verification has failed and prompts the payer to try again.