Latpay API

The LatPay API provides a suite of solutions to manage the entire Checkout process along with transaction management. Our API has been built with security as its core and offers all features as required by both the back office operations team as well as ease of integration for your technical team.

By accessing the LatPay payment management engine through the API, you will be able to manage the entire cash flow from collection to payout. The LatPay platform also gives you the ability to process in over 140 currencies and settle in 26 major currencies, all in real time. The API is designed in such a way that a single unified model to integrate for card, alternate payment and bank transfer is possible. So high level of code reusability and quick integration is possible.

Our API integration is very simple. However, if you need to contact us for technical support, please e-mail us at techsupport@lpsmail.com. For sandbox access, please send email to techsupport@lpsmail.com. Signing up for the sandbox will give you access to a test MID through which you can check out live responses, make demo transactions and explore features.

Our documentation was designed to be easy to use. Our API calls are grouped by resources which you will see in the navigation menu on the left frame.

These are the base API URLs for the LATPAY environments:

Sandbox: <<<Endpoint provided on signup to test MID>>>

Production: <<<Endpoint provided on issue of live MID>>>

mediaType: application/json

The Checkout API call will initialise an order in the Latpay system and begin the checkout process for the customer. The response will provide a unique transaction id, order id to acknowledge order acceptance and state of transaction. The response code indicates the type of response along with status and error codes to indicate the actual status and if rejected, the reason for rejection.

The Checkout API is part of a unified API request to process authorisations. To use cards as payment mode, indicate the “billing” section with type set to “card” as shown the sample request.

Auth Status Check API call offers the ability to query the status of transaction in realtime. This API can be used for querying of transaction status in case if no response back for the original authorisation request. It can also be used to verify transaction status as an additional check from server, if in case the authorisation was initiated from a client side application.

The Embedded UI - Checkout (Card+Wallet) is a two step process, first step to dynamically create a payment form to securely collect customer’s card details and a second step of server side API call for authorising the payment.

1. Latpay Embedded Form - Checkout securely collects customer payment information and authorises the card or wallet. On successful completion of payment process, a callback is triggered to indicate the process completion.

2. On the callback, clients can then make a server side to their backend and then initiate a server-to-server API to validate the payment status before displaying the final status to customers.

By capturing card details from the client side and tokenising the sensitive information, the card details never pass through your server. Hence the integration is fully PCI-compliant.

Account Registration

The first step will be to obtain a Latpay processing account enabled for Embedded UI - Checkout.Register Now.

To have the wallet functionality enable for Checkouts, it would be necessary for merchants domain registered with the wallets via Latpay. As part of account request, merchant will be required to confirm their domain name on which Latpay checkout will need be emdedded. Latpay will register the domain name which will enable the wallet buttons to be shown on Latpay Checkout.

Payment Form Creation

The next step is to securely collect card details. Embedded UI - Checkout creates UI components that are hosted in Latpay in your payment form, rather than you creating them directly.

Add this script tag in the head section of your Checkout HTML page:

<script src="https://lateralpayments.com/<<path>>/Scripts/latpay3.js"></script>

This script should be loaded directly from https://lateralpayments.com

Authentication

Next, to authenticate the merchant account to enable binding of Checkout elements into the payment page. This is performed by calling the open() function on the Latpay Checkout script. This should be called on the Page Onload() event. The following Javascript code sample can be used as a template. The function provides an option to handle authentication failure for e.g. to alert website admins or write to log etc.

LatpayCheckout.open
({
merchantuserid: issued by latpay ,
publickey: issued by latpay,
currency: transaction currency,
amount: transaction amount,
reference: transaction reference,
description: transaction description,
'status': function (status) {}
//merchant can write custom logic to get alerted
//validate (status). If False, send callback to backend to raise alert for investigation.
});

On the payment form, to allow the Embedded UI - Checkout elements to be binded, it is necessary to create an empty DOM container (div tag) with the unique id “latpay-element”. This should be placed in location where you would like to have the card elements to be displayed.

Card Only

If you specifically want to handle the card section separately, replace the LatpayCheckout.open call with LatpayCheckout.open_card when initializing the card input fields. Here’s how to do it:

LatpayCheckout.open_card
({
merchantuserid: issued by latpay ,
publickey: issued by latpay,
currency: transaction currency,
amount: transaction amount,
reference: transaction reference,
description: transaction description,
'status': function (status) {}
//merchant can write custom logic to get alerted
//validate (status). If False, send callback to backend to raise alert for investigation.
});

<div id=latpay-element>
</div>
<button id="customButton">Checkout</button>

To customise the user interface styles, the following classes can be added as inline style to overwrite the default behaviour of the card element UI. The available style classes and its default configuration used in Embedded UI - Checkout element are:

CSS details

Card element style

/*This selector is used for set required field "*" color*/
span.latpay-required {
color: red;
font-weight: bold;
}

/*This selector points to form labels */
div.latpay-elements-field > label {
color: #999 !important;
font-size: 12px !important;
}

/*This selector points to CVC box while pay using card token*/
div.latpay-elements-field {
padding: 10px 5px;
}

/*This selector points all input boxes*/
div.latpay-elements-field > input {
width: 100%;
margin-top: 5px;
border: 1px solid #d9d9d9;
background: #fff !important;
padding: 6px;
font-size: 18px !important;
color: grey !important;
}

/*This selector points card brand logo*/
i.latpay-credit-card-brand {
position: absolute;
right: 8%;
margin-top: -37px;
display: block;
width: 30px;
height: 24px;
background: no-repeat url(https://lateralpayments.com/checkout/Content/images/credit-card.svg);
}

/*This selector points division between Expiry Date and CVC*/
div.latpay-flex {
display: flex;
justify-content: space-between;
padding-bottom: 5%;
}

/*This selector points division width Expiry Date and CVC*/
div#latpay-exp-element, div#latpay-cvc-element {
width: 50%;
}



/*This selector points error-list section */
li.latpay-error-list {
color: #b81c23;
font-weight: bold !important;
}

@media (max-width: 520px) and (min-width: 300px) {
div.payment_box {
padding: 0px !important;
}

div.latpay-elements-field > input {
font-size: 15px !important;
}
//applepaybutton
#latpay-applepayButtonId {
        width: 90% !important;
        min-width: 90% !important;
        height: 50px;
        }
//googlepay button        
#latpay-gp-element{
width:60%;
}
}

Once authentication is successful, the Latpay Card Element would be embedded in the merchant page.

If the customer selects the Wallet option (either Gpay or ApplePay), then the transaction flow will complete based on the wallet popup and customer completing the necessary authentication.

When the customer selects the card option and fills in the card detail, on clicking the Submit button on merchant side, should trigger the secure3dPayment() on latpay script, the function call specification as shown below.

After the payment is processed, either via Wallet or Card, the Latpay Script will then initiate a callback to a predefined function called OnPaymentCompleted(), which the merchant should implement for capturing the process status. To securely validate the final status of the payment, on the callback, merchant can then initiate a call to their server to initiate a server-to-server API call to Latpay AuthStatus check endpoint to get the final status of payment.

LatpayCheckout.secure3DPayment({
amount: 'transaction amount' ,
currency: 'transaction currency' ,
reference: 'transaction reference' ,
description: 'transaction description' ,
firstname: 'customer firstname' ,
lastname: 'customer lastname' ,
email: 'customer email' ,
transkey: transkey**,
is3dcheck:'Y'|'N' 
});

** Refer the “HPS secure3DPayment TransKey” construction details in Authentication section

The following Javascript code sample template shows an implementation for the event listener along with the Latpay script main function calls.

LatpayCheckout.open
({
merchantuserid: issued by latpay ,
publickey: issued by latpay,
currency: inputparameter,
amount: inputparameter,
reference: inputparameter,
description: inputparameter,
'status': function (status) {}
//merchant can write custom logic to get alerted
});

 $("#customButton").click(function (e) {

LatpayCheckout.secure3DPayment({
amount: 'transaction amount' ,
currency: 'transaction currency' ,
reference: 'transaction reference' ,
description: 'transaction description' ,
firstname: 'customer firstname' ,
lastname: 'customer lastname' ,
email: 'customer email' ,
transkey: 'e875a6785520c8e5b9e20bb99a6d71c251221bff2bebd44442dcddf8398aa708'(hashvalue),
is3dcheck:'Y'|'N'
});

LatpayCheckout.OnPaymentCompleted= (val) => {        
        var Url = 'https://lateralpayments.com/<<path>>/';
        var transkey = 'acbda47903d16b4a9e09d0089bef2091635a3735bdc3b50a7e6362b100c10481';
         
                var authrequest = {
                    'merchantid': $("#merchatnuserid").val(),
                    'amount': val.amount,
                    'currency': val.currency,
                    'reference': val.reference,
                    'transactionkey': transkey,
                };
                $.ajax({
                    type: 'POST',
                    url: Url + '/authorise/authstatuscheck',
                    dataType: "json",
                    async: false,
                    contentType: 'application/json; charset=utf-8',
                    data: JSON.stringify(authrequest),
                    success: function (data) {
                        var objs = JSON.stringify(data);
                        $("#paymentresponce").text(objs);
                    } });
                }})

