Latpay-Ecomm

Schedule 2A – LPS POST Specification for Payment Request using CARD

Schedule 2B – LPS POST Specification for Payment Response

This document provides integration and usage instructions for using the LPS 3D SECURE integration specification using an asynchronous connectivity model. Integrating with LPS 3D SECURE integration specification will enable participation in payment authentication initiatives such as Verified by Visa (Visa 3D-Secure), Master Card Secure Code and JCB J/Secure. This document assumes you have familiarity with your website and payment processing procedures as well as a proficiency using the technologies and programming languages that your website implements.

The aim of the document is NOT to break any existing compatibility modes if the merchant has already integrated with LPS Payment Gateway. All the post data which if merchant has integrated with synchronous connection model has been retained and minimum customer redirection is proposed.

Since the purpose of 3D SECURE initiative is to reduce the chargebacks by customers authenticating with their issuing bank, which involves customers being navigated out of merchant’s websites, the status of the transaction will NOT be in real time but through separate connection between LPS gateway and merchant servers.

TRANSACTION FLOW DIAGRAM

Transactions are sent via a Synchronous HTTP POST; the response is received on the same TCP/IP connection. The transaction flow is depicted in the following diagram given below:

• CUSTOMER TO MERCHANTS WEBSITE
  Customer submits payment request encrypted over SSL;
  
  
• CUSTOMER TO MERCHANTS WEBSITE
  Contains all the necessary card data and card holder details. This is sent over secure encrypted SSL;
  
  
• LPS SERVER TO MERCHANTS SERVER
  LPS gateway performs data, velocity, and fraud checks. If any fail, the transaction process is stopped, and a failure code is returned;
  
  
• LPS SERVER TO BANK
  The transaction is sent from the LPS gateway to the bank;
  
  
• LPS TO MERCHANTS SERVER
  LPS sends the bank response details to merchant server;
  
  
• MERCHANT SERVER TO END USER
  Merchant updates database and notifies customer of success or failure of the transaction;
  
  
• LPS SERVER TO END USER
  LPS can send an e-mail receipt to customers where the transaction is successful. Merchant can receive a copy of the e-mail for customer support or account management purposes;
  
  
• 3D SECURE AUTHENTICATION
  LPS payment gateway can also perform 3D secure authentication for participating cardholders against their issuing bank before authorizing the transactions. The 3D secure flow is depicted in section 3.
  
  

THE 3D SECURE TRANSACTION

LPS 3D SECURE INTEGRATION FLOW
NB. For questions or help at any stage of integration, please send an email to technical@lpsmail.com

1. OVERVIEW
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. If the merchant has already integrated with LPS Payment Gateway, the post parameters remain the sameto maintain backward compatibility except for one additional optional parameter “3dSecureCheck”. By setting this parameter to “Y”, the merchant can force the transaction to be verified by 3d secure before authorisation. LPS Payment Gateway will check if the customer is enrolled for 3D SECURE verification. If the customer is enrolled, LPS Payment Gateway responds on the same synchronous connection the URL for customer’s issuing bank 3D SECURE verification URL along with 3D SECURE verification request. If the customer is NOT enrolled, LPS Payment Gateway proceeds with normal authorisation without 3D SECURE checks or rejects the transaction as per card scheme rules.
The rest of the document illustrates only in the case of if the customer is enrolled with their issuing bank for 3D SECURE checks. As explained above, if the customer is NOT enrolled the transaction will continue as normal synchronous authentication to the bank gateway and the AUTH response will be returned (if card scheme allows the normal authorisation).

NOTE:
The new parameter “3dSecureCheck” value will be overridden by any mandatory card scheme rules. Please consult with LPS for further information. Also, the default value for this new parameter is “N” implying that if the parameter is not sent, the transaction will be directly sent for authorisation provided there is no restriction by the card schemes.

2. REDIRECTING CUSTOMER IF ENROLLED
If the customer is enrolled for 3D SECURE checks, then LPS Payment Gateway will return the information as per table given in Schedule 2C. 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.
If the customer is enrolled for 3D SECURE checks, then LPS Payment Gateway will return the information as per table given in Schedule 2C. 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.

2.1 “BackToMerchantURL” Identifier
The table 2D in post fields section explains the parameters to be sent as part of redirecting the customer to their issuing bank 3dsecure page for authentication.

This contains a field called “BackToMerchantURL” which should be a numeric value as issued by Latpay. Merchants can provide any number of return URL’s to which they’d like to get customers landing back after completing the 3dsecure authentication. Each URL will be whitelisted by Latpay and a unique identifier issued which can then be used in the construction of MD parameter

2.2 LPS OPTIONAL REDIRECTION
LPS as an optional feature can also provide the redirection so that the customer is navigated to the 3D SECURE URL. To use this feature, the merchants should post back response received in schedule 2C as per schedule 2D(o) to the URL specified by LPS. This post must be from the browser and LPS will navigate the customer to their issuing bank 3D SECURE page. IN THIS SCHENARIO, SCHEDULE 2D(o) WILL REPLACE SCHEDULE 2D.

3. 3D SECURE AUTHENTICATION RESPONSE
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.

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 Table 2F.

