Search

Index

Revindex Storefront

Custom hosted gateway

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.

Comments


Powered by Revindex Wiki