Once the callback OnPaymentCompleted() is triggered, the following fields will be send to the callback from Latpay script.

Status Check API call offers the ability to query the status of transaction in realtime. This API can be used for querying of transaction status in case if no response back for the original authorisation request. It can also be used to verify transaction status as an additional check from server, if in case the authorisation was initiated from a client side application.

LPS Hosted Payment System (HPS) is a simple integration method suitable for all e-commerce merchants. It allows real-time transaction processing and at the same time can remove the problems involved in collecting and storing of cardholder details on merchant systems. The HPS is fully secure and linked to the LPS enterprise payment gateway which provides sophisticated fraud and risk assessment in addition to authorising the transaction. The HPS uses HTML redirect messages to pass information between merchant e-commerce site and LPS.

This method does not involve installation of any files at merchant site and hence is very simple to implement. We provide a 256-bit SSL interface for secure transmission of data over the internet. A secure reporting and administration system to provide real time information is also made available to the merchant. This document serves to explains the technical integration requirements and procedures. It is of a technical nature and should be read as such.

This integration method uses HTML forms to pass information to LPS payment gateway for payment processing. Merchants should create a purchase order form which describes the details of goods or service purchased by the customer.

1.When a shopper is ready to pay for their goods, the merchants website should submit the order details to our hosted payment page.

2.The shopper will then be taken to the LPS payment page to enter their payment details, such as credit/debit card details.

3. Once the shopper confirms the purchase the HPS system sends a request to LPS enterprise payment gateway which forwards the shopper’s details to the Acquiring bank, and which in turn returns an authorised or declined response to LPS.

4. HPS then displays the result to the shopper and sends them a confirmation email. The transaction status is then sent to merchant. If the merchant had opted for synchronous post back response, then HPS will call the merchant post back URL and post the response fields. The customer is then taken back to merchant site along with the response fields in another HTML redirect post session.

At LPS, security of customer’s financial data is of very high importance and we constantly review the existing security threats mapped against business / transaction flow and introduce mechanisms to minimise the risk of exploitation.

Since the HPS system involves the customer being redirected from different domains using browser redirection capabilities, it is very important to make sure the details generated by the merchant as part of transaction checkout are the same when redirected to HPS. And that the details have not been intercepted and changed during transit (man in middle attack).

To prevent the risk of such interception, the LPS HPS system provides a strong security mechanism wherein the transaction details are one-way encrypted (hashed) along with a secret key (salt) which will be known only to the merchant & LPS. This will be provided by merchant at the time of setup of the account with LPS.

If at any time merchant feels that the secret key may have been compromised, then merchant should get in touch with LPS and provide a new secret key.

The encryption functionality works as follows:

a. Merchant should concatenate the following fields in the same order:

• currencydesc

• amount

• merchant_ref_number

• secret key

b. Merchant should generate SHA1 hash of the above concatenated field and post this value in “transactionkey” field along with other redirection parameters.

In the LPS HPS System, the transactionkey is validated by computing the hash value again and only if the posted key matches the key computed at our end (i.e. no data tampering during transit), the transaction is accepted for processing. If the hash doesn’t match, the transaction request is declined.

The response to API indicates the status of transaction along with unique transaction and order id’s. In case of asynchronous payments where customer will be completing payments, the status will usually acknowledge as pending and final status notified on callback to URL sent on the notifyurl parameter.

Latpay Paylink module is an extension of Latpay Unified Gateway, which provides the ability for merchant to generate a paylink targeting a customer using either email or mobile or both. This paylink can be presented in the form of QR code for the customer to make payment securely.