4. ACQUIRER AUTHENTICATION
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. 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.

Schedule 2A – LPS POST Specification for Payment Request using CARD

Schedule 2A(T) – LPS POST Specification for Payment Request using CARD TOKEN

Schedule 2B – LPS POST Specification for Payment Response

This response will be returned to the merchant if the customer is NOT enrolled for 3D SECURE checks or after passing the 3D SECURE authentication request to LPS payment gateway. The ResponseType will either be 0 or 1. This response indicates the fraud screening or bank response.

Note:

• The entire Schedule 2B is always returned regardless of the transaction status.
• The variables highlighted above in blue are always returned with values regardless of the ResponseType.
• With a ResponseType=0 (fraudscreening status) then the variables in green will be blank. With a ResponseType=1 then all variables will be returned with appropriate values.
• ***CrdStrg_Token: Will be returned only if SCSScheck was set to Y on request post (or) the token itself was posted on request along with SCSScheck set to D.

Schedule 2C – LPS POST Specification for 3D SECURE Enrolment Response

Schedule 2D – Merchant Redirection POST parameters

Schedule 2D(o) – OPTIONAL LPS Redirection POST parameters

On receiving a ResponseType=2 from LPS payment gateway and if the merchant wishes to redirect the customer through LPS they need to post to a predefined LPS URL along with the following hidden post variables.

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

THIS POST MUST BE BROWSER TO SERVER POST

a. LPS RESPONSE TYPE CODES (ResponseType)

b. LPS FRAUD SCREENING RESPONSE CODES (Fraudscreening_status)

NB
***May not be activated for your account(s)
**Internal to LPS, will not be returned on standard response.
*Code returned when strict 3dsecure is enforced - can be enabled on explicit request - default is when card not enrolled, a standard authorisation will be attempted and a 2B response will be returned

c. LPS BANK RESPONSE CODES (Bank_status)

d.CVN/AVS/ZIP RESULT CODES (CVN_Result, AVS_Result & ZIP_Result)

e. UNIQUE BANK CODE AND MESSAGE (bank_code & bank_message)

Testing
The system is currently in production and any testing must be informed well in advance to LPS.

APPENDIX C: MANAGING CARD TOKENS FROM LPS SCSS SYSTEM
When merchants process recredits using SCSS system and generate card tokens corresponding to the customer card details, they can use the token as the reference for all subsequent transactions for that customer. The SCSS system provides two layers of encapsulation and hence it will not be possible to derive card details from token in anyway. To provide options for merchants to manage the details of card tokens, LPS SCSS system provides API which will enable merchants to automatically manage their card tokens. For example, if the expiry dates need to be changed due to card renewal it will not be necessary to post the whole details, but just the new changed details to the manage SCSS API functionality which will selectively update required information.

Currently LPS SCSS manage API provides three functionalities:

• Querying of card details linked to a token;
• Updating of card details linked to a token;
• Deletion of a token;

A1. POSTING PARAMETERS

A2. RESPONSE PARAMETERS

A3. RESPONSETYPE CODE

A4. STATUS CODE

Examples return response

1. sample response for querying existing the card token details.
1.sample response for querying existing the card tokendetails.ResponseType=7&RequestType=SCSS_Q&Requestid=1003&Bill_firstname=Ian&Bill_lastname=Vidamour&Bill_address1=34,Millersstreet&Bill_address2=Northlaneroad&Bill_city=London&Bill_state=Manchester&Bill_country=GB&Bill_zip=SE1&CardBin=420000&CardLast4=0000&Customer_cc_type=VISA&Customer_cc_expmo=11&Customer_cc_expyr=2011&Customer_dc_startmo=&Customer_dc_startyr=&Customer_dc_issue=&CrdStrg_Token=0x1375bb33612cd9cb18c52f33e748f4db&Status=0

APPENDIX D: TRANSACTION STATUS CHECK API
LPS Payment Gateway provides an API call to check the status of transaction sent for authorisation. This API call can be used in the event of communication failures. The API provides option to query for status in Realtime i.e. as soon the transaction is submitted. Due to security reasons, there is a threshold of ten minutes within which the same transaction should not be queried, or else a prescreening code will be returned.

D1. POSTING PARAMETERS

D2. POSTING PARAMETERS

D3. LPS Response Type Codes (responsetype)

D4. Response Codes (authstatuscheck_status)

D5. LPS Transaction Response Codes (transaction_status)

NB:
*** May not be activated for your account(s)
** Internal to LPS, will not be returned on standard response.
*Code returned when strict 3dsecure is enforced - can be enabled on explicit request - default is when card not enrolled, a standard authorisation will be attempted and a 2B response will be returned

APPENDIX B: Additional Post Response Fields

HPS WORKFLOW
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

• When a shopper is ready to pay for their goods, the merchants website should submit the order details to our hosted payment page.
• The shopper will then be taken to the LPS payment page to enter their payment details, such as credit/debit card details.
• 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.
• 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

3D SECURE
The LPS HPS Payment page is integrated with 3dsecure transaction payment processing. The merchant can indicate if the transaction should be processed as 3DSecure by setting theappropriate flag when redirecting the customer to the HPS payment system.

