Checkout API integration guide
Our complete guide presents clear, step-by-step instructions for integrating the Reach's Checkout API.
The integration steps can vary depending on the merchant's requirements. The use case of the Checkout API can also vary, but it is modular and allows merchants to control the performance of their payments.
- 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. 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 2. 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 3. 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 4. 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 5. 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 6. 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 7. 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 8. 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 9. 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 1 day ago