Third-Party Merchant Onboarding & Updating

Summary

Create and manage merchants for a third-party acquirer integration using the Moneris Merchant Onboarding APIs.

ISVs and partner acquirers can programmatically create Moneris merchant profiles, retrieve the latest merchant information , and update key merchant/contact details for new merchants without manual back-and-forth—reducing time-to-live and operational overhead.

Use Case Overview

Implement this when your partner platform needs to:

Submit a new merchant application and banking profile.
Retrieve merchant details and status using the assigned merchantId.
Update net new merchant/contact details via partial updates before placing the first order.

Steps

Partner Platform submits Create Merchant with the full onboarding payload.
Moneris persists merchant profile and banking details.
Moneris acknowledges creation and assigns a merchantId.
API responds 201 Created with headers and a merchant body.

Optional:

Partner retrieves merchant details by merchantId.
API responds 200 OK with the merchant object.
Partner issues PATCH Update Merchant details to change contact/merchant fields.
Moneris applies updates in backoffice systems.
Moneris confirms changes.
API responds 200 OK with updated merchantDetails.

📘
Systems involved

Partner Platform (your back end / onboarding UI)

Moneris PayFac as a Service API (Merchant Onboarding)

Moneris Backoffice Systems (credit, risk, provisioning, records)

APIs used

POST /onboarding/merchants — Create Merchant

GET /onboarding/merchants/{merchant-id} — Get Merchant details

PATCH /onboarding/merchants/{merchant-id} — Update Merchant details (partial, application/merge-patch+json)

Prerequisites

OAuth2 access with scopes:

onboarding.merchant.write (create/update)

onboarding.merchant.read (retrieve)

Api-Version and X-Correlation-Id headers sent on all requests.

Partner has a valid Moneris-issued merchant-id path parameter for GET/PATCH operations.

1. Create Merchant (POST)

Start a new merchant profile with business, banking, and security details so that an order can be placed for the merchant and downstream provisioning and risk checks can proceed.

Endpoint :

POST /onboarding/merchants –

Required Inputs:

The merchantPayload object is required, which itself requires: bankingDetails, businessDetails, merchantDetails, businessActivity, securityDetails.

NOTE: For third-party acquirers, it is mandatory to pass in a chainId that is provisioned by Moneris to link all merchants of the third-party acquirer and for identification on type of ISV.

{
"idempotencyKey": "6q5w4e7r8t9y",
"chainId": "0030400001622",
"bankingDetails": {
"creditDepositAccount": {
  "currency": "CAD",
  "institutionNumber": 809,
  "transitNumber": "00160",
  "accountNumber": "string"
},
"additionalBankingAccounts": [
  {
    "currency": "CAD",
    "institutionNumber": 809,
    "transitNumber": "00160",
    "accountNumber": "string",
    "accountType": "POS_BILLING_ACCOUNT"
  }
]
},
"pointOfSaleOptions": {
"settlementOption": "SYSTEM_CLOSE",
"settlementTime": "18:10:00",
"debitPerTransactionRefundLimit": {
  "amount": 16000,
  "currency": "CAD"
},
"dailyRefundLimit": {
  "amount": 16000,
  "currency": "CAD"
},
"dailyCancellationLimit": {
  "amount": 16000,
  "currency": "CAD"
}
},
"businessDetails": {
"merchantCategoryCode": "0742",
"averageTicketSize": 0,
"isSeasonalMerchant": true,
"maximumTransactionVolume": 0,
"directSellingPercentage": 90.5,
"motoTransactionPercentage": 90.5,
"ecommerceTransactionPercentage": 90.5,
"businessUrl": "www.abc.com",
"serviceProvider": "moneris.com",
"serviceDeliverToCanadaAvailable": true,
"serviceDeliverToUSAvailable": true,
"creditTransactionVolume": 0,
"masterCardTransactionVolume": 0,
"visaTransactionVolume": 0,
"visaDebitTransactionVolume": 42,
"amexTransactionVolume": 1000,
"interacTransactionVolume": 1000,
"masterCardDebitTransactionVolume": 1000,
"unionPayTransactionVolume": 1000,
"discoverTransactionVolume": 1000,
"category": "RESTAURANTS",
"subCategory": "A_1_RENT_A_CAR",
"offeredProductsAndServicesDescription": "food",
"riskLevel": "LOW"
},
"merchantDetails": {
"contactInformation": {
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+18663197450"
},
"merchantInformation": {
  "language": "en",
  "legalName": "Pizza 2 Go",
  "operatingAsName": "Pizza 2 Go",
  "cardholderName": "John Doe",
  "yearsOfOwnership": 0,
  "monthsOfOwnership": 0,
  "customerServicePhoneNumber": "+18663197450",
  "email": "[email protected]",
  "merchantType": "NATIONAL"
},
"locationAddress": {
  "unitNumber": "123A",
  "streetNumber": "3300",
  "streetName": "Bloor Street West",
  "city": "Toronto",
  "province": "ON",
  "postalCode": "M8X 2X2",
  "country": "CA"
},
"marketSegment": "PAYROC"
},
"businessActivity": {
"dropShipping": true
},
"securityDetails": {
"legalEntity": {
  "businessType": "SOLE_PROPRIETOR"
},
"signingOfficers": [
  {
    "signingOfficerIdentifier": 0,
    "creditReportAllowed": true,
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "unitNumber": "123A",
      "streetNumber": "3300",
      "streetName": "Bloor Street West",
      "city": "Toronto",
      "province": "ON",
      "postalCode": "M8X 2X2",
      "country": "CA"
    },
    "dateOfBirth": "2019-07-30",
    "ownershipPercentage": 90.5,
    "title": "OWNER",
    "merchantRiskRate": "A+"
  }
]
},
"riskDetails": {
"merchantRiskRate": "A+"
}
}