SECURE CARD STORAGE SERVICES (SCSS)
LPS HPS system is also linked with “Secure Card Storage Services (SCSS)” system which will help merchants to comply with PCI DSS audit requirements by removing the necessity to store card details in their system. SCSS system reduces the overhead of storing, managing and transmitting credit card details and card holder data. LPS HPS standard redirection post fields provide an option to flag a transaction to be part of SCSS and it automatically stores the card details and a corresponding token is returned in the response.

The encryption functionality works as follows:
a. Merchant should concatenate the following fields in the same order:

• currencydesc
• amount
• merchant_ref_number
• secret key

PAYMENT CALLBACK NOTIFICATION
LPS HPS system provides payment callback notification which effectively calls a listening URL at merchant server as soon as a transaction is completed. This helps merchants to get notified instantly of transaction statuses instead of relying on customer getting redirected back to their server along with status fields. Though this is optional, LPS strongly recommends merchants to enable this feature so that in cases where customer accidentally closes the browser after transaction is completed at LPS HPS, merchants are still able to update the account details before customer returns to the site.

However, it is important for merchant NOT to have long business processes running on this listening URL. LPS HPS effectively waits only 30 seconds for the notification process to complete.

Merchant must quickly respond back the response string “RECEIVED OK” as soon as the notification is received. They should then proceed with updating their business process asynchronously. The reason being, since customer are effectively held in LPS HPS whilst notification is being delivered, it’s important for Merchant to respond quickly, so that we can then start the process of returning customer back to merchant website. If LPS HPS doesn’t get the response string within 30 seconds, it closes the connection and marks the notification as failed. However, we will still redirect the customer back to merchant site along with the usual response fields.

MULTILANGUAGE SUPPORT AND AMOUNT FORMAT
LPS HPS System support Multilanguage display wherein the payment page can be customised and displayed in the language of choice requested by merchant. The merchant can capture the culture locale of customer and accordingly can display the payment page. The language required to be displayed is to be sent as a request parameter when sending the initial form post request.

It is important to understand the implications of culture format on the amount field. Different cultures format the amount differently.

When sending the amount field on the initial post, it is very important that the amount is formatted as “culture independent” which uses decimal point for separating the major and minor units. For e.g. EUR 500.50, SEK 2575.75 etc.

Any request to use other languages on the payment page will be handled only after the request is received by the main payment form and thus it is important that when submitting the amount field, it is not formatted according any specific locale but always using decimal point with 2 decimal digits.

For more information on language supported, please refer to Appendix D.

FUNCTIONAL FLOW DIAGRAM

INTEGRATION IN DETAIL
NB. For questions or help at any stage of integration, please send an email to technical@lpsmail.com

OVERVIEW
Integrating with LPS Hosted Payment System is a very simple process. The points below describe the process of setting up an integration using a sample HTML form.

ORDER DETAILS TO LPS HPS
Order details submission from merchant to LPS HPS is simply a HTML form with a number of post fields. It should contain a list of mandatory fields as specified in Appendix A “Authorisation Post Fields & Response Fields”. It can also contain a range of optional fields. The merchant system should “POST” this form to the LPS HPS URL when the customer has selected to proceed with making payment on merchant site.

A sample order details submission form is given below:

CARDHOLDER DETAILS CAPTURE
The HPS will display a payment page to the customer on successful redirection by the merchant using the order details form. The HPS will first authenticate to make sure the merchant is validated before allowing the payment page to be shown to customer. The customer will be able to enter the card details and to verify his purchase details. Finally, once all fields have been entered the customer will be able to make the payment.

PAYMENT PROCESSING STATUS
Once customer has clicked to pay for the transaction, the HPS system will send the request to the Acquiring bank and wait for authorisation response. The customer browser will NOT be redirected, and it will be server-to-server synchronous post request send to bank. Once receiving the response, HPS will display the status of the transaction result

PAYMENT CALLBACK NOTIFICATION
This is a feature in HPS. If the merchant has opted for payment callback notification, the HPS will automatically call a URL on the merchant server and post transaction status fields. This will make sure the merchants back office system is updated directly on response from the HPS and is not reliant on customer returning to merchant website along with the status. Merchant notification URL should quickly respond with “RECEIVED OK” on receiving the notification. An email confirming the payment authorisation will also be sent out to the customers on all successful authorisation requests.

CUSTOMER REDIRECTION BACK TO MERCHANT SITE
Once the transaction has been processed, the customer will be able to navigate back to merchant site from the HPS. The transaction status post fields will be posted back along with the redirection. This process also signals the end of transaction.

INFORMATION TO BE SUPPLIED BY MERCHANT
The following information is required:

• User name & Password:
  The user name and password used for authentication on the return post from the LPS server to the merchant server.
• IP address of server:
  The IP address of the merchant web server needs to be provided. Please notify LPS before changing your IP address.
• Technical Contact:
  Technical contacts details.
• Email address for Sending Email receipts:
  Please provide the “sent from” e-mail address for e-mails sent to customers. i.e. orders@merchant.com.
