Getting started
Our complete guide presents clear, step-by-step instructions for integrating the Reach's Checkout API.
The integration steps can vary depending on your requirements. The Checkout API can have various use cases; it is modular and allows you to manage your payment performance.
- Set up your environment for success
- Get FX rates (optional)
- Get a digital fingerprint (optional)
- Get payment methods
- Display the Reach badge
- Create a tax quote
- Create a checkout
- Capture delayed payments
- Manage refunds
- List reports (optional)
Step 1. Set up your environment for success
Set up your environment for success. Below are details on your request format and how to generate an accurate signature for requests.
Production and sandbox environments
Reach provides the following API environments:
| Environment | URL | Description |
|---|---|---|
| Sandbox | https://checkout.rch.how/ | The sandbox environment allows you to test API calls without affecting live data or services. You can use it for development and testing purposes. The sandbox domain name is checkout.rch.how. Since this is a safe environment for testing, any modifications or errors won't impact actual users or transactions. |
| Production | https://checkout.rch.io/ | The production environment is the live setting where the application operates and handles real user data and transactions. The production domain is checkout.rch.io. To avoid disruptions or data issues, you must thoroughly test them in the sandbox before sending them to this environment. |
Checkout API URL request requirements
When formatting a URL request for the Checkout API, note the following requirements:
- All HTTPS requests must be TLS 1.2 or higher.
- Use the latest API version in the format. The
v<x>.<nn>variable represents the version in the following example.
GET https://checkout.rch.how/v<x>.<yy>/getPaymentMethods?MerchantId=your_merchant_Id&Country=BR&Currency=BRL
- All data is UTF-8 encoded.
- All field names, such as
MerchantId, are case-sensitive. - All
Countrycodes, such as BR, must be uppercase and conform to the two-letter ISO code standards. - All
Currencycodes, such as BRL, must be uppercase and conform to the three-letter ISO code standards.
URL request format
AJAX requests
Most modern browsers support CORS (Cross-Origin Resource Sharing), while older browsers may not and cannot make cross-origin requests using AJAX. Reach has deprecated support for these older browsers. You can use the $.support.cors flag in jQuery to check for CORS support.
Signature calculations
Reach uses a hash-based Message Authentication Code (HMAC) signature to verify a message's data integrity and authenticity, ensuring it hasn't been tampered with and originated from the expected sender. HMAC calculates the signature using the contents of API requests and responses and a shared secret provided by Reach.
All GET and POST checkout API calls must include the signature calculation. The general algorithm for computing a signature is as follows:
- Compute the SHA256 HMAC value of the JSON to be submitted (before any encoding) or the JSON received from Reach (after any decoding) using the shared secret provided to you by Reach.
- Base-64 encodes the result.
The following code samples demonstrate how to calculate the HMAC signature given JSON input and a shared secret string.
import java.security.SignatureException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import sun.misc.BASE64Encoder;
public class hmac_signature {
public static String compute(String json, String secret) throws SignatureException
{
try {
SecretKeySpec key = new SecretKeySpec(secret.getBytes(), DIGEST_ALGORITHM);
Mac mac = Mac.getInstance(DIGEST_ALGORITHM);
mac.init(key);
BASE64Encoder base64Encoder = new BASE64Encoder();
return base64Encoder.encode(mac.doFinal(json.getBytes("UTF-8")));
} catch (Exception e) {
throw new SignatureException("HMAC Signature failed: " + e.getMessage());
}
}
}
import hashlib
import hmac
import base64
signature = base64.b64encode(hmac.new(bytes("secret").encode('utf-8'),
bytes("json").encode('utf-8'),
digestmod=hashlib.sha256).digest())
require 'openssl'
require 'base64'
signature = Base64.strict_encode64(OpenSSL::HMAC.digest
('sha256', secret.encode('utf-8'), json.encode('utf-8')))
$signature = base64_encode(hash_hmac('sha256', $json, $secret, TRUE));
using System.Security.Cryptography;
namespace Util {
public class hmac_signature {
private string compute(string json, string secret) {
secret = secret ?? "";
var encoding = new System.Text.UTF8Encoding();
using (var hmacsha256 = new HMACSHA256(encoding.GetBytes(secret))) {
return Convert.ToBase64String(hmacsha256.ComputeHash(encoding.GetBytes(json)));
}
}
}
}
#include <openssl/hmac.h>
#include <openssl/sha.h>
void compute_signature(const unsigned char *const json,
const unsigned int json_len,
const unsigned char *const secret,
const unsigned int secret_len,
char *const signature,
unsigned int *signature_len)
{
assert(json);
assert(secret);
assert(signature);
assert(signagure_len);
static unsigned char buffer[SHA_DIGEST_LENGTH];
unsigned int len = sizeof(buffer);
HMAC(EVP_sha256(), secret, secret_length, json, json_length, buffer, &len);
base64_encode(buffer, len, signature, signature_len);
}
$ create extension pgcrypto;
$ select encode(hmac(json, secret, 'sha256'), 'base64');
//jsonFormat is the json message
//hmacSecret is your Reach hmac Secret
jsonStr=JSON.stringify(jsonFormat,null,""); //Optional depending on your IDE, jsonStr=jsonFormat might work just well
if (typeof jsonStr != 'string') {
jsonStr = JSON.stringify(jsonStr);
}
hashInBase64 = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(jsonStr, hmacSecret, {asBytes: true}));
Step 2. Get FX rates (optional)
To get a list of foreign exchange (FX) rates, send an HTTP GET request to the getRates API endpoint. The API response will indicate either Guaranteed or Spot rates based on the configuration settings of your Reach account. For further details, consult the Get Rates API.
The following examples show how to send getRates API calls in the production and sandbox environments:
GET https://checkout.rch.how/v<x>.<yy>/getRates?merchantId=yourMerchantId
GET https://checkout.rch.io/v<x>.<yy>/getRates?merchantId=yourMerchantId
You can find more information on our Get Rates API.
Step 3. Get a digital fingerprint (optional)
This step is required only for customer-initiated transactions (CITs) requiring a device fingerprint. If you are not using CITs, proceed to the next step.
Unlike other Reach API requests, the fingerprint must be included using <script> tags on the page so that a pixel can be present on the frontend, allowing our fraud system to collect information about the shopper's system. See Fingerprint API for more details.
The following examples show how to send fingerprint API calls.
<script async="" src="https://checkout.rch.how/v<x>.<yy>/fingerprint?MerchantId={SANDBOX MERCHANT ID}"></script>
<script async="" src="https://checkout.rch.io/v<x>.<yy>/fingerprint?MerchantId={PROD MERCHANT ID}"></script>
Websites using Content-Security-Policy may need to include the following rules to use our fingerprint mechanism:
script-src https://checkout.rch.how/;
frame-src https://checkout.rch.how/ https://tst.kaptcha.com/
script-src https://checkout.gointerpay.net/;
frame-src https://checkout.gointerpay.net/ https://ssl.kaptcha.com/
To use the device fingerprint in checkout requests, use the Globally Unique Identifier (GUID) represented by the value for the gip_device_fingerprint parameter as the value for the DeviceFingerprint parameter in the Checkout API and Open Contract API requests.
var gip_device_fingerprint='83a669ce-c369-4bc8-be39-ec5519528628';
var d=document;
var b=d.getElementsByTagName('body')[0];
var e=d.getElementById('gip_fingerprint');
if(e){e.parentNode.remove();}
(function(){
var div=d.createElement('div');
div.style.display="none";
div.innerHTML=`
<iframe
id="gip_fingerprint"
src="https://checkout.rch.how/pixel/e6545955-938c-4f8d-8bb6-80b239bb9711/83c669ce-c369-4bc8-be39-ec5599528628.htm">
<img src="https://checkout.rch.how/pixel/e6545955-938c-4f8d-8bd6-80b139bb9711/83c666ce-c369-4bc8-be39-ec5598518628.gif"/>
</iframe>`;
b.appendChild(div);
})();
You can find more information on the device fingerprint in the Fingerprint API.
Step 4. Get payment methods
The getPaymentMethods API lets you retrieve and dynamically display the appropriate payment methods based on the selected currency. It returns the available payment methods in a structured JSON object format, allowing seamless integration into your website or checkout process.
The following examples show how to send getPaymentMethods API calls.
<script async="" src="GET https://checkout.rch.how/v<x>.<yy>/getPaymentMethods?MerchantId=6fcc882d-8aec-4f01-bb7f-a0d4be9a157b&Country=US&Currency=USD&ViaAgent=false"></script>
<script async="" src="GET https://checkout.rch.io/v<x>.<yy>/getPaymentMethods?MerchantId=6fcc882d-8aec-4f01-bb7f-a0d4be9a157b&Country=US&Currency=USD&ViaAgent=false"></script>
You can find more information on getting payment methods in the Get Payment Methods API.
Step 5. Display the Reach badge
The Badge element should be displayed during the checkout flow to show the shopper that Reach acts as the transaction's Merchant of Record (MoR). You can retrieve the badge details using the badge API call.
The following examples show the badge API request and response.
https://checkout.rch.how/v<x>.<yy>/badge?MerchantId=<Sandbox MerchantId>&Theme=<theme>
{
"Text": "By completing your order, you will check out with Reach US, our preferred international seller, and agree to the Terms of Service of Reach US.",
"Html": "<div class=\"reach--disclosure reach--payment--banner reach--payment--banner-light\"> <div class=\"reach--logo\"> <img src=\"https://st.rch.io/logos/reach-verified-logo-grey.svg\" alt=\"Reach Verified Badge\"> </div> <div class=\"reach--content\"> <p> By completing your order, you will check out with Reach US, our preferred international seller, and agree to the <a class=\"reach--inline-link\" href=\"https://assets.rch.red/service/terms-of-service?MerchantId=18da9ea3-f9ac-4e64-8405-d301f079a658\" title=\"Read Terms of Service\" target=\"reach\">Terms of Service</a> of <strong>Reach US</strong>. </p> </div> </div>",
"ImageUrl": "https://st.rch.io/logos/reach-verified-logo-grey.svg",
"FlagImageUrl": "https://st.rch.io/flags/US.png",
"TermsOfServiceUrl": "https://assets.rch.red/service/terms-of-service?MerchantId=18da9ea3-f9ac-4e64-8405-d301f079a658",
"MerchantOfRecord": "Reach US",
"MerchantOfRecordUrl": "https://withreach.com",
"MerchantName": "Jenna's Capes"
}
Note
The
Themeparameter defines the badge's theme is defined. Valid values for the theme are: light or dark. If you don't provide the Theme parameter, the request will default to the light theme.
You must display the Reach badge and disclaimer on the checkout page before the shopper completes payment.
Important
Note that the schemes do not accept a link to a separate webpage; you must display the Reach badge and disclaimer during checkout. See the Reach disclaimer and Terms of Service requirements for instructions on adding the Reach badge and disclaimer.
Render banner and badge server-side
You can also add an IP address to the /badge request to generate the Reach badge on the server and serve the result to your shopper. Reach bases the /badge response on the specified IP address instead of the IP linked to the request.
The following examples show how to send badge API calls on the server side.
https://checkout.rch.how/v<x>.<yy>/badge?MerchantId=<MerchantId>&Theme=<theme>&ConsumerIpAddress=<ip_address>
https://checkout.rch.how/v<x>.<yy>/badge?MerchantId=2a144a21-066a-42fe-a553-736a777e39e2&Theme=dark&ConsumerIpAddress=153.128.10.226
{
"Text": "By completing your order, you will check out with Reach US, our preferred international seller, and agree to the Terms of Service of Reach US.",
"Html": "<div class=\"reach--disclosure reach--payment--banner reach--payment--banner-dark\"> <div class=\"reach--logo\"> <img src=\"https://st.rch.io/logos/reach-verified-logo-white.svg\" alt=\"Reach Verified Badge\"> </div> <div class=\"reach--content\"> <p> By completing your order, you will check out with Reach US, our preferred international seller, and agree to the <a class=\"reach--inline-link\" href=\"https://assets.rch.red/service/terms-of-service?MerchantId=18da9ea3-f9ac-4e64-8405-d301f079a658\" title=\"Read Terms of Service\" target=\"reach\">Terms of Service</a> of <strong>Reach US</strong>. </p> </div> </div>",
"ImageUrl": "https://st.rch.io/logos/reach-verified-logo-white.svg",
"FlagImageUrl": "https://st.rch.io/flags/US.png",
"TermsOfServiceUrl": "https://assets.rch.red/service/terms-of-service?MerchantId=18da9ea3-f9ac-4e64-8405-d301f079a658",
"MerchantOfRecord": "Reach US",
"MerchantOfRecordUrl": "https://withreach.com",
"MerchantName": "Jenna's Capes"
}
For more information on the badge, see the Badge API.
Step 6. Create a tax quote
The Tax Quote API allows you to retrieve a tax quote for items that include tax calculations. In the request body, you must include "TaxIncluded": true in the Items array.
curl --request POST \
--url https://api.sandbox.withreach.com/v1/tax/quote \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"Currency": "string",
"Reference": "string",
"Items": [
{
"Sku": "string",
"Description": "string",
"TaxIncluded": true,
"Quantity": 0,
"Amount": 0
}
],
"ShippingAddress": {
"Street": "string",
"City": "string",
"Region": "string",
"Country": "string",
"Postcode": "string"
},
"WarehouseAddress": {
"Street": "string",
"City": "string",
"Region": "string",
"Country": "string",
"Postcode": "string"
},
"BusinessIdentificationNumber": "string"
}
'
{
"Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Currency": "string",
"Reference": "string",
"Items": [
{
"Id": "string",
"Sku": "string",
"Description": "string",
"TaxCode": "string",
"TaxIncluded": true,
"Quantity": 0,
"Amount": 0,
"TaxAmount": 0,
"Tax": [
{
"Name": "string",
"Type": "string",
"TaxAmount": 0
}
]
}
],
"ShippingAddress": {
"Street": "string",
"City": "string",
"Region": "string",
"Country": "string",
"Postcode": "string"
},
"WarehouseAddress": {
"Street": "string",
"City": "string",
"Region": "string",
"Country": "string",
"Postcode": "string"
},
"BusinessIdentificationNumber": "string",
"Amount": 0,
"TaxAmount": 0
}
For more information on getting a tax quote, see Reach Tax Quote API and Tax Quote API.
Step 7. Create a checkout
The checkout is where the magic happens! When you receive a successful response after sending a /checkout request, Reach manages the transaction, specifically through its Merchant of Record (MoR) payment model. This distinction impacts how we handle your transaction data and ensures a streamlined payment experience.
The following examples show how to send checkout API calls.
POST https://checkout.rch.how/v<x>.<yy>/checkout
"request": {
"MerchantId": "x",
"ReferenceId": "112233",
"PaymentMethod": "MC",
"ConsumerTotal": "63.91",
"ConsumerCurrency": "CAD",
"RateOfferId": "ee9efd25-e27a-4359-9312-aff3e3869b48",
"Capture": true,
"ViaAgent": true,
"AcceptLiability": true,
"OpenContract": false,
"DeviceFingerprint": "xyx",
"ContractId": "b229209b-9658-4538-b326-563eeebfaa5b",
"Items": [
{
"Sku": "Item1",
"ConsumerPrice": "63.91",
"Quantity": "1"
}
],
"Consumer": {
"Name": "john smith",
"Email": "[email protected]",
"Address": "394 Stanhope Garden",
"City": "Winnipeg",
"Region": "MB",
"PostalCode": "R2N 0G8",
"Country": "CA"
}
}
POST https://checkout.rch.io/v<x>.<yy>/checkout
"request": {
"MerchantId": "x",
"ReferenceId": "112233",
"PaymentMethod": "MC",
"ConsumerTotal": "63.91",
"ConsumerCurrency": "CAD",
"RateOfferId": "ee9efd25-e27a-4359-9312-aff3e3869b48",
"Capture": true,
"ViaAgent": true,
"AcceptLiability": true,
"OpenContract": false,
"DeviceFingerprint": "xyx"
"ContractId": "b229209b-9658-4538-b326-563eeebfaa5b",
"Items": [
{
"Sku": "Item1",
"ConsumerPrice": "63.91",
"Quantity": "1"
}
],
"Consumer": {
"Name": "john smith",
"Email": "[email protected]",
"Address": "394 Stanhope Garden",
"City": "Winnipeg",
"Region": "MB",
"PostalCode": "R2N 0G8",
"Country": "CA"
}
}
See the Checkout API for more information.
Step 8. Capture delayed payments
If you want to use delayed payment capture for orders, ensure the capture occurs within 7 days after authorization. Add the parameter AutoCapture=false to activate this delay in the initial Checkout API call. When it's time to ship or capture the order, send the subsequent API call according to the guidelines outlined below.
The following examples show how to send capture API calls.
POST https://checkout.rch.how/v<x>.<yy>/capture
{
"request":
{
"MerchantId":
"6f123-10erofogl-1212359",
"OrderId":
"12345"
},
"signature":
"abcdef="
}
POST https://checkout.rch.io/v<x>.<yy>/capture
{
"request":
{
"MerchantId":
"6f123-10erofogl-1212359",
"OrderId":
"12345"
},
"signature":
"abcdef="
}
For further details on capturing an order, see our Capture API. Review the capture rules in our Checkout API.
Step 9. Manage refunds
Refunds are available in your Reach Admin, but you can also use our Refund API endpoint to execute refunds against your orders. For more information, see our Refund API.
Step 10. List reports (optional)
List reports are essential for accounting functions and will be available at our endpoint when the remittance process is completed. For detailed information, refer to the List Reports API.
Updated about 10 hours ago