2. Retrieve Merchant Details (GET)

Fetch the current merchant profile for status display or CRM synchronization.

Endpoint:

GET /onboarding/merchants/{merchant-id}

Required Inputs

merchant-id (path, V13)

Response

{
  "merchantId": "0030211900875",
  "businessDetails": {
    "isSeasonalMerchant": false,
    "merchantCategoryCode": "0742",
    "averageTicketSize": 3,
    "directSellingPercentage": 86,
    "motoTransactionPercentage": 14,
    "ecommerceTransactionPercentage": 0,
    "businessUrl": "https://www.test.io",
    "serviceProvider": "moneris.com",
    "serviceDeliverToCanadaAvailable": true,
    "serviceDeliverToUSAvailable": true,
    "creditTransactionVolume": 250000,
    "masterCardTransactionVolume": 100000,
    "visaTransactionVolume": 100000,
    "visaDebitTransactionVolume": 0,
    "amexTransactionVolume": 25000,
    "interacTransactionVolume": 50000,
    "masterCardDebitTransactionVolume": 0,
    "category": "CONTRACTED_SERVICES",
    "subCategory": "VETERINARY_SERVICES",
    "offeredProductsAndServicesDescription": "food"
  },
  "merchantDetails": {
    "contactInformation": {
      "firstName": "Joe",
      "lastName": "Test",
      "phone": "+11234567890"
    },
    "merchantInformation": {
      "cardholderName": "Joe Test",
      "language": "en",
      "legalName": "Joe",
      "operatingAsName": "Joe OPS",
      "yearsOfOwnership": 3,
      "monthsOfOwnership": 2,
      "customerServicePhoneNumber": "+11234567890",
      "email": "[email protected]",
      "merchantType": "NATIONAL"
    },
    "locationAddress": {
      "postalCode": "M5T2G2",
      "city": "TORONTO",
      "province": "ON",
      "streetName": "SPADINA AVE",
      "country": "CA"
    }
  },
  "businessActivity": {
    "dropShipping": true
  },
  "securityDetails": {
    "legalEntity": {
      "businessType": "PRIVATE_CORPORATION"
    },
    "signingOfficers": [
      {
        "signingOfficerIdentifier": 1234,
        "dateOfBirth": "1980-01-01",
        "creditReportAllowed": true,
        "firstName": "DOMEMIC",
        "lastName": "TESTPOTKIDIS",
        "address": {
          "postalCode": "K1M1N8",
          "city": "OTTAWA",
          "province": "ON",
          "streetName": "STANLEY",
          "country": "CA"
        },
        "ownershipPercentage": 100,
        "title": "VICE_PRESIDENT"
      }
    ]
  },
  "riskDetails": {
    "merchantRiskRate": "A_PLUS"
  },
  "pointOfSaleOptions": {
    "settlementOption": "MERCHANT_CLOSE",
    "settlementTime": "23:00:00",
    "debitPerTransactionRefundLimit": {
      "amount": 0,
      "currency": "CAD"
    },
    "dailyRefundLimit": {
      "amount": 0,
      "currency": "CAD"
    },
    "dailyCancellationLimit": {
      "amount": 0,
      "currency": "CAD"
    }
  },
  "bankingDetails": {
    "creditDepositAccount": {
      "currency": "CAD",
      "institutionNumber": "00809",
      "transitNumber": "00160",
      "accountNumber": "3333333333"
    },
    "additionalBankingAccounts": []
  },
  "chainId": "0030600062664",
  "createdAt": "2025-01-01T00:00:00Z",
  "modifiedAt": "2025-01-01T00:00:00Z"
}