• Email Address for Receipt of Email receipts:
  The merchant is Bcc’d on all receipts sent to customers. Please provide an e-mail address for these mails to be sent to. E.g.accounts@merchant.com
• Secret key for generating one-way hash transaction key post field:
  
  

TESTING
Once the relevant information has been supplied to LPS, a test account will be created. The details of which will be returned by email to the merchant.

All test transactions should be sent to the URL as specified by LPS. The LPS test platform will respond, as it will do in a live environment.
The following rules must apply to testing:

• Use CC numbers as given in the test cards document.
• Use any expiry date but must be valid i.e. a date in the future
• Use any CVC code but must be valid i.e. three digits in length.

APPENDIX A: MERCHANT POSTED FIELDS TO LPS HOSTED PAYMENT SYSTEM

APPENDIX B: POSTED FIELDS FROM LPS HOSTED PAYMENT SYSTEM TO ECOMMERCE SYSTEM

APPENDIX C: POSTED FILEDS FROM LPS HOSTED PAYMENT SYSTEM TO REDIRECT URL

APPENDIX D: Language codes

APPENDIX E: LPS RESPONSE CODES

APPENDIX F: UNIQUE BANK CODE AND MESSAGE (BANK_CODE & BANK_MESSAGE)

INTRODUCTION
Lateral Payment Solutions provide an online credit card/debit card processing solution for e‐commerce businesses. We provide a highly sophisticated fraud screening process to reduce the risk posed to online merchants in the ‘card not present’ environment. 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 explains the technical integration requirements and procedures. It is of a technical nature and should be read as such.

SECURE CARD STORAGE SERVICES (SCSS)
The SCSS system can be used as a standalone system wherein merchants can add cards and generate mapped tokens independently to transactions. Alternatively, the SCSS is also linked with both authorisation & credit systems of LPS payment gateway wherein the merchants have the option to store the card number and generate token at the point of transaction processing.

SCSS AS A STANDALONE SYSTEM:
In the case of a standalone system, the merchants can send customer billing details with card number to generate a token.The system will store the details and will generate a unique token corresponding to the customer details linked specifically to the merchant.

The generated token can then be used in a transaction authorisation or OCT request by passing the token details and specifically setting a flag to indicate to the LPS payment gateway that a card token is used.

If a generated token details needs to be modified or to be validated again, the manage SCSS system can be used.

Once a token is generated the system flow will be as follows:
a. Merchant sends normal authorisation request with SCSS flag set to D (implying already done).
b. If SCSS flag is set to D, then instead of card number, the SCSS token should be posted.

SCSS AS A MODULE TO AUTH/CREDIT SYSTEM:
LPS Authorisation API system is also linked with “Secure Card Storage Services (SCSS)” system which will help merchants to comply with PCI DSS audit requirements by removing the necessity to store card details in their system.

MANAGE SCSS SYSTEM:
In the event the billing details or card details needs to be updated, then merchants can make use of manage SCSS subsystem API to update or delete the card details.

The way the system works is as follows:

• Merchants send normal authorisation request with SCSS flag set to Y.
• A unique identifier is generated and returned along with the authorisation response.
• The unique identifier acts as the reference for all subsequent transactions
• The identifier also references complete billing details of the card holder. Hence apart from the card The identifier also references complete billing details of the card holder. Hence apart from the card

Once a token is generated the system flow will be as follows:

• Merchant sends normal authorisation request with SCSS flag set to D (implying already done).
• If SCSS flag is set to D, then instead of card number, the SCSS token should be posted.

Points to note when posting token with SCSS flag set to D:

• When posting with SCSS flag set to D, the token must always be posted or else the transactions will be rejected with a prescreening code.
• If card number is also sent along with SCSS flag set to D and token also present, card number will be ignored.
• If billing details as well as other card details are posted along with token, the details posted in the request will take precedence over the details stored in SCSS for that token. Hence the posted values will be utilised for authorisation processing. However, note that the details stored in SCSS will not have been updated. If it should be updated, then a separate update request on manage SCSS system API should be sent.

The unique identifier is of no value to anyone who attempts to steal sensitive information because the secure credit card information can never be obtained by using the identifier. Technically, the identifier is a hash pointer reference to a token value which is then referenced to the card holder data in our data store. Hence our SCSS system provides robust security in protecting card holder information.

SCSS system comprises of four main building blocks:

a. Card Token Generation:
This phase consists of the generation of unique identifier for the card holder data. The unique identifier is linked to the merchant account issued by LPS. In case of standalone SCSS system, if the card number already exists on the system then the system will reject, and new token generation will fail. However, in case of SCSS linked to authorisation, if an existing card number is used, then the same identifier will be returned if the card details has been previously posted by the client and an identifier generated previously.

b. Card Token Details Update:
This phase consists of an independent API which will enable merchants to be in control of their secure card data. In the event the card details need updating, for example if the expire dates have changed due to card renewal or the customer’s address details have changed. The merchants can send the token as well the new details which will be automatically updated into the SCSS system. All the usual process of validating the credentials will be necessary before the details can be updated.

