QuadPay

QuadPay Integration

Welcome! Integrating QuadPay into your online store is straightforward. Here you'll find comprehensive guides and documentation to support integrating QuadPay into your site as quickly as possible. Let's jump right in!

Guides

API Documentation

This document will outline the API and the high-level requirements of completing a custom QuadPay API integration as a payment gateway for a merchant's website.

API Endpoint Documentation is available here

Functional Flow

This is a basic description of how an integration to the QuadPay payment gateway via our API would look.

  1. Customer selects QuadPay as their payment method during checkout on merchant's site.
  2. Customer on merchant's site does a form POST to the QuadPay /orders/authorize API endpoint containing basic information the order.
  3. QuadPay redirects to the QuadPay checkout.
  4. Customer completes payment process on QuadPay site.
  5. QuadPay redirects customer back to merchant site via a confirm or cancel URL (depending on whether they completed payment successfully or not). These URLs are set by merchant when creating the order.
  6. In addition to the customer navigating through the supplied confirm URL, the merchant will also receive a server-side POST from QuadPay to confirm the order authorization.

Which API do I use? Gateway vs. Legacy

The API Endpoint Documentation references two well-supported APIs that are used for custom integrations -- the gateway and legacy merchant APIs.

QuadPay recommends that all new integrations use the Gateway API. The Gateway API was built with additional resiliency and scalability in mind. Implementations with the Gateway have the following differences:

  • QuadPay will make a server-side webhook callback API request to the merchant's platform to confirm the success/failure of all operations, such as order authorizations, refunds, captures, and voids. This removes the need to poll for order processing updates from QuadPay.
  • The merchant will receive data on callbacks and user redirects to create the order in their system with all the data needed instead of multiple subsequent calls to QuadPay's API.
  • Requests to the QuadPay gateway API must contain a header with a signature to secure requests. This implementation results in less API calls to authenticate from our identity provider and no need for the merchant to manage credential caching.
  • Support for deferred order confirmation.

While our Gateway API is the preferred implementation path for merchant's looking to do a full custom API integration, we will continue to support the legacy API. When should you use a the legacy API instead of the Gateway API?

  • You already have an integration with QuadPay and don't want to rebuild it.
  • You are unable to receive HTTP requests (for the webhooks/callbacks) from QuadPay servers in your system.

The below sections cover integrations to each API.

Gateway API

To build your integration, you will utilize the Orders endpoints listed below. Later sections cover how to receive requests and the format of the webhooks that you will use to get updates about QuadPay orders initiated through the gateway API.

Endpoints and Environments

You will be given unique credentials for the sandbox and production environments. It is best to build your integration against the sandbox environment and enable in production upon successful certification.

Production - https://gateway.quadpay.com
Sandbox (Test) - https://sandbox.gateway.quadpay.com

Sent from the user's browser via a form POST, will start a checkout session within QuadPay. It will automatically redirect the user to our QuadPay checkout. You need to ensure you provide your merchant ID, merchant reference (the unique ID you use for the order in your system), confirm/cancel URLs, and the order amount. The order amount should include all shipping, tax, and discount charges. You do not need to provide the order ID as that will be generated for you. Passing as much customer information as possible will improve the user experience by pre-filling data fields and improving conversion. Required fields are:

  • merchantId - Your identifier provided by QuadPay
  • merchantReference - Your unique order identifier for this order in your system
  • callbackUrl - A URL that will receive the webhook request about the result of this operation
  • redirectCancelUrl - Where the user should go upon abandoning their cart.
  • redirectConfirmUrl - Where the user should go upon order completion (will include the aforementioned query parameters)

Example

Request URL: https://gateway.quadpay.com/orders/authorize
POST Body:

{
  "merchantId": "44444444-4444-4444-4444-444444444444",
  "merchantReference": "ref",
  "order": {
    "currency": "USD",
    "amount": 123.45,
  },
  "test": true,
  "capture": true,
  "redirectCancelUrl": "https://www.bing.com",
  "redirectConfirmUrl": "https://www.google.com",
  "callbackUrl": "https://api.merchant.com"
}

Same as the above endpoint but data is passed as query string parameters with a GET request.

Example

