Boarding API - ISVs

Version 1.0

May 23, 2025

Note

This API is currently only available as part of our Pilot program.

On this page

Introduction
Authentication
- Generate an X-User-ID
- Generate an X-Message-Hash
Boarding API - ISVs Specification
Merchant Application Error Responses

Introduction 

Our Boarding API for ISVs is a RESTful API that can be used to submit a merchant application for payment processing.

Merchant applications contain the following information:

Business information – Business and legal information, such as type of business, Doing Business As (DBA) name, and business email address.
Owners – Name and contact details of the business owners. You can provide up to four owners, and you must assign one of the owners as an authorized signatory.
Contact details – Contact information for the business, such as its phone number, fax number, and email address.
PAD processing – Information that we need to process PAD transactions, such as funding account details and the fees to run PAD transactions.
Card processing – Information that we need to process card transactions, such as funding account details and the fees to run card transactions.

If the boarding request is accepted, then the application will be sent to the merchant. Once the merchant has completed and signed the application, it will be submitted for Payroc underwriting and boarding.

Authentication 

To authenticate your requests, we provide you with an API User ID and an API Key.

Important

Do not share API keys and do not use API keys in publicly accessible areas, for example, on client-side code.

Use your API User ID and API Key to generate an X-User-ID and an X-Message-Hash. X-User-ID and X-Message-Hash need to be included in the header of your requests, for example:

Content-Type: application/json
X-User-ID: c2FtcGxlX0lEMTIzNDU
X-Message-Hash: kCaHLZMAF+3Ov923dfPF+AkauzmSclAn1vnFaoTu/rk=

Generate an X-User-ID 

To create your X-User-ID, convert your API User ID into base64 encoded format.

Generate an X-Message-Hash 

Your X-Message-Hash is a base64-encoded value that you create from your API Key and your JSON request string. To create your X-Message-Hash, complete the following steps:

Use your API key to create a HMAC-SHA256 hash of the JSON request string. For more information about HMAC, go to RFC 2104.

Convert the value to a base64-encoded format.

400 - Invalid Data

Incoming data cannot be validated against the defined schema.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#invalid-data",
  "title": "The incoming data fields did not pass validation checks.",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
      {
          "detail": "Missing property.",
          "parameter": "/dba_name"
      },
      {
          "detail": "Missing property.",
          "parameter": "/legal_entity_contact_email"
      },
      {
          "detail": "Missing property.",
          "parameter": "/legal_entity_contact_phone"
      }
  ],
}

400 - Credit Card Processing Not Enabled

The API user does not have permissions for credit card processing.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#credit-card-processing-not-enabled",
  "title": "Credit Card Processing Not Enabled",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
    {
      "message": "This API user does not have permissions to create merchant applications that include credit card as a payment type."
    }
  ]
}

400 - PAD Processing Not Enabled

The API user does not have permissions for PAD processing.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#pad-processing-not-enabled",
  "title": "PAD Processing Not Enabled",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
    {
      "message": "This API user does not have permissions to create merchant applications that include PAD as a payment type."
    }
  ]
}

400 - Volume Breakdown Error

Ecommerce and MOTO order volumes must total 100%.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#volume-breakdown-error",
  "title": "Volume Breakdown Error",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
    {
      "message": "Current ecommerce and mail/telephone order volume percentage must sum to 100%."
    }
  ]
}

400 - Invalid or Missing Email Contact Method

One or more authorized signatories did not provide an email contact method.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_MerchantApplicationAPI.html#invalid-or-missing-email-contact-method",
  "title": "Invalid or Missing Email Contact Method",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
    {
      "message": "An email address must be provided as contact method for authorized signatories."
    }
  ]
}

400 - Invalid PAD Trust Account Setup

Trust accounts are not correctly configured for PAD.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#invalid-pad-trust-account-setup",
  "title": "Invalid PAD Trust Account Setup",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
    {
      "message": "Only the funding account can be designated as a trust account. Fee and return accounts must be provided."
    }
  ]
}

400 - Invalid Credit Card Trust Account Setup

Trust accounts are not correctly configured for credit card.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#invalid-credit-card-trust-account-setup",
  "title": "Invalid Credit Card Trust Account Setup",
  "status": 400,
  "detail": "One or more validation errors occurred. See errors object for more info.",
  "errors": [
    {
      "message": "Only the deposit account can be designated as a trust account. Fee and chargeback accounts must be provided."
    }
  ]
}

401 Unauthorized 

Your identity could not be verified.

Check that:

The X-User-ID and X-Message-Hash headers are correctly generated.
Your API Key and User ID are active and valid.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#unauthorized",
  "title": "Not Authorized",
  "status": 401,
  "detail": "Your identity could not be verified."
}

403 Forbidden 

You do not have permission to perform the requested action.

Ensure that:

Your API User has the appropriate rights for this endpoint.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have the required permissions to perform this action."
}

404 Not Found 

The requested resource could not be found.

Verify that:

The URL is correct.
The resource exists and is accessible to your API User.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Resource not found.",
  "resource": "(The Type of the Resource)"
}

500 Internal Server Error 

An unexpected error occurred.

Please try again later.
If the problem persists, contact Payroc support with request details.

{
  "type": "https://portal.caledoncard.com/documentation/html/Payroc_IsvBoardingAPI.html#internal-server-error",
  "title": "API Error",
  "status": 500,
  "detail": "Unable to process your request at this time.",
  "errors": [
    {
      "message": "Service offline"
    }
  ]
}

Back to Top of Error Codes.

Boarding API - ISVs

Introduction 

Authentication 

Generate an X-User-ID 

Generate an X-Message-Hash 