The paylink latches on to the secure features of Hosted Payment System which is a fully compliant L1 PCI certified system.

The paylink also has features to control the expiry of link so merchant has fine grained control over when the payment should be completed. There is also the option to notify merchant on completion of payment by customer, in the form of a callback to a URL as specified by merchant in the request.

Latpay offers batch API to submit authorisation request in a batch. A batch can be upto 10k transactions. The process flow will be for each batch request, the API will validate the request and acknowledge receipt of batch with a batchid and status pending. Latpay enterprise Gateway will then sweep all pending batches and will notify the status of transactions in each batch in a callback notification.

SCA - Strong Customer Authentication Strong Customer Authentication (SCA) is a new requirement of the second Payment Services Directive (PSD2), which aims to add extra layers of security to electronic payments. The requirement ensures that electronic payments are performed with multi-factor authentication, to increase the security of electronic payments.

EMV 3D Secure, often referred to as 3DS 2.x, is the authentication protocol provided by the card networks to support SCA. To comply with SCA, merchants must deploy 3DS 2.x to their checkout page or use a compliant hosted checkout.

Latpay unified GW is compatible with 3DS 2.x and merchants can integrate into the 3dsecure flow by extending their existing integration with Latpay.

3dsecure flow:

The merchant will make the usual CNP transaction to Latpay Unified GW. In addition to the existing parameters, merchant will also flag 3dcheck as Y. This will initiate the 3dS flow for the transaction.

As part of initial response to merchant request, a 3d payer authentication response which includes payer authentication request, VBV URL to where the customer must be redirected, will be returned back.

The merchant must extract the response and then make a browser redirection to the VBV URL returned on the first request. When redirecting, merchant must include parameters Pareq, TermURL and MD.

The Pareq value to be used as returned in first request. The TermURL is the URL to which customer will be returned back after completing the payer authentication. This will need to be to a URL as issued by Latpay.

The construction of MD parameter must follow the rules as explained in next sections. It encapsulates the gateway reference, merchant reference and a “back to merchant” URL identifier. Merchants, as part of 3dsecure setup will be expected to provide URL’s to where the customer will be redirected back from Latpay. Latpay will provide unique identifiers to each of the URL’s which merchant provides, which then can be used in the construction of MD parameter.

On receiving the customer back on the “back to merchant” URL, merchant will be required to make final AuthRequest call to Latpay API. When making this call, they’ll be expected to send the PaRes value which was returned as part of the customer returing back to merchant url.

The step - by - step flow is explained below:

<<dig>>

1. At the point of checkout, the cardholder selects an appropriate payment method based on the initiatives supported by the Merchant.

2. Based on the payment information the Merchant passes a lookup message to LPS. This message contains all the required information provided by the cardholder to check the enrolment of the cardholder.

3. Based on the card number range (pulled from the Directory Server daily), a Verify Enrolment request message will be sent to the Enrolment Directory server.

4. The Enrolment Directory will send the a Verify Enrolment Request to the card holder issuing bank ACS Server where it will verify the enrolment status of the issuing bank.

5. The Verify Enrolment Response is then passed back to the Directory Server with the corresponding ACS URL, if applicable.

6. The information is then passed back to LPS where it is verified, and the Payment Authentication Request is created.

7. The Lookup response is returned to the merchant with the Payer Authentication Request [PAReq].

8. Based on the existence of the ACS URL in the Lookup response, the Merchant will redirect the card holder browser to the corresponding ACS Server.

9. The ACS URL will gather the customer profile details including browser capabilities and determine if the transaction can proceed as “frictionless” (i.e. No additional authentication needed) or if a “challenge” (additional authentication is necessary). If deemed challenge, then prompt to enter additional authentication is shown for customer to enter.

10. The ACS, in conjunction with the Card Issuer, authenticates the cardholder.

11. The Payer Authentication Response [PARes] along with the customer is returned to the LPS gateway, via the web browser.

12. The Payer Authentication Response is then forwarded to the merchant to the backtomerchant url requested in the original redirection (step 8)

13. The merchant initiates the authenticate message, which is sent to the LPS gateway for processing.

14. LPS 3D secure system validates the Payer Authentication Response, and along with the rest of the transaction information, sends out the authorization to the payment network.

