Getting Started

This documentation is designed for system designers and web application developers who plan to integrate with the SmartRoute interface to perform e-Commerce.

Purpose 

The purpose of this documentation is to provide you with the necessary help after you have signed up through the SmartRoute system. 

The SmartRoute system is your integration point with payment gateways to handle electronic transactions (payment, refund, confirm) from different payment methods (credit card, debit card). The system uses the HTTPS Post as a programming interface to perform the transactions. 

This documentation describes the format for sending transactions, and the corresponding received responses. 

Prerequisites

• You have a contract with Payment Gateway as an e-Commerce Merchant.
• You have a contract with SmartRoute as an Integration point with the Payment Gateways.
• You have been provided with a SmartRoute profile to generate Authentication Tokens used for integration. 
• You have a profile on the Payment Gateway side.

Authentication Token & Secure Hash

Data Integrity

To guarantee request or response data integrity, the system generates a Secure Hash for each message. All message fields are used to create a Secure Hash. 

After receiving a request or response message, the receiver recreates the Secure Hash from the received message parameters and compares it with the Secure Hash already sent within the message. 

Authentication

The system generates a unique Authentication Token for you. This Authentication Token is used as part of the Secure Hash value and is known only to your application and SmartRoute. Accordingly, the message recipient (you or SmartRoute) includes the Authentication Token value when generating the Secure Hash value.

You must make sure to:

• Store the Authentication Token in a secure place as a secure database or file. 
• Not store the Authentication Token within the source code of an ASP, JSP, or any web page standing the chance of being accessed or viewed via the web. 

Transaction Flow

Request Flow 

• You prepare the request message which includes request fields based on the message ID (For example, Sale, Inquiry Status).
• You generate the Secure Hash using request parameters and Authentication Token value.
• You send the request that includes the Secure Hash to SmartRoute. 
• SmartRoute System will retrieve the Authentication Token value stored for you at SmartRoute side after receiving the request. 
• SmartRoute System Regenerates Secure Hash using received request parameters and Authentication Token stored at SmartRoute System. 
• SmartRoute compares generated Secure Hash with received Secure Hash; if values mismatch, the request will be rejected. Else SmartRoute will continue processing the request. 

Response Flow 

• SmartRoute System prepares responses for your requests. 
• SmartRoute System generates Secure Hash using response parameters and Authentication Token stored at SmartRoute side. 
• SmartRoute sends the response, including the Secure Hash to you. 
• Upon receiving the response, you will use the response parameter and Authentication Token value stored at your application to regenerate Secure Hash for response 
• If the values mismatch, you compare the generated Secure Hash with the received Secure Hash. The response will be rejected. Else your application will continue processing responses.
  
  
  Note: You can arrange with SmartRoute’s support team to include extra parameters (dynamic fields) in the messages’ requests/responses if the need arises. These dynamic fields must be included in the secure hash generation.

  
  

How to Start 

Merchants integrating with SmartRoute have the flexibility of choosing the needed messages to conduct their transactions from a varied selection of messages based on their platform (e.g. Native Mobile App or a Web Application) and their preferred communication model (upon arrangement with the SmartRoute’s Support Team), as follows: 

• If you are integrating a web application and need to have complete control of the payment details capturing process, then the following messages must be considered in the integration:

• API Payment: This message is used to perform a payment. 
• API Pre-Auth: This message is used to perform a Pre-Authorization Transaction. 
• API Approve: Complement message and not to be used alone. Used to finalize some API Payment transactions. 
• Refund: This message is used to refund a transaction. 
• Inquiry: This message is used to inquire about the status of a transaction. 
• Completion: This message is used to complete a Pre-Authorization Transaction. 

• If you are integrating a native mobile application and need to have complete control of the payment details capturing process, then the following messages must be considered in the integration: 

• API mPayment: This message is used to perform a payment. 
• API Approve: Complement message and not to be used alone. Used to finalize some API mPayment transactions. 
• Refund: This message is used to refund a transaction. 
• Inquiry: This message is used to inquire about the status of a transaction. 

•  If you are integrating a web application and need SmartRoute to handle the entire payment details capturing process without any capturing at your side, then the following messages must be considered in the integration: 

• Redirect Payment: This message is used to perform a payment. 
• Redirect Pre-Authorization: This message is used to perform a Pre-Authorization. 
• Refund: This message is used to refund a transaction. 
• Inquiry: This message is used to inquire about the status of a transaction. 
• Update Notification: This message is used to notify your transaction status. It is helpful if the customer closes the browser before being redirected back to your site. 
• Completion: This message is used to complete a Pre-Authorization Transaction.  

• If you are integrating a web application and need to be in control of the design and hosting of the payment page, which posts silently to SmartRoute directly from the customer’s browser, then the following messages must be considered in the integration: 

• Direct Post Payment: This message is used to perform payment -  Redirect Pre-Authorization: This message is used to perform a Pre-Authorization 
• Refund: This message is used to refund a transaction. 
• Inquiry: This message is used to inquire about the status of a transaction.
• Update Notification: This message is used to notify you of the status of the transaction. It is helpful if the customer closes the browser before being redirected back to your site. 
• Completion: This message is used to complete a Pre-Authorization Transaction.