When possible, you should always use a gateway that is already supported by the system. The following instructions show how to integrate your own custom hosted payment gateway. A hosted payment is the type where the customer gets redirected to your hosted page for payment as opposed to entering their payment information on the checkout page.

Start by enabling the Custom hosted payment under Configuration > Payment settings. You will need to provide the following information:

• Gateway URL - The Storefront will transmit information to this URL.
• Username - This field is optional if you want to authenticate the connections to your gateway.
• Password - This field is optional if you want to authenticate the connections to your gateway.
• Passphrase - This field is optional if you intend to use the notification callback.
• Request method - GET or POST method.

Transaction flow

When the customer places the order, the following flow occurs:

1. The Storefront makes a request to your Gateway URL using the GET or POST method. The following key-value pair information is transmitted in application/x-www-form-urlencoded format.
    

   Name	Type	Description
   Amount	Decimal	The amount to charge. e.g 12.78
   BillingCity	String
   BillingCountryCode	String	The ISO 3166-1 2-letter country code. e.g. "US" for United States.
   BillingEmail	String
   BillingFirstName	String
   BillingLastName	String
   BillingPhone	String
   BillingPostalCode	String
   BillingStreet	String
   BillingSubdivisionCode	String	The ISO 3166-2 subdivision code. e.g "US-CA" for California.
   BillingUnit	String
   CurrencyCode	String	The primary 3-letter ISO currency code. e.g. "USD"
   CustomerID	String	The customer identifier in the Storefront, i.e. the UserID.
   CustomerIPAddress	String	e.g. "88.88.88.88"
   FailureReturnUrl	String	The URL to redirect the customer back if payment failed or cancelled.
   NotificationUrl	String	The callback URL to return the result asynchronously.
   OrderID	String	The system order number. e.g. "INV-1209"
   Password	String	The password as entered in the credentials to authenticate the connection to your service.
   ReferenceID	String	The reference string should be reflected back as-is if you are calling back the Notification URL.
   SuccessReturnUrl	String	The URL to redirect the customer back if payment is successful.
   UICultureCode	String	The user interface culture code. e.g. "en-US"
   Username	String	The username as entered in the credentials to authenticate the connection to your service.

2. Your Gateway URL page should respond back with the following key-value pair information in application/x-www-form-urlencoded format.
    

   Name	Type	Description
   Message	String	The optional message to display to end customer, usually on failure.
   PaymentRedirectUrl	String	The secure URL to redirect the customer to your hosted payment page. To prevent malicious tampering of the URL, it's important that you encrypt the visible part of the data or include a checksum that you can verify.
   Status	Integer	Use the status to indicate success or error processing request: 1 - Success 100 - Declined 200 - Gateway error 300 - Network error

    

   Below is an example of using an ASHX page to handle the communication between the Storefront and your hosted form page. Unlike as ASPX page, it does not contain any HTML and is suitable for returning plain text data.

   
   public class Pay : IHttpHandler
   {
       public bool IsReusable => throw new NotImplementedException();
   
       public void ProcessRequest(HttpContext context)
       {
           var amount = decimal.Parse(context.Request.QueryString["Amount"]);
           var failureReturnUrl = context.Request.QueryString["FailureReturnUrl"];
           var successReturnUrl = context.Request.QueryString["SuccessReturnUrl"];
   
           // We must not reveal the SuccessReturnUrl.
           // Use a stronger encryption.
           // In this example, we simply use a weak obfuscation method.
           var encryptedSuccessReturnUrl = new string(successReturnUrl.Select(c => (char)(c ^ 42)).ToArray());
   
           context.Response.ContentType = "text/plain";
   
           // You need to escape the values in a URL carefully.
           // Pass any additional values you need for your payment form.
           // You should encrypt any sensitive information that can be tampered with like the Amount.
           var paymentRedirectUrl = "http://site.com/Form.aspx?Amount=" + HttpUtility.UrlEncode(amount.ToString());
           paymentRedirectUrl += "&EncryptedSuccessReturnUrl=" + HttpUtility.UrlEncode(encryptedSuccessReturnUrl);
           paymentRedirectUrl += "&FailureReturnUrl=" + HttpUtility.UrlEncode(failureReturnUrl);
   
           // You need to escape the values again.
           context.Response.Write("Status=1&PaymentRedirectUrl=" + HttpUtility.UrlEncode(paymentRedirectUrl));
       }
   }
   

3. If status indicates success, the customer is redirected to your hosted payment page indicated by the PaymentRedirectUrl.
4. Once the customer has paid, redirect the customer back to the SuccessReturnUrl address. If the payment failed or customer cancelled the payment, please redirect the customer to the FailureReturnUrl.
    

   Below is an example of an ASPX hosted form page that handles a button click to charge the payment. Upon success, it will redirect back to the SuccessReturnUrl.

   
   public partial class HostedForm : System.Web.UI.Page
   {
       protected void Page_Load(object sender, EventArgs e)
       {
               
       }
   
       // Customer clicked on the Pay Now button
       protected void PayNowButton_Click(object sender, EventArgs e)
       {
           var amount = decimal.Parse(Request.QueryString["Amount"]);
           var failureReturnUrl = Request.QueryString["FailureReturnUrl"];
           var encryptedSuccessReturnUrl = Request.QueryString["EncryptedSuccessReturnUrl"];
   
           // Decrypt the encrypted SuccessReturnUrl.
           // Use a stronger encryption. In this example, 
           // we simply use a weak obfuscation method.
           var successReturnUrl = new string(encryptedSuccessReturnUrl.Select(c => (char)(c ^ 42)).ToArray());
   
           // Perform the actual charge to the card and test for success.
           // Here we simply test the card number is not empty.
           if (!String.IsNullOrEmpty(CardNumberTextBox.Text))
           {
               // If charge succeeded, redirect to SuccessReturnUrl
               Response.Redirect(successReturnUrl, false);
           }
           else
           {
               // If fail, redirect to the FailureReturnUrl
               Response.Redirect(failureReturnUrl, false);
           }
       }
   }
   

5. The callback step is optional, but can provide greater resiliency against browser disconnects during redirects. Once the customer has successfully paid, you can make an asynchronous callback request to transmit the result to the Notification URL. You will need to transmit the following key-value pair information in application/x-www-form-urlencoded format using a POST method.
    

   Name	Type	Description
   Message	String	The optional message to log in case of errors.
   Passphrase	String	This value should match the Passphrase entered in the credentials.
   ReferenceID	String	The reflected back value as-is from the original request to your service.
   TransactionID	String	Optional. Your identifier for historical reference to this transaction,
   Status	Integer	Use the status to indicate success or error processing request: 1 - Success 100 - Declined 200 - Gateway error 300 - Network error

Please contact us if you don't see the payment gateway you like to use.