Merchant Onboarding API 

Version 2.7

May 9, 2023

Table of Contents

Merchant Onboarding API

Introduction 

The Merchant Onboarding API is a RESTful web service designed to improve onboarding experience for Payroc partners and customers.

A simple form can be used to request new merchant setups for both PAD and Card payment processing.

Messages are HTTPS POST or HTTPS GET with JSON format being used for data exchange.

Process Overview 

Customers can request an account setup for Merchant Onboarding API by contacting Payroc Merchant Services.

Tel: 647-258-3708

Toll Free: 1-855-812-5191

Email: canada-support@payroc.com

After receiving their account credentials, customers can construct and send request messages to Payroc’s API server

Payroc’s API server will return a response specifying whether a request has been queued for review or rejected due to validation errors

Payroc Merchant Services will review all queued requests and update the status to either approved or declined

A notification message is delivered to the customer’s server specifying whether a request has been approved or declined.

For approved requests, the notification will include the information required to commence payment processing.

Customers can choose to submit Status Update requests to determine the status of their merchant setups instead of receiving Notification messages.

Authentication 

Authentication of requests is performed based on following values included in HTTP header:

X-User-ID

X-User-ID value must be base64 encoded API User ID assigned by Payroc

API User ID will be an ASCII string up to 32 bytes in length that can contain A-Z,a-z,0-9,-,_

X-Message-Hash

X-Message-Hash value must be base64 encoded result of hash function

Message hash is calculated using the API Key provided by Payroc and the entire JSON string included in the request

API Key will be an alphanumeric ASCII string up to 64 bytes in length

Hash is to be generated using HMAC-SHA256 algorithm - see RFC 2104 for details

HTTP header example:

Content-Type: application/json

X-User-ID: sample\_ID12345

X-Message-Hash: kCaHLZMAF+3Ov923dfPF+AkauzmSclAn1vnFaoTu/rk=

Response returned for failed authentication:

HTTP Code: 401

{ "message":"", "details":{} }

Request Fields 

Templates setup by Payroc Merchant Services are used to control the field requirements for each API User ID. Examples of typical templates are provided in *Template Examples* section.

General Boarding Information 

Field	Values	Description
request_id	String [1-64] Alphanumeric, underscore, hyphen, space, period, comma, ampersand, colon, semicolon, slash, vertical slash, @	Unique identifier for the request. Requests including a previous request id will be rejected as duplicate.
action	String [1-16]	Action ‘add’ - Create a new merchant ‘update’ - Update an existing merchant ‘deactivate’ - Deactivate an existing merchant Optional for “add” requests. Required for “update”, “deactivate” requests.
terminal_id	String [8] Alphanumeric	Terminal ID Required for “update” and “deactivate” requests. Rejected for “add” requests.
legal_entity_name	String [1-30] Alphanumeric, space, hyphen, underscore, period, comma, ampersand	Legal Entity Name Used as Chain name for Payment Facilitator setups
legal_entity_type	String [6]	Legal Entity Type ‘CRPPRV’ - Private Corporation ‘CRPPUB’ - Public Corporation ‘NNPRFT’ - Non-Profit ‘GOVERN’ - Government ‘LLCPRV’ - Private LLC ‘LLCPUB’ - Public LLC ‘PRTPRV’ - Partnership Private ‘PRTPUB’ - Partnership Public ‘SOLEPR’ - Sole Proprietor
legal_entity_contact_phone	String [1-25] Alphanumeric, space, hyphen, period, comma	Legal Entity Phone number
legal_entity_contact_email	String [1-254] Multiple emails can be separated by comma	Legal Entity Email address
customer_service_phone	String [1-25] Alphanumeric, space, hyphen, period, comma	Customer Service Phone number
url	String [1-128] URL address	Company URL
dba_name	String [1-25] Alphanumeric and space	Doing Business As (DBA) name
mcc	String [4] Numeric only	Merchant Category Code

Address 

Field		Values	Description
address		Object	Merchant address
	street	String [1-50] Alphanumeric, space, hyphen, underscore, period, comma	Street number PO BOX numbers are not allowed Unit or Apt number needs to be preceded by UNIT or APT
	city	String [1-20] Alphanumeric and underscore	City name
	province	String [2] Two-Letter abbreviation	Province or State
	pc_zip	String [1-16]	Canadian Postal Code or U.S. Zip Code
	country	String [2]	Country “CA” or “US”

Owner Information 

Owner information must be an Authorized Signer to satisfy Amex compliance requirements.

Field		Values	Description
owner_information		Object	Owner information
	name	String [1-30] Alphanumeric First and last name separated by space	Owner name
	phone	String[1-25] Alphanumeric, space, hyphen, comma, period	Phone number
	email	String [1-300] Multiple email addresses can be separated by comma	Email address
	country	String [2]	Country Code Format: ISO Alpha-2 Country Code Example: CA, US, GB
	date_of_birth	String [8] Numeric value	Owner’s date of birth Format: YYYYMMDD

Contact Details 

Primary Contact 

Field		Values	Description
primary_contact		Object	Primary contact information
	name	String [1-30] Alphanumeric First and last name separated by space	Contact name
	phone	String[1-25] Alphanumeric, space, hyphen, comma, period	Phone number
	fax	String[1-25] Alphanumeric, space, hyphen, comma, period	Fax number
	email	String [1-300] Multiple email addresses can be separated by comma	Email address
