Search

Contents

Revindex Storefront

Export Print

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.
    BillingEmail
    String  
    BillingFirstName
    String  
    BillingLastName
    String  
    BillingPhone
    String  
    BillingPostalCode
    String  
    BillingStreet1
    String  
    BillingStreet2
    String  
    BillingSubdivisionCode
    String The ISO 3166-2 subdivision code. e.g "US-CA" for California.
    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 URL to redirect the customer to your hosted payment page.
    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

Add comment

Powered by Revindex Wiki