The merchant’s server makes a request for authorisation passing all the mandatory fields and relevant optional fields through a synchronous secure HTTP POST as per table given in Schedule 2A. LPS Gateway will initiate the 3d2 request for the transaction and respond back with the Payment Authentication Request & VBV URL to which merchant must redirect the customer.

LPS Payment Gateway will return the information as per table given in Schedule 2C.

_3dresponse

enrollmentdata

The merchant will be required to handle the response, check the presence of URL, and then redirect the customer to the URL returned along with Payment Authentication Request (PAReq) returned. When merchant redirects the customer to their issuing bank 3D SECURE page they will also be required to attach the “TARGET” page to which the customers will be redirected after successful 3D SECURE authentication with their issuing bank as a hidden field parameter. The merchant should also attach as hidden field parameters their system reference number and LPS Transaction Id for retrieval of the transaction at LPS Payment Gateway after 3D SECURE authentication.

The fields that needs to be sent along with the redirection to 3D SECURE URL is given in Table 2D.

<<Table 2D>>

**Note that all the fields are mandatory and must be send as hidden variables.

Pareq

3D SECURE Provider Payment Authentication Request returned in 2C.

TermUrl

The “target” page on LPS payment gateway to which the customer is redirected after 3D SECURE authentication

MD

Merchant Details. The following post variables must be concatenated together:
a. gatewayreference (LPS Transaction Id)
b. Merchant_ref_number (Merchant Ref Number)
c. BackToMerchantURL (urlidentifiervalue)

**Sample MD param will be like:

gatewayreference=760371&Merchant_ref_number=yoursystemref&BackToMerchantURL=grp327_JRSI

Below script for redirection

<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
<script>

function post(path, params, method='post') { 

  // The rest of this code assumes you are not using a library.
  // It can be made less verbose if you use one.
  const form = document.createElement('form');
  form.method = method;
  form.action = path; 

  for (const key in params) {
    if (params.hasOwnProperty(key)) {
      const hiddenField = document.createElement('input');
      hiddenField.type = 'hidden';
      hiddenField.name = key;
      hiddenField.value = params[key]; 

      form.appendChild(hiddenField);
    }
  } 

  document.body.appendChild(form);
  form.submit();
} 
<!-- //function post(path, parameters) {

    var form = $('<form></form>');
document.write("form form");
    form.attr("method", "post");
    form.attr("action", path); 

    $.each(parameters, function(key, value) {
        var field = $('<input></input>'); 

        field.attr("type", "hidden");
        field.attr("name", key);
        field.attr("value", value); 

        form.append(field);
    }); 

    // The form needs to be a part of the document in
    // order for us to be able to submit it.
    $(document.body).append(form);
    form.submit();
//} -->
</script>

When the customer is redirected to a URL on LPS Gateway after 3D SECURE authentication, it will match the transaction Id passed with the existing pending transaction. The status of the transaction will be updated to “3D SECURE Response Returned” and the 3D SECURE response will then be transferred back to a merchant’s URL which will return the customer back to the merchant site along with the details given in Table 2E.

<<Table 2E>>

LPS_transaction_id—Unique Identifier for the transaction generated by LPS

Merchant_ref_number—Merchant reference number generated for the order

Lpsid—LPS Response Authentication User Id

Lpspwd—LPS Response Authentication User Password

PARes—3D SECURE Authentication Response

The merchant should extract the 3D SECURE response and update the status of the transaction as 3D SECURE Response received. Note at this stage neither LPS nor the merchant know if the 3D SECURE authentication is successful. They will then open synchronous connection back to LPS payment gateway with the transaction details as shown in next step Table 2F.

LPS Payment gateway on receiving the payment request as per table 2F will send the 3D SECURE authentication response back to the 3D SECURE provider to validate if the 3D SECURE authentication was successful.

<<Table 2F>>

If successful, then it will be passed to the acquirer along with 3D SECURE authentication response. After the transaction is authorized / rejected, the response will be sent back to the merchant on the same synchronous connection along with the details specified in Table 2B with ResponseType = 1. If the 3D SECURE authentication has failed, LPS will return the transaction back to the Merchant as 3D SECURE failed transaction with the details specified in Table 2B with ResponseType = 0.

The Checkout API is part of a unified API request to process authorisations. To use direct debit / direct credit as payment mode, indicate the “billing” section with type set to “dd” or “dc” as shown the sample request.