c. Card Token Details Query:
This phase is similar to “Token Update” phase, except that it will just return the details stored for that token rather than altering any information. This will be useful if the merchants wish to recheck the details stored in our SCSS system before posting transactions.

d. Card Token Delete:
If customer details are to be removed due to various reasons such as customer has closed their account or audit retention policy or customer deemed fraudulent etc, merchants can send the “Token Delete” request and the card details will be completely removed and cannot be used further.

APPENDIX A: NEW CARD TOKEN GENERATION

A1. POSTING PARAMETERS

A2. RESPONSE PARAMETERS

Note:
The fields in blue will always be returned.
The fields in green will be returned if request is successful, i.e., Status=0

APPENDIX B: MANAGING CARD TOKENS FROM LPS SCSS SYSTEM
When merchants process recredits using SCSS system and generate card tokens corresponding to the customer card details, they can use the token as the reference for all subsequent transactions for that customer. The SCSS system provides two layers of encapsulation and hence it will not be possible to derive card details from token in anyway. To provide options for merchants to manage the details of card tokens, LPS SCSS system provides API which will enable merchants to automatically manage their card tokens. For example, if the expiry dates need to be changed due to card renewal it will not be necessary to post the whole details, but just the new changed details to the manage SCSS API functionality which will selectively update required information.

Currently LPS SCSS manage API provides three functionalities:

• Querying of card details linked to a token;
• Updating of card details linked to a token;
• Deletion of a token;

B1. POSTING PARAMETERS

B2. RESPONSE PARAMETERS

Note: The fields in blue will always be returned. The fields in green will be returned if request is successful, i.e., Status=0

APPENDIX C: RESPONSE CODES

C1. RESPONSETYPE CODE

C2. STATUS CODE

Examples return response

1. sample response for querying existing the card token details.
ResponseType=7&RequestType=SCSS_Q&Requestid=1003&Bill_firstname=Ian&Bill_lastname=Vidamour&Bill_address1=34,Millersstreet&Bill_address2=Northlaneroad&Bill_city=London&Bill_state=Manchester&Bill_country=GB&Bill_zip=SE1&CardBin=420000&CardLast4=0000&Customer_cc_type=VISA&Customer_cc_expmo=11&Customer_cc_expyr=2011&Customer_dc_startmo=&Customer_dc_startyr=&Customer_dc_issue=&CrdStrg_Token=0x1375bb33612cd9cb18c52f33e748f4db&Status=0

APPENDIX D: SECURE CARD DATA SFTP TRANSFER
As an alternative option to generate card tokens, merchants can also use our secure card data SFTP transfer facility, wherein they will be able to bulk import customer card details. The generated tokens corresponding to the imported data will be appended to the file and returned through the same channel. On the outbound file, the original full details will be stripped out for security.

This feature provides a convenient way to securely generate tokens for existing payment instructions already present in another secure system and where API call additional development is an overhead.

The preferred format of file import will be csv and the column header and values are as follows.

INTRODUCTION
The purpose of this technical specification is to give an in‐depth description of the Lateral Payment Solutions (LPS) Enterprise Payment Gateway – Card Processing API. LPS Card Gateway is a proprietary platform for processing payments online. It exposes multiple API’s for performing various types of online financial transactions. This specific document explains the Card Processing API which enables payments online using debit and credits cards.

The platform data exchange is a secure and yet simple name/value pair data format based on HTML POST form‐URL encoded data. The API operates on a securely authenticated request / response method where an authorised client instructs the gateway to perform an operation and the gateway replies back with the status of the operation.

TRANSACTION FLOW DIAGRAM
A simple transaction process flow is depicted in fig‐1 below.

1. CUSTOMER TO MERCHANTS WEBSITE

   Customer confirms payment request in a client app or browser securely submitted back to merchant web server;

2. MERCHANTS SERVER TO LPS SERVER

   Opens web request containing all the necessary card data and card holder details submitted over secure encrypted SSL;

3. LPS SERVER TO MERCHANTS SERVER

   LPS gateway performs data, velocity and fraud checks. If any fail, the transaction process is stopped and a failure code is returned;

4. LPS SERVER TO BANK

   The transaction after risk/fraud screening is sent from the LPS gateway to the bank and receives the response back from bank;

5. LPS TO MERCHANTS SERVER

   LPS sends the bank response details to merchant server;

6. MERCHANT SERVER TO END USER

   Merchant updates database and notifies customer of success or failure of the transaction;

7. LPS SERVER TO END USER

   LPS can send an e‐mail receipt to customers where the transaction is successful. Merchant can receive a copy of the e‐mail for customer support or account management purposes;

Card Gateway – API
The LPS Enterprise Payment Gateway – Card Processing API provides a real‐time, synchronous interface to execute debit / credit card transactions. Transaction requests are sent online, in real‐time,using HTTPS (Hypertext Transfer Protocol Secure).

Addresses
Integration Endpoint URL:

• Note: This will be issued along with account credentials after approval.

Production Endpoint URL:

• Note: This will be issued along with account credentials after approval.

HTTP Specification

• Protocol: https
• Method: POST
• Content‐Type: [application/www‐form‐urlencoded] or [application/x‐www‐formurlencoded]