chargeback_contact		Object	Chargeback contact information
	name	String [1-30] Alphanumeric First and last name separated by space	Contact name
	phone	String [1-25] Alphanumeric, space, hyphen, comma, period	Phone number
	fax	String [1-25] Alphanumeric, space, hyphen, comma, period	Fax number
	email	String [1-300] Multiple email addresses can be separated by comma	Email address

Admin Contact 

Field		Values	Description
admin_contact		Object	Admin contact information
	name	String [1-30] Alphanumeric First and last name separated by space	Contact name
	phone	String [1-25] Alphanumeric, space, hyphen, comma, period	Phone number
	fax	String [1-25] Alphanumeric, space, hyphen, comma, period	Fax number
	email	String [1-300] Multiple email addresses can be separated by comma	Email address

Techincal Contact 

Field		Values	Description
tech_contact		Object	Technical contact information
	name	String [1-30] Alphanumeric First and last name separated by space	Contact name
	phone	String [1-25] Alphanumeric, space, hyphen, comma, period	Phone number
	fax	String [1-25] Alphanumeric, space, hyphen, comma, period	Fax number
	email	String [1-300] Multiple email addresses can be separated by comma	Email address

PAD Boarding Details 

Field			Values	Description
pad_acceptance			String [1]	Specifies whether PAD payments are to be accepted “Y” or “N”
pad			Object	PAD related parameters Required if pad_acceptance is set to Y
	account		Object	Merchant bank account
		bank	String [1-3] Numeric value	Bank number
		transit	String [1-5] Numeric value	Transit number
		account	String [7-12] Numeric value	Account number
	returned_item_account		Object	Merchant bank account for returned items, AKA NSF items
		bank	String [1-3] Numeric value	Bank number
		transit	String [1-5] Numeric value	Transit number
		account	String [7-12] Numeric value	Account number
	threshold		Object	Merchant risk thresholds
		max_transaction_amount	Integer value	Maximum transaction amount (in cents)
		max_monthly_transaction_count	Integer value	Maximum monthly transaction count
		max_monthly_transaction_volume	Integer value	Maximum monthly volume (in cents)
	funding_days		Integer [0-99]	Funding Days Number of banking days after settlement that merchant funds are to be issued. Optional

Cheque Boarding Details 

Field			Values	Description
cheque_acceptance			String [1]	Specifies whether Cheque payments are to be accepted “Y” or “N”
cheque			Object	Cheque related parameters Required if cheque_acceptance is set to Y
	account		Object	Merchant bank account
		bank	String [1-3] Numeric value	Bank number
		transit	String [1-5] Numeric value	Transit number
		account	String [7-12] Numeric value	Account number
	threshold		Object	Merchant risk thresholds
		max_transaction_amount	Integer value	Maximum transaction amount (in cents)
		max_monthly_transaction_count	Integer value	Maximum monthly transaction count
		max_monthly_transaction_volume	Integer value	Maximum monthly volume (in cents)
	funding_days		Integer [0-99]	Funding Days Number of banking days after settlement that merchant funds are to be issued. Optional

EFT Payment Boarding Details 

Field			Values	Description
eft_payment_acceptance			String [1]	Specifies whether EFT payments are to be accepted “Y” or “N”
eft_payment			Object	EFT payment related parameters Required if eft_payment_acceptance is set to Y
	account		Object	Merchant bank account
		bank	String [1-3] Numeric value	Bank number
		transit	String [1-5] Numeric value	Transit number
		account	String [7-12] Numeric value	Account number
	fees		Object	PAD related fees
		transaction	Integer value	Transaction fee (in cents)
		reject	Integer value	Reject fee (in cents)
		return	Integer value	Return fee (in cents)
	funding_days		Integer [0-99]	Funding Days Number of banking days after settlement that merchant funds are to be issued. Optional

Card Payment Boarding Details 

Field			Values	Description
card_payment_acceptance			String [1]	Specifies whether card payments are to be accepted “Y” or “N”
card_payment			Object	Card payment related parameters Required if card_payment_acceptance is set to Y
	credit_account		Object	Credit bank account
		bank	String [1-3] Numeric value	Bank number
		transit	String [1-5] Numeric value	Transit number
		account	String [7-12] Numeric value	Account number
	debit_account		Object	Debit bank account
		bank	String [1-3] Numeric value	Bank number
		transit	String [1-5] Numeric value	Transit number
		account	String [7-12] Numeric value	Account number
	interchange_plus		Object	Interchange Plus parameters
	convenience_fee		Object	Convenience Fee parameters
	discount_fee		Object	Discount Fee parameters

If card payments are to be accepted by the merchant then the request must include at least one of the following objects:

interchange_plus

discount_fee

convenience_fee

Following combinations are allowed if more than one of the above objects is included:

interchange_plus, convenience_fee

discount_fee, convenience_fee

Interchange Plus 