Request URL: https://gateway.quadpay.com/orders/authorize?merchantId=44444444-4444-4444-4444-444444444444&merchantReference=TH-20200707-1da6&order.firstName=Aaron&order.lastName=Smith&order.email=869765666.test%40quadpay.com&order.phone=5555555555&order.billingAddress.line1=123+Main+St&order.billingAddress.city=New+York&order.billingAddress.state=NY&order.billingAddress.postalCode=10003&order.billingAddress.country=US&order.amount=100.00&capture=True&callbackUrl=https%3a%2f%2fapi.merchant.com%2forder%2fcomplete&redirectCancelUrl=https%3a%2f%2fapi.merchant.com%2forder%2fcancel&redirectConfirmUrl=https%3a%2f%2fapi-ci.quadpay.com%2forder%2fcomplete&X-QP-Signature=3f3oc6tACuGIs%2fX7bhWP3PkstZ8UmI6fSZ%2buPQE8Wfo%3d

Will request a merchant refund to the supplied order and apply it to the customer's payment plan. If you are a pay-on-ship/DFC merchant, you can only apply up to your captured amount. Required fields are:

  • orderId - QuadPay order ID to refund
  • merchantId - Your identifier provided by QuadPay
  • currency - The currency to issue the refund in
  • amount - The amount of the refund (not the amount of the order!)
  • merchantReference - An identifier in your system to reference this refund transaction
  • callbackUrl - A URL that will receive the webhook request about the result of this operation

Example

Request URL: https://gateway.quadpay.com/orders/44444444-4444-4444-4444-444444444444/refund
POST Body:

{
  "orderId": "44444444-4444-4444-4444-444444444444",
  "currency": "USD",
  "amount": 123.45,
  "merchantReference": "ref",
  "callbackUrl": "https://api.merchant.com"
}

Only for pay-on-ship/DFC merchants. This captures funds to reflect a fulfilled item in an order. Required fields are:

  • orderId - QuadPay order ID to capture
  • merchantId - Your identifier provided by QuadPay
  • currency - The currency to issue the capture in
  • amount - The amount of the capture (not the amount of the order!)
  • merchantReference - An identifier in your system to reference this capture transaction
  • callbackUrl - A URL that will receive the webhook request about the result of this operation
  • singleCapture - True if this will be the only capture for the order and you want the rest to automatically be voided.

Example

Request URL: https://gateway.quadpay.com/orders/44444444-4444-4444-4444-444444444444/capture
POST Body:

{
  "orderId": "44444444-4444-4444-4444-444444444444",
  "currency": "USD",
  "amount": 123.45,
  "merchantReference": "ref",
  "callbackUrl": "https://api.merchant.com",
  "singleCapture": false
}

Only for pay-on-ship/DFC merchants. This voids funds to reflect a cancelled item in an order. Required fields are:

  • orderId - QuadPay order ID to void
  • merchantId - Your identifier provided by QuadPay
  • currency - The currency to issue the void in
  • amount - The amount of the void (not the amount of the order!)
  • merchantReference - An identifier in your system to reference this void transaction
  • callbackUrl - A URL that will receive the webhook request about the result of this operation

Example

Request URL: https://gateway.quadpay.com/orders/44444444-4444-4444-4444-444444444444/void
POST Body:

{
  "orderId": "44444444-4444-4444-4444-444444444444",
  "currency": "USD",
  "amount": 123.45,
  "merchantReference": "ref",
  "callbackUrl": "https://api.merchant.com"
}

Merchants using the Standard Checkout with the mobile SDK will allow customers to use the QuadPay checkout without starting an order until this API call is made by the merchant. This same feature can be leveraged for standard online checkouts as well. The payment plan for the customer will not begin until a successful callback is received by the merchant for this operation. This operation does allow merchants to add shipping/taxes after the QuadPay checkout for the order. This will be processed with the currency of the original order. Required fields are:

  • orderId - QuadPay order ID to confirm
  • merchantReference - An identifier in your system to reference this confirmtransaction
  • callbackUrl - A URL that will receive the webhook request about the result of this operation

Optionally, you can provide the following:

  • amount - The new total order amount, including all shipping/tax amounts added in
  • shippingAmount - The final calculated shipping amount
  • taxAmount - The final calculated tax amount

Example

Request URL: https://gateway.quadpay.com/orders/44444444-4444-4444-4444-444444444444/confirm
POST Body:

{
  "orderId": "44444444-4444-4444-4444-444444444444",
  "merchantReference": "ref",
  "callbackUrl": "https://api.merchant.com"
}

