Merchant Onboarding API

Version 2.7

May 9, 2023

PDF download

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":"contact@example.com",
  "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":"contact@example.com",
  "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":"contact@example.com",
  "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":"contact@example.com",
    "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": "o@example.com",
        "country": "CA",
        "date_of_birth": "20000101"
    },
    "primary_contact":{
        "name":"Contact A",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "a@example.com"
    },
    "chargeback_contact":{
        "name":"Contact B ",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "b@example.com"
    },
    "admin_contact":{
        "name":"Contact C",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "c@example.com"
    },
    "tech_contact":{
        "name":"Contact D",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "d@example.com"
    },
    "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":"contact@example.com",
    "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": "o@example.com",
        "country": "CA",
        "date_of_birth": "20000101"
    },
    "primary_contact":{
        "name":"Contact A",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "a@example.com"
    },
    "chargeback_contact":{
        "name":"Contact B ",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "b@example.com"
    },
    "admin_contact":{
        "name":"Contact C",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "c@example.com"
    },
    "tech_contact":{
        "name":"Contact D",
        "phone": "416 123-4567",
        "fax": "416 123-4567",
        "email": "d@example.com"
    },
    "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"
  }
}