Field					Values	Description
interchange_plus					Object - child of card_payment	Interchange Plus parameters
	visa				Object	Visa parameters
		acceptance			Object	Specifies whether Visa card brand is to be accepted
			credit		String [1]	Specifies whether Visa Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether Visa Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	Visa Credit fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
			debit		Object	Visa Debit fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
			commercial		Object	Visa Commercial fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
	mcrd				Object	MasterCard parameters
		acceptance			Object	Specifies whether MasterCard card brand is to be accepted
			credit		String [1]	Specifies whether MasterCard Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether MasterCard Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	MasterCard Credit fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
			debit		Object	MasterCard Debit fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
			commercial		Object	MasterCard Commercial fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
	amex				Object	AMEX parameters
		acceptance			Object	Specifies whether AMEX card brand is to be accepted
			credit		String [1]	Specifies whether AMEX Credit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	AMEX Credit fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)
	jcb				Object	JCB parameters
		acceptance			Object	Specifies whether JCB card brand is to be accepted
			credit		String [1]	Specifies whether JCB Credit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	JCB Credit fees
				basis_points	Integer value	Basis points
				transaction	Integer value	Transaction fees (in cents)

Discount Fee 

Field					Values	Description
discount_fee					Object - child of card_payment	Discount Fee parameters
	visa				Object	Visa parameters
		acceptance			Object	Specifies whether Visa card brand is to be accepted
			credit		String [1]	Specifies whether Visa Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether Visa Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	Visa Credit fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
			debit		Object	Visa Debit fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
			commercial		Object	Visa Commercial fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
	mcrd				Object	MasterCard parameters
		acceptance			Object	Specifies whether MasterCard card brand is to be accepted
			credit		String [1]	Specifies whether MasterCard Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether MasterCard Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	MasterCard Credit fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
			debit		Object	MasterCard Debit fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
			commercial		Object	MasterCard Commercial fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
	amex				Object	AMEX parameters
		acceptance			Object	Specifies whether AMEX card brand is to be accepted
			credit		String [1]	Specifies whether AMEX Credit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	AMEX Credit fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)
	jcb				Object	JCB parameters
		acceptance			Object	Specifies whether JCB card brand is to be accepted
			credit		String [1]	Specifies whether JCB Credit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	JCB Credit fees
				discount_rate	Numeric value, 2 decimal places	Discount rate
				transaction	Integer value	Transaction fees (in cents)

Convenience Fee 

Convenience fees can be setup as either a percentage or based on amount ranges. Tables are provided below with request field details for each option.

Convenience Fee - percentage option

Field					Values	Description
convenience_fee					Object - child of card_payment	Convenience Fee parameters
	visa				Object	Visa parameters
		acceptance			Object	Specifies whether Visa card brand is to be accepted
			credit		String [1]	Specifies whether Visa Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether Visa Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	Visa Credit fees
				rate	Numeric value, 2 decimal places	Rate
			debit		Object	Visa Debit fees
				rate	Numeric value, 2 decimal places	Rate
			commercial		Object	Visa Commercial fees
				rate	Numeric value, 2 decimal places	Rate
	mcrd				Object	MasterCard parameters
		acceptance			Object	Specifies whether MasterCard card brand is to be accepted
			credit		String [1]	Specifies whether MasterCard Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether MasterCard Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	MasterCard Credit fees
				rate	Numeric value, 2 decimal places	Rate
			debit		Object	MasterCard Debit fees
				rate	Numeric value, 2 decimal places	Rate
			commercial		Object	MasterCard Commercial fees
				rate	Numeric value, 2 decimal places	Rate

Convenience Fee - amount range option

Field					Values	Description
convenience_fee					Object - child of card_payment	Convenience Fee parameters
	visa				Object	Visa parameters
		acceptance			Object	Specifies whether Visa card brand is to be accepted
			credit		String [1]	Specifies whether Visa Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether Visa Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	Visa Credit fees
				range	Array Object	Amount ranges & fees
			debit		Object	Visa Debit fees
				range	Array Object	Amount ranges & fees
			commercial		Object	Visa Commercial fees
				range	Array Object	Amount ranges & fees
	mcrd				Object	MasterCard parameters
		acceptance			Object	Specifies whether MasterCard card brand is to be accepted
			credit		String [1]	Specifies whether MasterCard Credit is to be accepted ‘Y’ or ‘N’
			debit		String [1]	Specifies whether MasterCard Debit is to be accepted ‘Y’ or ‘N’
		fees			Object	Fees
			credit		Object	MasterCard Credit fees
				range	Array Object	Amount ranges & fees
			debit		Object	MasterCard Debit fees
				range	Array Object	Amount ranges & fees
			commercial		Object	MasterCard Commercial fees
				range	Array Object	Amount ranges & fees

Range array syntax:

{"range":[[amount1, fee1],[amount2, fee2],[amount3, fee3]]}

Each array item includes maximum payment amount and associated fee to be charged for the range

Template Examples 

Some of the factors used to determine the request field requirements for an API user account:

Type of merchant accounts to be setup, e.g., individual merchant account, Payment Facilitator sub-merchant

Fee model to be setup for merchant accounts, e.g., Interchange Plus, Discount Fee

Examples are provided below for templates that would typically apply for individual merchant and Payment Facilitator sub-merchant account setups. Request fields are specified as being Required, Optional, or Rejected where Rejected means that a value is not to be provided.

Payment Facilitator Sub-Merchant 