Security/Authentication
All HTTP requests must be sent over SSL, a secure channel should be used. The LPS Payment Gateway does not authenticate the SSL session using a certificate from the client, thus a non‐authenticated SSL session is used. Instead the client is first authenticated using source IP plus a secondary authentication check using the account credentials verification which is sent in the request payload is used to verify before processing.

Integration Steps

Overview
The merchant’s server makes a request through a HTTP POST over a secure SSL connection and receives the result of the processing request as the response to the POST request. The request payload carries the necessary details for processing the payment request and the response contains parameters whose values represent the result of the payment request.

MERCHANT SERVER TO LPS SERVER
To process a payment, request all mandatory fields found in Schedule 2A need to be posted via SSL to LPS payment gateway URL which will be provided by LPS. All communication between LPS and the merchant is via SSL only. The merchant server makes a request through an HTTP POST to the LPS server, LPS receives the payment request, performs fraud screening and returns to the merchant a result of either fraudscreening (failed) or the bank response (if passed fraud screening).

Points to note about the POST to LPS

• LPS provide the merchant_user_id and merchantpwd
• Replace spaces in the user details with +. You do not however have to do a full URL‐encode of the request string.
• Post amounts as 2 decimal places only. Applies to amount field. i.e. 125.03
• A payment request will not be accepted for processing if the mandatory fields in Schedule 2A are missing.
• If a payment request does not contain all the mandatory fields then the system will return the fraudscreening_status value of 9001 and an LPS_Transaction_id of –1.

LPS SERVER BACK TO MERCHANT SERVER
Using the synchronous method your server opens an SSL protected connection to the LPS server and awaits a HTTP response from the server. If the data is sent successfully (HTTP Status 200) you need to retrieve the Response to the payment request. This will be returned as a query string with the variables described in Schedule 2B. Two response types may be returned; either fraud screening failed or bank transaction status.

Points to note about the LPS return POST

• LPS generates a unique transaction id for each transaction. This is returned to the merchant’s server along with the merchant reference number.
• Merchants must use the LPS_transaction_id for any transaction enquiries with LPS
• LPS response includes an id and password in the string for merchant server authentication purposes; this is the user name & password you supply to LPS and is different from the LPS supplied pair in the original post to Schedule 2A.
• If mandatory fields are missing then the system will not accept the transaction for processing. The details will be logged and the system will return a Fraudscreening_status of 9001 & an LPS_transaction_id of –1.

LPS TO END USER
LPS send an e‐mail receipt to the customer for each authorised payment request. The receipt contains all transaction details and an email address for customer enquiries. The email is sent from the merchants chosen address and not from LPS e.g. support@merchant.com. The merchant can receive a copy of the receipt sent to the customer.

Account Setup Process
Once the necessary due diligence has been completed on your application by the LPS compliance team, a test MID will be approved. To setup the test MID, merchants will be asked to provide a set of details which are required by the LPS technical team. This will be communicated at the time of MID setup

Testing & QA
As part of integration verification, merchants will be required to perform a set of test transactions as listed out by the LPS integrations verification team and submit the results. This will be validated and if any tests are not found to be satisfactory, the merchants will be requested to perform the test cases again until all outstanding issues are cleared. Once the integration is signed off, a live production MID approval will need to be obtained.

Going Live
On approval from bank, the live MID will be loaded into LPS payment gateway by LPS tech team and connectivity tests performed to ensure the transactions are processed correctly. A new production account will be issued to merchant which they can seamlessly swap their test account credentials for and initiate live tests. The merchants will need to submit live tests using real card details before they can switch their production traffic to LPS payment gateway.

Technical Support
At any stage during the integration process or beyond, merchants will be able to contact the LPS tech team using a dedicated support email. This email is automatically linked to a ticket queuing system which will generate a support ticket on merchant’s behalf and assigned to LPS Level 1 support team.

APPENDIX A: AUTHORISATION POST FIELDS & RESPONSES Schedule 2A – LPS POST Specification for Payment Request using CARD

SAMPLE REQUEST STRING
Merchant_User_Id=test_merchant_account&merchantpwd=te****s!&merchant_ipaddress=1.1.1.1&customer_firstname=Thirlok&customer_lastname=shankar&customer_phone=1236798848&customer_email=testuser%40lateralpaymentsolutions.com&customer_ipaddress=2.2.2.2&bill_firstname=Thirlok&bill_lastname=Shankar&Bill_address1=34%2c+Millers+street&bill_address2=North+lane+road&bill_city=London&bill_country=GB&bill_state=Manchester&bill_zip=SE1&customer_cc_expmo=11&customer_cc_expyr=2018&customer_cc_number=420000######0000&customer_cc_type=VISA&customer_cc_cvc=000&merchant_ref_number=lpstest123&currencydesc=GBP&amount=0.10

Schedule 2A (T)– LPS POST Specification for Payment Request using CARD TOKEN