Merchants with a merchant fee for payment plan (i.e. MFPP) agreement can use this endpoint to determine the fee amount for a given order. The state/country for the customer should come from the customer's shipping address. When $0 is returned, then there is no fee and does not need to display within the merchant's UX. Required fields are:

  • amount - The total order amount including shipping/tax amounts added in.
  • currency - Defaults to USD if not provided.
  • customerState- The state of the customer's shipping address.
  • customerCountry - The country of the customer's shipping address. Defaults to "US".

Example

Request URL: https://gateway.quadpay.com/orders/calculate-merchant-fees
POST Body:

{
  "customerState": "NY",
  "customerCountry": "US",
  "currency": "USD",
  "amount": 123.45
}

Sample response:

{
  "merchantFeeForPaymentPlan": 1.00,
  "currency": "USD"
}

Signing Requests

All operations are secured with an HMAC-SHA256 one-way hash that is performed using a shared secret key between QuadPay and the merchant. This secret key will be provided to you.

Signatures are generated based on the request type.

  • POST JSON Requests sign the entire request body contents.
  • POST Form Requests sign all the keys + values contained in the form request in alphabetical order except for the signature.
  • GET Requests sign all the keys + values contained in the query string in alphabetical order except for the signature.

Implementing this is language specific. Here is an example using C# that can generate these hashes for you:

public class HmacSha256Signature
    {
        private static Encoding encoding = Encoding.UTF8;

        /// If your entire request body is passed in as bytes (e.g. POST JSON request), this will give you the correct hash
        public string Compute(string secretKey, byte[] bytes)
        {
            using (var hmacsha256 = new HMACSHA256(encoding.GetBytes(secretKey)))
            {
                var hash = hmacsha256.ComputeHash(bytes);

                return Convert.ToBase64String(hash);
            }
        }

        /// Given a dictionary that contains all the values from a GET or form POST request, this will return your correct hash
        public string Compute(string secretKey, IDictionary<string, string> values)
        {
            var builder = new StringBuilder();

            // Form Keys Sorted Alphabetically
            foreach (var item in values.OrderBy(i => i.Key))
            {
                if (!item.Key.Equals(Constants.SignatureKey, StringComparison.OrdinalIgnoreCase))
                {
                    builder.Append(item.Key);
                    builder.Append(item.Value);
                }
            }

            var message = builder.ToString();

            return this.Compute(secretKey, encoding.GetBytes(message));
        }

        public string Compute(string secretKey, string json)
        {
            var bytes = encoding.GetBytes(json);

            return this.Compute(secretKey, bytes);
        }

        /// This can take any object and turn it into a dictionary to be used for hash creation
        public IDictionary<string, string> GenerateKeyValues(object model)
        {
            var jsonObject = JObject.FromObject(model, JsonSerializer.Create(Constants.KeyGenSerializerSettings));
            var jTokens = jsonObject.Descendants().Where(p => p.Count() == 0);
            var keyValues = jTokens.Aggregate(
                new Dictionary<string, string>(),
                (
                    properties,
                    jToken) =>
                {
                    properties.Add(jToken.Path, jToken.ToString());
                    return properties;
                });

            return keyValues;
        }
    }

Callbacks

All of the endpoints listed above include a callbackUrl parameter. This URL will be used by QuadPay to update you on the result of each of these operations. The content of this webhook is as follows:

{
    "timestamp": "2020-04-27T12:34:56.000000Z",
    "merchantId": "44444444-4444-4444-4444-444444444444",
    "orderId": "44444444-4444-4444-4444-444444444444",
    "currency": "USD",
    "amount": 123.45,
    "merchantReference": "1234-abc",
    "test": false,
    "success": true,
    "metadata": {
      "property1": "value1"
    }

The merchantReference value will match the value you provided for the original operation. You also may pass metadata properties to add other important attributes you may need to use to identify your order.

Each of these callbacks will have a X-QP-Signature header that contains the signature that you can use to verify and trust the HTTP request.

These callbacks are issued for every operation (order authorization, refund, void, and capture transactions).

Important! This data will also be provided to you as query string parameters on your supplied confirm URL when creating an order. You can use this to verify order completion within your system by verifying the signature and utilizing the other parameters to store the QuadPay order ID. Here is a sample URL showing how this information is added. Also note that we pass you the QuadPay customer information as part authorize order callbacks:

https://yoursite.com/order/complete?timestamp=04%2F27%2F2020%2023%3A27%3A22&merchantId=44444444-4444-4444-4444-444444444444&orderId=44444444-4444-4444-4444-444444444444&currency=USD&amount=123.45&merchantReference=1234-abc&test=False&success=True&customer.firstName=Test&customer.lastName=Test&[email protected]&customer.phone=%2B15555555555&customer.address.line1=123%20Main%20St&customer.address.city=New%20York&customer.address.state=NY&customer.address.postalCode=10000&customer.address.country=US&X-QP-Signature=PdkC29bSMbRG5DR6E0xQt781AgvaZa6Ov9V26Ez2OHU%3D

Legacy API

Endpoints

Creates an Order that is used to initiate the QuadPay payment flow.

Production Endpoint
POST https://api.quadpay.com/order

Staging Endpoint
POST https://api-ut.quadpay.com/order

Retrieves an order by the token assigned to it.

Production Endpoint
GET Https://api.quadpay.com/order/{orderId}

Sandbox Endpoint
GET https://api-ut.quadpay.com/order/{orderId}

This endpoint retrieves payment configuration settings that define the valid Order min/max ranges for use with QuadPay.

Production Endpoint
POST https://api.quadpay.com/configuration

Sandbox Endpoint
POST https://api-ut.quadpay.com/configuration

This endpoint issues a refund against an existing 'Approved' QuadPay Order ID.

Requests to this endpoint are idempotent if a unique requestId is provided.

Production Endpoint
POST https://api.quadpay.com/order/[orderId]/refund

Sandbox Endpoint
POST https://api-ut.quadpay.com/order/{orderId}/refund

This endpoint issues a capture against an existing 'Approved' QuadPay Order ID for pay-on-ship/DFC merchants.

Requests to this endpoint are idempotent if a unique merchantReference is provided.

Production Endpoint
POST https://api.quadpay.com/order/[orderId]/capture

Sandbox Endpoint
POST https://api-ut.quadpay.com/order/{orderId}/capture

This endpoint issues a void against an existing 'Approved' QuadPay Order ID for pay-on-ship/DFC merchants.

Requests to this endpoint are idempotent if a unique merchantReference is provided.

Production Endpoint
POST https://api.quadpay.com/order/[orderId]/void

Sandbox Endpoint
POST https://api-ut.quadpay.com/order/{orderId}/void

Authentication

QuadPay uses OAuth2 Client Credentials Flow as the primary means for authorizing Merchant API requests. This is a two step process in that the client must obtain an access token via the OAuth token endpoint and then use this token to access the QuadPay API endpoints.

Client Id & Client Secret will be provided by QuadPay.

Note These access tokens are created with a specific expiration time. The integration should cache these tokens for no longer than the expiration length and request a new one if the existing token has expired. It is important to cache these tokens and not request a new one for each operation.

Refer to the Authentication API documentation for more information.

Pending Orders

Integrations should keep track of what orders have been sent to QuadPay for payment and have a scheduled job that runs every 10 minutes or so that checks the status of these orders via the 'GET Order' Endpoint. This insures that if a customer doesn't get successfully redirected back to the integration's callback endpoint, the merchant's internal order status can be updated to reflect the outcome of the QuadPay checkout.

Environments

Custom integrations should be built to understand the context in which they are operating. During development and testing, all configuration parameters will be specific to the Sandbox environment. This includes the Client ID, Client Secret and Audience used in the Authorization Endpoint and the base QuadPay API Endpoint for all Merchant API Requests.

Once a custom integration is fully developed and tested, QuadPay will issue a new set of Production credentials to be used when the integration goes live.

Production Merchant API Endpoint
POST https://api.quadpay.com/

Sandbox Merchant API Endpoint
POST https://api-ut.quadpay.com/

Test Data

You may use the below testing data while working with the QuadPay checkout in your development environment.

Field

Test Data

Phone

A US-based mobile phone number. You may use VOIP services for development if needed.

Email

Can be real or fake valid email address (‘@example.com’ for fake)

Verification Code

Code received via SMS

Name

Anything

Address

Anything valid

Birthdate

Anything 22+ years old

Billing Address

Anything valid

Card Holder Name

Anything

Card Number

4242 4242 4242 4242

Expiration date

02 / 22

CVC

222

Updated 3 months ago

API Documentation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.