Merchant Add 

request_id					Required
action					Optional
terminal_id					Rejected
legal_entity_name					Required
legal_entity_type					Required
legal_entity_contact_phone					Required
legal_entity_contact_email					Required
customer_service_phone					Required
url					Required
dba_name					Required
mcc					Optional
address					Required
	street				Required
	city				Required
	country				Required
	province				Required
	pc_zip				Required
owner_information					Required
	name				Required
	phone				Required
	email				Required
	country				Required
	date_of_birth				Required
primary_contact					Required
	name				Required
	phone				Required
	fax				Required
	email				Required
chargeback_contact					Required
	name				Required
	phone				Required
	fax				Required
	email				Required
admin_contact					Optional
	name				Required
	phone				Required
	fax				Required
	email				Required
tech_contact					Optional
	name				Required
	phone				Required
	fax				Required
	email				Required
pad_acceptance					Required
pad					Required if pad_acceptance = Y otherwise ignored
	account				Required
		bank			Required
		transit			Required
		account			Required
	returned_item_account				Optional
		bank			Required
		transit			Required
		account			Required
	threshold				Required
		max_transaction_amount			Required
		max_monthly_transaction_count			Required
		max_monthly_transaction_volume			Required
	fees				Required
		transaction			Required
		reject			Required
		return			Required
	funding_days				Optional
cheque_acceptance					Optional
cheque					Required if cheque_acceptance = Y otherwise ignored
	account				Required
		bank			Required
		transit			Required
		account			Required
	threshold				Optional
		max_transaction_amount			Required
		max_monthly_transaction_count			Required
		max_monthly_transaction_volume			Required
	fees				Required
		transaction			Required
		reject			Required
		return			Required
	funding_days				Optional
eft_payment_acceptance					Optional
eft_payment					Required if eft_payment_acceptance = Y otherwise ignored
	account				Required
		bank			Required
		transit			Required
		account			Required
	fees				Required
		transaction			Required
		reject			Required
		return			Required
	funding_days				Optional
card_payment_acceptance					Required
card_payment					Required if card_payment_acceptance = Y otherwise ignored
	credit_account				Rejected
	debit_account				Rejected
	interchange_plus				Required
		visa			Required
			acceptance		Required
				credit	Required
				debit	Required
			fees		Rejected
		mcrd			Required
			acceptance		Required
				credit	Required
				debit	Required
			fees		Rejected
		amex			Required
			acceptance		Required
				credit	Required
			fees		Rejected
		jcb			Required
			acceptance		Required
				credit	Required
			fees		Rejected
	discount_fee				Rejected
	convenience_fee				Rejected

Individual Merchant 

Merchant Add 

request_id						Required
action						Optional
terminal_id						Rejected
legal_entity_name						Required
legal_entity_type						Required
legal_entity_contact_phone						Required
legal_entity_contact_email						Required
customer_service_phone						Required
url						Required
dba_name						Required
mcc						Optional
address						Required
	street					Required
	city					Required
	country					Required
	province					Required
	pc_zip					Required
owner_information						Required
	name					Required
	phone					Required
	email					Required
	country					Required
	date_of_birth					Optional
primary_contact						Required
	name					Required
	phone					Required
	fax					Required
	email					Required
chargeback_contact						Required
	name					Required
	phone					Required
	fax					Required
	email					Required
admin_contact						Optional
	name					Required
	phone					Required
	fax					Required
	email					Required
tech_contact						Optional
	name					Required
	phone					Required
	fax					Required
	email					Required
pad_acceptance						Required
pad						Required if pad_acceptance = Y otherwise ignored
	account					Required
		bank				Required
		transit				Required
		account				Required
	returned_item_account					Optional
		bank				Required
		transit				Required
		account				Required
	threshold					Required
		max_transaction_amount				Required
		max_monthly_transaction_count				Required
		max_monthly_transaction_volume				Required
	fees					Required
		transaction				Required
		reject				Required
		return				Required
	funding_days					Optional
cheque_acceptance						Required
cheque						Required if cheque_acceptance = Y otherwise ignored
	account					Required
		bank				Required
		transit				Required
		account				Required
	threshold					Optional
		max_transaction_amount				Required
		max_monthly_transaction_count				Required
		max_monthly_transaction_volume				Required
	fees					Required
		transaction				Required
		reject				Required
		return				Required
	funding_days					Optional
eft_payment_acceptance						Required
eft_payment						Required if eft_payment_acceptance = Y otherwise ignored
	account					Required
		bank				Required
		transit				Required
		account				Required
	fees					Required
		transaction				Required
		reject				Required
		return				Required
	funding_days					Optional