SAMPLE REQUEST STRING
Merchant_User_Id=lps_Account&merchantpwd=***&merchant_ipaddress=1.1.1.1&customer_ firstname=Thirlok&customer_lastname=Shankar&customer_phone=1236798848&customer_email= testuser%40lateralpaymentsolutions.com&customer_ipaddress=2.2.2.2&bill_firstname=Thirlok&bill _lastname=Shankar&Bill_address1=Southbank+house&bill_address2=Balck+Prince+road&bill_city=L ondon&bill_country=GB&bill_state=Greater+London&bill_zip=SE1&customer_cc_expmo=11&custo mer_cc_expyr=&customer_cc_cvc=000&merchant_ref_number=lpstest123&currencydesc=GBP &amount=0.10&scsscheck=D&CrdStrg_Token=0xda749cc60382e4af0cfb7e4dbb2ab33139840443

Schedule 2B – LPS POST Specification for Payment Response

Note

• The entire Schedule 2B is always returned regardless of the transaction status.
• The variables highlighted above in blue are always returned with values regardless of the ResponseType.
• With a ResponseType=0 (indicating it’s a fraudscreening response) then the variables in green will be blank. With a ResponseType=1 (indicating it’s a bank response) then all variables will be returned with appropriate values.

SAMPLE RESPONSE STRINGS

Result of fraudscreening failed response (ResponseType=0)

ResponseType=0&LPS_merchant_account=67392733&Merchant_ref_number=*******&Lpsid=test &Lpspwd=test&Fraudscreening_status=1003&Bank_status=&Amount=2&Currency=USD&Bank_tran saction_no=&Bank_authorisation_no=&Bank_date=12/05/2017&Bank_time=14:06&Bank_original_c ode=

Result of bank transaction response (ResponseType=1)

Accepted Sample
ResponseType=1&LPS_transaction_id=67392741&Merchant_ref_number=lpstest123&Lpsid=test&L pspwd=test&Fraudscreening_status=0&Bank_status=00&Amount=2&Currency=GBP&Bank_transacti on_no=67392741&Bank_authorisation_no=test&Bank_date=12/05/2017&Bank_time=14:06&Bank_ original_code=

Rejected Sample
ResponseType=1&LPS_transaction_id=40473433&Merchant_ref_number=lpstest123&Lpsid=test&L pspwd=test&Fraudscreening_status=0&Bank_status=05&Amount=0.1&Currency=GBP&Bank_transa ction_no=678691488&Bank_authorisation_no=&Bank_date=11/06/2012&Bank_time=12:08&Bank_ original_code=&AVS_Result=0&ZIP_Result=1&CVN_Result=0&CardBin=420000&CardLast4=2345

APPENDIX B: ADDITIONAL POST RESPONSE FIELDS
Depending on the merchant’s account setup status, LPS enterprise payment gateway can respond with extra fields in addition to the fields specified in the “schedule 2B”, which is the response to confirm the results of the transaction. These fields will NOT be enabled by default and cannot be guaranteed to be returned even if enabled. Depending on the outcome of the transaction and on the Acquiring bank on which the merchant is setup, these fields can be returned. LPS will continue to add these additional response fields as required in future releases/upgrades of the gateway. If a merchant would like to receive these additional fields they should contact LPS.

APPENDIX C: LPS RESPONSE CODES

"ResponseType" response Codes

“Fraudscreening_status” response codes

*** These codes may not be active for your account(s)

“Bank_status” response codes

CVN/AVS/ZIP (“CVN_Result”, “AVS_Result” & “ZIP_Result”) response codes

NB. The CVN/AVS/ZIP result fields above can also be returned blank or empty which should be treated as “Not verified by bank”

BankIdentifier codes (“BankIdentifier”)
This will be confirmed at the time of going live after MID approval with the respective acquiring bank.

Unique Bank code and Message (“bank_code” & “bank_message”)

APPENDIX D: TRANSACTION STATUS CHECK API
LPS Payment Gateway – card processing provides an API call to check the status of transactions sent for authorisation. This API call can be used in the event of communication failures. The API provides the option to query the status soon after the transaction is submitted. Due to security reasons, there is a threshold of ten minutes within which the same transaction should not be queried, or else a prescreening code will be returned.

Schedule 2G – LPS POST Specification for Status Check Request

Schedule 2H – LPS POST Specification for Status Check Response

*** Only returned if transaction being checked is a token transaction

Status Check “responsetype” response codes

Status Check “authstatuscheck_status” response codes

Status Check “transaction_status” response codes

*** These codes may not be active for your account(s).

APPENDIX E: MANAGE CARD TOKENS
When merchants process recredits using SCSS system and generate card tokens corresponding to the customer card details, they can use the token as the reference for all subsequent transactions for that customer. The SCSS system provides two layers of encapsulation and hence it will not be possible to derive card details from token in anyway. To provide options for merchants to manage the details of card tokens, LPS SCSS system provides API which will enable merchants to automatically manage their card tokens. For example, if the expiry dates need to be changed due to card renewal it will not be necessary to post the whole details, but just the new changed details to the manage SCSS API functionality which will selectively update required information. Currently LPS SCSS manage API provides three functionalities:
a. Querying of card details linked to a token;
b. Updating of card details linked to a token;
c. Deletion of a token;

Schedule 2I – LPS POST Specification for Manage Tokens Request