3. Update Merchant Details (PATCH)

Apply targeted account maintenance to merchant/contact info without resubmitting the full onboarding payload.

Endpoint:

PATCH /onboarding/merchants/{merchant-id}

Content Type:

application/merge-patch+json

{
"chainId": "0030400001622",
"bankingDetails": {
"creditDepositAccount": {
  "currency": "CAD",
  "institutionNumber": 809,
  "transitNumber": "00160",
  "accountNumber": "string"
},
"additionalBankingAccounts": [
  {
    "currency": "CAD",
    "institutionNumber": 809,
    "transitNumber": "00160",
    "accountNumber": "string",
    "accountType": "POS_BILLING_ACCOUNT"
  }
]
},
"pointOfSaleOptions": {
"settlementOption": "SYSTEM_CLOSE",
"settlementTime": "18:10:00",
"debitPerTransactionRefundLimit": {
  "amount": 16000,
  "currency": "CAD"
},
"dailyRefundLimit": {
  "amount": 16000,
  "currency": "CAD"
},
"dailyCancellationLimit": {
  "amount": 16000,
  "currency": "CAD"
}
},
"businessDetails": {
"merchantCategoryCode": "0742",
"averageTicketSize": 0,
"isSeasonalMerchant": true,
"maximumTransactionVolume": 0,
"directSellingPercentage": 90.5,
"motoTransactionPercentage": 90.5,
"ecommerceTransactionPercentage": 90.5,
"businessUrl": "www.abc.com",
"serviceProvider": "moneris.com",
"serviceDeliverToCanadaAvailable": true,
"serviceDeliverToUSAvailable": true,
"creditTransactionVolume": 0,
"masterCardTransactionVolume": 0,
"visaTransactionVolume": 0,
"visaDebitTransactionVolume": 42,
"amexTransactionVolume": 1000,
"interacTransactionVolume": 1000,
"masterCardDebitTransactionVolume": 1000,
"unionPayTransactionVolume": 1000,
"discoverTransactionVolume": 1000,
"category": "RESTAURANTS",
"subCategory": "A_1_RENT_A_CAR",
"offeredProductsAndServicesDescription": "food",
"riskLevel": "LOW"
},
"merchantDetails": {
"contactInformation": {
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+18663197450"
},
"merchantInformation": {
  "language": "en",
  "legalName": "Pizza 2 Go",
  "operatingAsName": "Pizza 2 Go",
  "cardholderName": "John Doe",
  "yearsOfOwnership": 0,
  "monthsOfOwnership": 0,
  "customerServicePhoneNumber": "+18663197450",
  "email": "[email protected]",
  "merchantType": "NATIONAL"
},
"locationAddress": {
  "unitNumber": "123A",
  "streetNumber": "3300",
  "streetName": "Bloor Street West",
  "city": "Toronto",
  "province": "ON",
  "postalCode": "M8X 2X2",
  "country": "CA"
},
"marketSegment": "PAYROC"
},
"businessActivity": {
"dropShipping": true
},
"securityDetails": {
"legalEntity": {
  "businessType": "SOLE_PROPRIETOR"
},
"signingOfficers": [
  {
    "signingOfficerIdentifier": 0,
    "creditReportAllowed": true,
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "unitNumber": "123A",
      "streetNumber": "3300",
      "streetName": "Bloor Street West",
      "city": "Toronto",
      "province": "ON",
      "postalCode": "M8X 2X2",
      "country": "CA"
    },
    "dateOfBirth": "2019-07-30",
    "ownershipPercentage": 90.5,
    "title": "OWNER",
    "merchantRiskRate": "A+"
  }
]
},
"riskDetails": {
"merchantRiskRate": "A+"
}
}

Notes

Handling Idempotency and Retries

If the platform times out after POST /onboarding/merchants, check for a created merchant using your stored merchantId (from the Location header or create response) before retrying. Use a new X-Correlation-Id per attempt.

Additional Notes

Send Api-Version and X-Correlation-Id on every call.
Use OAuth2 scopes as least-privilege: onboarding.merchant.read and onboarding.merchant.write.
All monetary amount values are in cents.
Validate merchant-id format (13 characters) before path substitution.

Additional Information

📘
Learn more with the API Definitions
Peruse the endpoints, request/response formats, and authentication methods covered in this scenario.
API References