card_payment_acceptance						Required
card_payment						Required if card_payment_acceptance = Y otherwise ignored
	credit_account					Required
		bank				Required
		transit				Required
		account				Required
	debit_account					Required
		bank				Required
		transit				Required
		account				Required
	interchange_plus					Optional
		visa				Required
			acceptance			Required
				credit		Required
				debit		Required
			fees			Required
				credit		Required
					basis_points	Required
					transaction	Required
				debit		Required
					basis_points	Required
					transaction	Required
				commercial		Required
					basis_points	Required
					transaction	Required
		mcrd				Required
			acceptance			Required
				credit		Required
				debit		Required
			fees			Required
				credit		Required
					basis_points	Required
					transaction	Required
				debit		Required
					basis_points	Required
					transaction	Required
				commercial		Required
					basis_points	Required
					transaction	Required
		amex				Required
			acceptance			Required
				credit		Required
			fees			Required
				credit		Required
					basis_points	Required
					transaction	Required
		jcb				Required
			acceptance			Required
				credit		Required
			fees			Required
				credit		Required
					basis_points	Required
					transaction	Required
	discount_fee					Optional
		visa				Required
			acceptance			Required
				credit		Required
				debit		Required
			fees			Required
				credit		Required
					discount_rate	Required
					transaction	Required
				debit		Required
					discount_rate	Required
					transaction	Required
				commercial		Required
					discount_rate	Required
					transaction	Required
		mcrd				Required
			acceptance			Required
				credit		Required
				debit		Required
			fees			Required
				credit		Required
					discount_rate	Required
					transaction	Required
				debit		Required
					discount_rate	Required
					transaction	Required
				commercial		Required
					discount_rate	Required
					transaction	Required
		amex				Required
			acceptance			Required
				credit		Required
			fees			Required
				credit		Required
					discount_rate	Required
					transaction	Required
		jcb				Required
			acceptance			Required
				credit		Required
			fees			Required
				credit		Required
					discount_rate	Required
					transaction	Required
	convenience_fee					Optional
		visa				Required
			acceptance			Required
				credit		Required
				debit		Required
			fees			Required
				credit		Required
					rate	Optional
					range	Rejected if rate specified otherwise Optional
				debit		Required
					rate	Optional
					range	Rejected if rate specified otherwise Optional
				commercial		Required
					rate	Optional
					range	Rejected if rate specified otherwise Optional
		mcrd				Required
			acceptance			Required
				credit		Required
				debit		Required
			fees			Required
				credit		Required
					rate	Optional
					range	Rejected if rate specified otherwise Optional
				debit		Required
					rate	Optional
					range	Rejected if rate specified otherwise Optional
				commercial		Required
					rate	Optional
					range	Rejected if rate specified otherwise Optional

Request Examples 

Payment Facilitator Request Examples 

Merchant Add - PAD Processing 

{
  "request_id": "request0001",
  "legal_entity_name":"Sample",
  "legal_entity_type":"CRPPUB",
  "legal_entity_contact_phone":"416 123-4567",
  "legal_entity_contact_email":"[email protected]",
  "customer_service_phone":"416 123-4567",
  "url":"www.example.com",
  "dba_name": "Retailer",
  "address":{
    "street":"2275 Upper Middle Rd.",
    "city":"Oakville",
    "country": "CA",
    "province": "ON",
    "pc_zip": "L6H0C3"
  },
  "pad_acceptance": "Y",
  "pad":{
    "account":{
       "bank": "001",
       "transit": "12345",
       "account": "1234556"
    },
    "returned_item_account":{
       "bank": "001",
       "transit": "12345",
       "account": "1234556"
    },
    "threshold":{
       "max_transaction_amount":"199999",
       "max_monthly_transaction_count":"500",
       "max_monthly_transaction_volume":"6900000"
    }
  },
  "cheque_acceptance": "N"
}

Notes:: returned_item_account object is optional for PAD processing

Merchant Add - Cheque Processing 

{
  "request_id": "request0001",
  "legal_entity_name":"Sample",
  "legal_entity_type":"CRPPUB",
  "legal_entity_contact_phone":"416 123-4567",
  "legal_entity_contact_email":"[email protected]",
  "customer_service_phone":"416 123-4567",
  "url":"www.example.com",
  "dba_name": "Retailer",
  "address":{
    "street":"2275 Upper Middle Rd.",
    "city":"Oakville",
    "country": "CA",
    "province": "ON",
    "pc_zip": "L6H0C3"
  },
  "pad_acceptance": "N",
  "cheque_acceptance": "Y",
  "cheque":{
    "account":{
       "bank": "001",
       "transit": "12345",
       "account": "1234556"
    },
    "threshold":{
        "max_transaction_amount":"199999",
        "max_monthly_transaction_count":"500",
        "max_monthly_transaction_volume":"6900000"
    }
  }
}

Merchant Add - PAD & Cheque Processing 

{
  "request_id": "request0001",
  "legal_entity_name":"Sample",
  "legal_entity_type":"CRPPUB",
  "legal_entity_contact_phone":"416 123-4567",
  "legal_entity_contact_email":"[email protected]",
  "customer_service_phone":"416 123-4567",
  "url":"www.example.com",
  "dba_name": "Retailer",
  "address":{
    "street":"2275 Upper Middle Rd.",
    "city":"Oakville",
    "country": "CA",
    "province": "ON",
    "pc_zip": "L6H0C3"
  },
  "pad_acceptance": "Y",
  "pad":{
    "account":{
       "bank": "001",
       "transit": "12345",
       "account": "1234556"
    },
    "returned_item_account":{
       "bank": "001",
       "transit": "12345",
       "account": "1234556"
    },
    "threshold":{
        "max_transaction_amount":"199999",
        "max_monthly_transaction_count":"500",
        "max_monthly_transaction_volume":"6900000"
    }
  },
  "cheque_acceptance": "Y"
}

