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.
   BillingDistrict	String
   BillingEmail	String
   BillingFirstName	String
   BillingLastName	String
   BillingPhone	String
   BillingPostalCode	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

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.
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.