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

👍

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.gointerpay.net//
Sandbox: https://checkout-sandbox.gointerpay.net//

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.

General algorithm for generating a signature:

1. Construct the JSON request body or decode the JSON response body as necessary.
2. Compute the SHA256 HMAC value of the JSON using the shared secret.
3. Base-64 encode the SHA256 HMAC signature.

Code Samples:

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');