Notes:: returned_item_account object is optional for PAD processing

Merchant Update - Add Cheque Processing for merchant accepting PAD 

{
   "request_id": "request1",
   "action": "update",
   "terminal_id": "EXAMPLE1",
   "cheque_acceptance": "Y"
}

Merchant Update – Add PAD processing for merchant accepting Cheque payments 

{
  "request_id": "request1",
  "action": "update",
  "terminal_id": "EXAMPLE1",
  "pad_acceptance": "Y",
  "pad":{
    "returned_item_account":{
       "bank": "001",
       "transit": "12345",
       "account": "1234556"
    }
  }
}

Notes:: returned_item_account object is optional for PAD processing

Merchant Update –Account information & Risk Thresholds 

{
  "request_id": "request1",
  "action": "update",
  "terminal_id": "EXAMPLE1",
  "pad":{
    "account":{
       "bank": "001",
       "transit": "12345",
       "account":"123456789"
    },
    "threshold":{
        "max_transaction_amount":"199999",
        "max_monthly_transaction_count":"500",
        "max_monthly_transaction_volume":"6900000"
    }
  }
}


{
  "request_id": "request1",
  "action": "update",
  "terminal_id": "EXAMPLE1",
  "cheque":{
    "account":{
       "bank": "001",
       "transit": "12345",
       "account":"123456789"
    },
    "threshold":{
        "max_transaction_amount":"199999",
        "max_monthly_transaction_count":"500",
        "max_monthly_transaction_volume":"6900000"
    }
  }
}

Notes:: Account information and thresholds can be updated by including either the pad or cheque object in a boarding request as the same fields are used for PAD & Cheque payment processing. Update requests are not currently supported that include both the pad and cheque objects.

Individual Merchant Request Examples 

Merchant Add 

Request including only PAD payment acceptance:

