Request Format

About

This page contains details of the API request you will send to Reach to achieve a successful order.

Responses, formats, reference tools, and other useful information can also be found below.

Request Requirements

📘

Integration Considerations

All HTTPS requests must be TLS1.2 or higher
All data is UTF-8 encoded
All field names are case sensitive
All currency and country codes must be uppercase and conform to ISO standards as specified

👍

Any response parameter that is either unknown or not currently being used may safely be ignored. For example, if financing is not currently offered the financing fields in the /getPaymentMethods response may be ignored.

Endpoints

The following are the base URLs for accessing the production and sandbox Checkout API services.

Production: https://checkout.rch.io/
Sandbox: https://checkout.rch.how/

HTTP Format

HTTP GET

Responses to HTTP GET requests will return application/json by default.

👍

If a Callback function is specified the JSONP pattern will be used and text/javascript will be returned to call the callback function. If the callback function does not exist a Javascript error will occur.

HTTP POST

All POST entities must be a x-www-form-urlencoded string with request and signature fields. A card field is appended when applicable.

All POST response entities will be an x-www-form-urlencoded string with response and signature fields.

👍

Synchronous responses to the /checkout request provide important information that may be used in helping the customer have a successful order. For example, if the CardExpired error is received the customer can be redirected to the payment information page to re-enter their information and try again.

HTTP Responses

AJAX REQUESTS

AJAX requests from a web page hosted by the merchant’s server to Reach's hosted Checkout API endpoints would normally be subject to the Same-Origin security policy. However, Reach allows simple cross origin requests as defined by the Cross Origin Resource Sharing (CORS) specification.

Most modern browsers support CORS but older browsers may not and so are incapable of making cross origin requests via AJAX. Support for these browsers has been deprecated. Detection of CORS support may be determined with the jQuery $.support.cors flag.

Signature Creation

All POST request and responses in the Request Format require a signature to verify both the sender and data integrity. The HMAC signature is calculated using the request or response contents and a shared secret provided by Reach.

❗️

The shared secret is only known by the merchant and Reach and should never be used on a public site. Consequently, signatures may only be generated on the merchant's server and never on the customer's browser.

👍

It's highly recommended that the signature be calculated for any responses received from Reach using the shared secret. If the calculated signature does not match the signature sent the response should be ignored as the data has been compromised.

View the signature calculation page.

Badge Localization

With the version 2.21 and later, we accept local/lang and return translations accordingly. Below are the codes that are passed in the query to the /badge endpoint. If no match is found, the default is US English.