Custom Pluggable Payment Gateways

SmithCart > Payment Gateways
SmithCart is pre integrated with most of the popular payment gateways you will ever need for your e-commerce site, but you may have the requirement to work with a payment gateway provider that is not currently integrated with Smith Cart.  If you need a gateway that is not currently integrated with Smith Cart you have the following two options:
 

Custom Direct Payment Gateway Web Service

The Direct Custom Payment Gateway Web Service option allows you to plug-in any payment gateway provider you desire. 
 
To configure the “Custom Direct Web Service” do the following:
 
  1. Go to the Store Admin Menu and click the “Payment Setup” button
 
 
  1. Click the “Payment Gateways” button on the top menu
  2. Select the “Custom Direct Web Service” from the gateway dropdown list
 
 
 
When the “Custom Direct Web Service” gateway option is selected in the payment gateway setup screen the following required fields are displayed:
 
Merchant ID - This is a required field for the gateway.  Merchant ID is a unique id that identifies you with the gateway provider. 
 
Password - This is the gateway password and is a required field. 
 
URL – Enter the URL of the payment gateway you want to post the credit card transaction to. 
 
For example:   https://secure.myservice.com/processcard.aspx
 
The custom web service gateway option performs an https post operation to the URL you enter in the “URL” field.  A secure SSL connection is initiated from the cart to the payment gateway URL to pass transaction data in name/value pairs. It is a standard https post “Request – Response” with hidden name value pairs (NVP).  The following are the required fields (parameters) in the request and response between the cart and the payment gateway:
 

Parameters Posted by SmithCart to the Payment Gateway

  • Merchant ID
  • Password
  • Mode  =  "TEST" or “LIVE”
  • Trans_Type = "SALE"
  • Credit_Card_Number       
  • Expiration_Date
  • CVV2_Code
  • Amount
  • Billing_Name
  • Address
  • City
  • State
  • Zip
  • Country

Response Parameters SmithCart expects back from the Payment Gateway

  • AuthCode
  • Status (APPROVED or DECLINED)
  • TransID
  • Notes
  • Amount
 
The cart expects the transaction response parameters from the payment gateway to be returned as an ampersand ("&") delimited string.  The gateway response parameters provide information about the status of a transaction whether it was accepted or declined as well as other information about the transaction.
 
The cart receives and parses the transaction response from the payment gateway and displays the results to the customer.
 
The custom gateway/web service option in the cart uses the standard WebRequest Class http://msdn.microsoft.com/en-us/library/system.net.webrequest.aspx in dot net to communicate with your payment gateway.  The integration and communication between the cart and the payment gateway is very similar to the Authorize.Net AIM payment gateway integration here http://www.authorize.net/support/AIM_guide.pdf
 
 

Hosted Payment Gateway Web Service

The Hosted Custom Payment Gateway Web Service option allows you to plug-in any hosted payment gateway provider you desire.  To configure the “Custom Hosted Web Service” do the following:
 
  1. Go to the Store Admin Menu and click the “Payment Setup” button
 
 
  1. Click the “Payment Gateways” button on the top menu
  2. Select the “Custom Hosted Web Service” from the gateway dropdown list
 
 
 
When the “Custom Hosted Web Service” gateway option is selected in the payment gateway setup screen the following required fields are displayed:
 
Merchant ID - Merchant ID is a unique id that identifies you with the gateway provider and is used for authentication.  Merchant ID should be a required field for the gateway. 
 
Password - This is the gateway password and should be a required field.  Used for security authentication. 
 
URL – Enter the URL of the hosted payment gateway you want SmithCart to transfer to when the user checks out in SmithCart and clicks the submit button to make payment.
 
For example:   https://secure.mypaymentform.com/payonline.aspx
 

Redirect and Post

 
The SmithCart custom hosted web service gateway option will perform a “Response.Redirect” to the URL that you have configured in the “URL” field and pass the payment parameters as hidden fields in the form post.
 
SmithCart will communicate with the custom hosted payment gateway using a standard https “Request – Response” form post with hidden name value pairs (NVP) fields. 
 
The following are the required fields (parameters) in the request and response between SmithCart and the payment gateway:
 

Parameters Posted by SmithCart to the Payment Gateway

  • merchant_id
  • password
  • test_mode  -  "1" for test mode.  “0” for live.
  • trans_type - "creditcard"
  • return_url  - The url that the customer will be redirected to after they process a payment.
  • first_name
  • last_name
  • address1
  • address2
  • city
  • state
  • country
  • postalcode
  • email
  • telephone
  • company_name
  • order_id – SmithCart Order ID
  • ship_amount
  • tax_amount
  • order_total
  • product: {id},{name},{quantity},{amount} in json format
 
Example:
 
{product=[{sku:1234, name:ProductABC, quantity:1, amount:100.00}, {sku:2222, name:ProductXYZ, quantity:1, amount:200.00}]}
 

Transaction Response

The Hosted Payment Gateway should redirect buyers back to SmithCart after a successful payment.
 
The Hosted Payment Gateway gets the URL to redirect the buyer to in one of two ways:
 
  1. By using the "redirect_url" parameter passed by SmithCart in the original post redirect
  2. By allowing merchants to configure a URL in there gateway virtual terminal where buyers will be redirected to after a successful payment.
 
SmithCart will accept response parameters posted from the gateway as form variables.
 

Response Parameters SmithCart expects back from the Hosted Payment Gateway

  • status - "00000" or "Approved" indicates payment success.  Any other value indicates decline.
  • payment_type (CreditCard, ACHChecking, ACHSavings)
  • auth_code - Authorization code returned from the processor
  • trans_id - Transaction ID returned from the processor
  • notes - In the case of a declined transaction returns the reason for the decline.
  • amount - Amount of the transaction authorized
 

Custom Payment Gateway Architecture

The Smith Cart custom payment gateway options allow you to plug in payment gateways that are not currently pre integrated with Smith Cart. 
 
The following diagram shows the basic flow of control when using the Smith Cart custom gateway option to plug in a new payment gateway:
 
 
 
 
The following items correspond to the numbers in the diagram above:
 
1. Your site running Smith Cart sends a Pay request to “Your Custom Web Service”.
 
2. Your Custom Web Service receives the request from Smith Cart and does the following:
 
            - Translates the fields posted by Smith Cart to the field names required by the payment gateway.
            - Builds a request to the new payment gateway you want to communicate with.
 
- Sends a request to the payment gateway using the communication mechanism outlined in the payment gateway integration guide.  Most payment gateways use one of the following communication mechanisms to send and receive information:
  • Http post with hidden form fields
  • Http post with querystring parameters
  • Soap Xml web service
  • Restful web service
  • Method calls to a DLL provided by the payment gateway
 
3. The payment gateway processes the transaction and responds with an approval or a decline.
 
4. Your Custom Web Service receives the response from the payment gateway and builds the response back to Smith Cart using the response fields that Smith Cart expects to receive. 
 
Please Note:  The box titled “Your Custom Web Service” in the diagram above is a program that you develop and can be in any language you desire (C#, VB, PHP, Java, etc.).  Your custom web service functions as a middle man between Smith Cart and the payment gateway you want to integrate with.
 
The reasons that Smith Cart cannot communicate directly with the new payment gateway and you need to develop your own web service to marshal transactions between Smith Cart and the payment gateway are as follows:
 
- Each payment gateway uses a different communication mechanism (i.e.  http post, soap xml, restful web service, etc.)
 
- Each payment gateway uses different naming conventions for the request and response fields that are send back and forth.