{
    "request_id": "request0001",
    "legal_entity_name":"Sample",
    "legal_entity_type":"CRPPUB",
    "legal_entity_contact_phone":"416 123-4567",
    "legal_entity_contact_email":"[email protected]",
    "customer_service_phone":"416 123-4567",
    "url":"www.example.com",
    "dba_name": "Retailer",
    "address":{
        "street":"2275 Upper Middle Rd.",
        "city":"Oakville",
        "country": "CA",
        "province": "ON",
        "pc_zip": "L6H0C3"
    },
    "owner_information":{
        "name":"Owner Name",
        "phone": "416 123-4567",
        "email": "[email protected]",
        "country": "CA",
        "date_of_birth": "20000101"
    },
    "primary_contact":{
        "name":"Contact A",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "chargeback_contact":{
        "name":"Contact B ",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "admin_contact":{
        "name":"Contact C",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "tech_contact":{
        "name":"Contact D",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "pad_acceptance": "Y",
    "pad":{
        "account":{
           "bank": "001",
           "transit": "12345",
           "account": "1234556"
        },
        "returned_item_account":{
           "bank": "001",
           "transit": "12345",
           "account": "1234556"
        },
        "threshold":{
            "max_transaction_amount":"199999",
            "max_monthly_transaction_count":"500",
            "max_monthly_transaction_volume":"6900000"
        },
        "fees":{
            "transaction": "8",
            "reject": "1500",
            "return": "1500"
        }
    },
    "cheque_acceptance": "N",
    "eft_payment_acceptance": "N",
    "card_payment_acceptance": "N"
}

Request including PAD and Card payments with both Interchange Plus fees and Convenience fees:

{
    "request_id": "request0001",
    "legal_entity_name":"Sample",
    "legal_entity_type":"CRPPUB",
    "legal_entity_contact_phone":"416 123-4567",
    "legal_entity_contact_email":"[email protected]",
    "customer_service_phone":"416 123-4567",
    "url":"www.example.com",
    "dba_name": "Retailer",
    "mcc": "1234",
    "address":{
        "street":"2275 Upper Middle Rd.",
        "city":"Oakville",
        "country": "CA",
        "province": "ON",
        "pc_zip": "L6H0C3"
    },
    "owner_information":{
        "name":"Owner Name",
        "phone": "416 123-4567",
        "email": "[email protected]",
        "country": "CA",
        "date_of_birth": "20000101"
    },
    "primary_contact":{
        "name":"Contact A",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "chargeback_contact":{
        "name":"Contact B ",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "admin_contact":{
        "name":"Contact C",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "tech_contact":{
        "name":"Contact D",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "[email protected]"
    },
    "pad_acceptance": "Y",
    "pad":{
        "account":{
           "bank": "001",
           "transit": "12345",
           "account": "1234556"
        },
        "returned_item_account":{
           "bank": "001",
           "transit": "12345",
           "account": "1234556"
        },
        "threshold":{
           "max_transaction_amount":"199999",
           "max_monthly_transaction_count":"500",
           "max_monthly_transaction_volume":"6900000"
        },
        "fees":{
           "transaction": "8",
           "reject": "1500",
           "return": "1500"
        }
    },
    "cheque_acceptance": "N",
    "eft_payment_acceptance": "N",
    "card_payment_acceptance": "Y",
    "card_payment":{
        "credit_account":{
            "bank":"001",
            "transit":"12345",
            "account": "123456789"
        },
        "debit_account":{
            "bank":"001",
            "transit":"12345",
            "account": "123456789"
        },
        "interchange_plus":{
            "visa":{
                "acceptance": {"credit":"Y", "debit":"Y"},
                "fees":{
                    "credit": {"basis_points":"15", "transaction":"110"},
                    "debit": {"basis_points":"15", "transaction":"110"},
                    "commercial": {"basis_points":"15", "transaction":"110"}
                },
            },
            "mcrd":{
                "acceptance": {"credit":"Y", "debit":"Y"},
                "fees":{
                    "credit": {"basis_points":"15", "transaction":"110"},
                    "debit": {"basis_points":"15", "transaction":"110"},
                    "commercial": {"basis_points":"15", "transaction":"110"}
                }
            }
            "amex":{
                "acceptance": {"credit":"Y"},
                "fees":{
                    "credit": {"basis_points":"15", "transaction":"110"},
                }
            }
            "jcb":{
                "acceptance": {"credit":"Y"},
                "fees":{
                    "credit": {"basis_points":"15", "transaction":"110"},
                }
            }
        },
        "convenience_fee":{
            "visa": {
                "acceptance": {"credit":"Y", "debit":"Y" },
                "fees":{
                    "credit": {"rate":"0.75"},
                    "debit": {"rate":"0.75"},
                    "commercial": {"rate":"0.75"}
                }
            },
            "mcrd":{
                "acceptance":{"credit":"Y", "debit":"Y"},
                "fees":{
                    "credit": {"rate":"0.75"},
                    "debit": {"rate":"0.75"},
                    "commercial":{"rate":"0.75"}
                }
            }
        }
    }
}

Following is sample snippet for merchant setup with Discount Fee setup:

{
   "discount_fee": {
       "visa": {
           "acceptance":{"credit":"Y", "debit":"Y"},
           "fees":{
               "credit": {"discount_rate":"2.50", "transaction":"10"},
               "debit": {"discount_rate":"2.50", "transaction":"10"},
               "commercial": {"discount_rate":"2.50", "transaction":"10"}
           }
       },
       "mcrd": {
           "acceptance": {"credit":"Y", "debit":"Y"},
           "fees":{
               "credit": {"discount_rate":"2.50", "transaction":"10"},
               "debit": {"discount_rate":"2.50", "transaction":"10"},
               "commercial": {"discount_rate":"1.00" , "transaction":"110"}
           }
       }
       "amex": {
           "acceptance": {"credit":"Y"},
           "fees":{
               "credit": {"discount_rate":"2.50", "transaction":"10"},
           }
       }
       "jcb": {
           "acceptance": {"credit":"Y"},
           "fees":{
               "credit": {"discount_rate":"2.50", "transaction":"10"},
           }
       }
   }
}

Following is sample snippet for merchant setup with Convenience Fee amount ranges:

{
   "convenience_fee":{
       "visa":{
           "acceptance": {"credit":"Y", "debit":"Y"},
           "fees":{
               "credit": {"range":[[1000, 105],[2000, 250],[3000, 315]]},
               "debit": {"range":[[1000, 105],[2000, 250],[3000, 315]]},
               "commercial": {"range":[[1000, 105],[2000, 250],[3000, 315]]}
           }
       },
       "mcrd": {
           "acceptance": {"credit":"Y", "debit":"Y"},
           "fees":{
               "credit": {"range":[[1000, 105],[2000, 250],[3000, 315]]},
               "debit": {"range":[[1000, 105],[2000, 250],[3000, 315]]},
               "commercial": {"range":[[1000, 105],[2000, 250],[3000, 315]]}
           }
       }
   }
}

Merchant Update 

{
   "request_id": "request1",
   "action": "update",
   "terminal_id": "EXAMPLE1",
   "pad":{
       "account":{
           "bank": "001",
           "transit": "12345",
           "account":"123456789"
       },
       "returned_item_account":{
           "bank": "001",
           "transit": "12345",
           "account": "1234556"
       }
   }
}

Merchant Deactivate 

{
   "request_id": "request1",
   "action": "deactivate",
   "terminal_id": "EXAMPLE1"
}

Response 

For successful requests, HTTP 202 will be returned with the following object:

{
    "message": "",
    "details":{}
}

For failed requests, HTTP 4xx code is returned. Depending on the scenario, the following object may be returned with the error messages attached to the corresponding fields:

{
    "message": "Invalid data",
    "details":{
        "legal_entity_name":"0",
        "legal_entity_type":"Invalid",
        "address":{
            "street":"0",
            "city":"0",
            "country": "0",
            "province": "Invalid",
            "pc_zip": "0"
        }
    }
}

Note: fields with a “0” or empty string indicate that the values passed validation

For some HTTP codes, such as 405, 415, 404, an empty body will be returned.

Notification 

A notification ( HTTP POST with JSON string ) is sent back to customer’s server after a request has been reviewed and approved or declined by Payroc Merchant Services.

Customer’s server is expected to return an HTTP 200 code when the notification is received. Delivery of notification will be retried up to 3 times if HTTP 200 is not returned by the customer’s server.

HTTP Headers will include:

Content-Type

application/json

X-User-ID

This is the same X-User-ID which submitted the request

X-Message-Hash

X-Message-Hash will be calculated using the secret key from the API user specified by X-User-ID and the JSON payload in the notification.

The hash will be generated using HMAC-SHA256 algorithm - see RFC 2104 for details.

X-Message-Hash will be base64 encoded.

Fields that can be included in the notification message

Field						Values	Description
status						String[1-32]	‘Pending’, ‘Approved’, ‘Declined’
message						String	Reserved
details						Object
	request_id					String
	action					String[1-16]	‘add’, ‘update’, ‘deactivate’
	pad					Object	If PAD payment is setup
		terminal_id				String[8]	Assigned by Payroc
	cheque					Object	If Cheque payment is setup
		terminal_id				String[8]
	eft_payment					Object	If EFT payment is setup
		terminal_id				String[8]
	card_payment					Object	If Card payment is setup
		interchange_plus				Object
			terminal_id			String[8]
			bp_gateway_id			String	Certain customer only
			bp_secret_key			String	Certain customer only
				acquirer_merchant_id		Object
					visa	String[16]	Assigned by Payroc for VISA
					mcrd	String[16]	Assigned by Payroc for MCRD
					amex	String[16]	Assigned by Payroc for AMEX
					jcb	String[16]	Assigned by Payroc for JCB
		convenience_fee				Object
			terminal_id			String[8]
				acquirer_merchant_id		Object
					visa	String[16]	Assigned by Payroc for VISA
					mcrd	String[16]	Assigned by Payroc for MCRD
					amex	String[16]	Assigned by Payroc for AMEX
					jcb	String[16]	Assigned by Payroc for JCB
		discount_fee				Object
			terminal_id			String[8]
			bp_gateway_id			String	Certain customer only
			bp_secret_key			String	Certain customer only
				acquirer_merchant_id		Object
					visa	String[16]	Assigned by Payroc for VISA
					mcrd	String[16]	Assigned by Payroc for MCRD
					amex	String[16]	Assigned by Payroc for AMEX
					jcb	String[16]	Assigned by Payroc for JCB

Sample notification for approved request:

{
    "status": "Approved",
    "message": "",
    "details": {
        "request_id": "request0001",
        "action": "add",
        "pad":{
            "terminal_id":"INTG0001"
        },

        "card_payment":{
            "interchange_plus":{
                "terminal_id":"INTG0001",
                "acquirer_merchant_id":{
                    "visa": "1234567890123456",
                    "mcrd": "1234567890123456",
                    "amex": "1234567890123456",
                    "jcb": "1234567890123456"
                },
                "bp_gateway_id":"100000123000",
                "bp_secret_key":"9c24c7bd1d2b2354e4bd84a578e91b46"
            }
        }
    }
}

Sample notification for declined request:

{
    "status": "Declined",
    "message": "",
    "details":{
        "request_id": "request0001",
        "action": "add",
        "message":"Merchant already exists"
    }
}

Status Update 

Status update process provides Payroc’s customers/partners with an alternative to Notification process. Instead of receiving a Notification message from Payroc’s API server, customers/partners would be able to submit a request to determine if the status of a merchant setup has been updated.

Status update for a merchant setup can be obtained by submitting a HTTPS GET including the boarding request_id along with a timestamp;

https://api.caledoncard.com/boarding/request/<url_encoded_request_id>/<epoch>

Timestamp (epoch) is to specify when the status update request was initiated.

HTTP header must include same set of values as specified in Authentication section:

Content-Type: application/json

X-User-ID: <Base 64 encoded User ID>

X-Message-Hash: <Base64 encoded result of hash function>

Message hash for status update requests is calculated using the API Key provided by Payroc and request_id concatenated with epoch. Hash is to be generated using HMAC-SHA256 algorithm.

Status Update responses include:

HTTP 401 Unauthorized will be returned if the request failed to pass the authentication.

{
  "message": "",
  "details": {}
}

HTTP 400 Bad request will be returned if the epoch is outside of allowed time period

{
  "message": "Request expired",
  "details": {}
}

HTTP 404 Not found will be returned if the request ID does not exist

{
  "message": "",
  "details": {}
}

HTTP 200 Ok will be returned if the boarding request is still pending.

{
  "message":"",
  "status":"Pending",
  "details":{}
}

HTTP 200 Ok will be returned if the boarding request has been approved

{
  "message": "",
  "status":"Approved",
  "details":{
    "request_id": "request0001",
    "action": "add",
    "pad":{
      "terminal_id":"INTG0001"
    },
    "card_payment":{
      "interchange_plus":{
        "terminal_id":"INTG0001",
        "acquirer_merchant_id":{
          "visa": "1234567890123456",
          "mcrd": "1234567890123456",
          "amex": "1234567890123456",
          "jcb": "1234567890123456"
        },
        "bp_gateway_id":"100000123000",
        "bp_secret_key":"9c24c7bd1d2b2354e4bd84a578e91b46"
      }
    }
  }
}

HTTP 200 will be returned if the boarding request was declined.

{
  "message":"",
  "status":"Declined",
  "details":{
    "request_id":"request0001",
    "action": "add",
    "message":"Merchant already exists"
  }
}