*** Optional – To be sent only when the updating the corresponding field value stored in LPS Token System.

Schedule 2J – LPS POST Specification for Manage Tokens Response

Manage Tokens “ResponseType” response codes

Manage Tokens “Status” response codes

In the event the billing details or card details needs to be updated, then merchants can make use of manage SCSS subsystem API to update or delete the card details.

The way the system works is as follows:

• Merchants send normal authorisation request with SCSS flag set to Y.
• A unique identifier is generated and returned along with the authorisation response.
• The unique identifier acts as the reference for all subsequent transactions.
• The identifier also references complete billing details of the card holder. Hence apart from the card details, billing details also will not be necessary when posting the identifier.

Once a token is generated the system flow will be as follows:

• Merchant sends normal authorisation request with SCSS flag set to D (implying already done).
• If SCSS flag is set to D, then instead of card number, the SCSS token should be posted.

Points to note when posting token with SCSS flag set to D:

• When posting with SCSS flag set to D, the token must always be posted or else the transactions will be rejected with a prescreening code.
• If card number is also sent along with SCSS flag set to D and token also present, card number will be ignored.
• If billing details as well as other card details are posted along with token, the details posted in the request will take precedence over the details stored in SCSS for that token. Hence the posted values will be utilised for authorisation processing. However, note that the details stored in SCSS will not have been updated. If it should be updated, then a separate update request on manage SCSS system API should be sent.

The unique identifier is of no value to anyone who attempts to steal sensitive information because the secure credit card information can never be obtained by using the identifier. Technically, the identifier is a hash pointer reference to a token value which is then referenced to the card holder data in our data store. Hence our SCSS system provides robust security in protecting card holder information.

SCSS system comprises of four main building blocks:

a. Card Token Generation:

This phase consists of the generation of unique identifier for the card holder data. The unique identifier is linked to the merchant account issued by LPS. In case of standalone SCSS system, if the card number already exists on the system then the system will reject and new token generation will fail. However, in case of SCSS linked to authorisation, if an existing card number is used, then the same identifier will be returned if the card details has been previously posted by the client and an identifier generated previously.

b. Card Token Details Update:

This phase consists of an independent API which will enable merchants to be in control of their secure card data. In the event the card details need updating, for example if the expire dates have changed due to card renewal or the customer’s address details have changed. The merchants can send the token as well the new details which will be automatically updated into the SCSS system. All the usual process of validating the credentials will be necessary before the details can be updated.

c. Card Token Details Query:

This phase is similar to “Token Update” phase, except that it will just return the details stored for that token rather than altering any information. This will be useful if the merchants wish to recheck the details stored in our SCSS system before posting transactions.

d. Card Token Delete:

If customer details are to be removed due to various reasons such as customer has closed their account or audit retention policy or customer deemed fraudulent etc, merchants can send the “Token Delete” request and the card details will be completely removed and cannot be used further.

Schedule 2B – LPS Common Post Specification for Payment Response

Schedule 2C – LPS POST Specification for Enrolment Response

Schedule 2D – LPS POST Specification for ACS Redirect Request

Schedule 2E – LPS POST Specification for ACS Redirect Response

Schedule 2F – LPS POST Specification for Auth Request

Schedule A – LPS Post Specification for Payment Request

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

Country code: KZ, RU, UA
Currency: EUR, RUB, USD

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

TrustPay works for the following country code/currency combinations:

Country code: BG, CZ, DK, EE, FI, GR, HU, LV, LT, NO, RO, SK, SI, SE
Currency: EUR, BGN, CZK, DKK, HUF, NOK, RON, SEK

The currencies available to you may depend on your contract.

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

EPS works for the following country code/currency combinations:

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

iDEAL only works for the following country code/currency combinations:

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

POLi only works for the following country code/currency combinations:

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

For standard request fields check Schedule 2A. Przelewy24 only works for the following country code/currency combinations:

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

Schedule B – LPS Post Specification for Payment Response

There are no specific response fields for this payment method. For standard response fields check Schedule 2B.

Schedule A – LPS Post Specification for Payment Request

Country code: International
Currency: International

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

There are no specific input parameters for this payment method. For standard input parameters check Schedule 2A.

Country code: AT, BR, CA, CO, CR, DE, MX, NI, PA, PE, ES, NL, US
Currency: EUR, USD

Schedule B – LPS Post Specification for Payment Response

There are no specific response fields for this payment method. For standard response fields check Schedule 2B.

Schedule A – LPS Post Specification for Payment Request

Schedule B – LPS Post Specification for Payment Response

There are no specific response fields for this payment method. For standard response fields check Schedule 2B.

Schedule A – LPS Post Specification for Payment Request

Country code: International
Currency: International

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

For standard request fields check Schedule 2A. Boleto only works for the following country code/currency combinations:

Schedule B – LPS Post Specification for Payment Response

Schedule A – LPS Post Specification for Payment Request

For standard request fields check Schedule 2A. TicketOnline (Raberil) only works for the following country code/currency combinations:

Schedule B – LPS Post Specification for Payment Response

There are no specific response fields for this payment method. For standard response fields check Schedule 2B.