Terminal & Service Ordering for New Merchants

Summary

Create a terminal/service order for a newly-onboarded merchant and monitor fulfillment.

Partners can programmatically provision hardware, services, and supplies at scale, reducing manual effort and speeding time-to-activate for new merchants.

Use Case Overview

Partners (ISVs, PayFacs, third-party acquirers) trigger an order once a merchant record exists. The Partner app calls Moneris PayFac as a Service’s Terminal & Service Orders APIs to submit the order and then polls for order status to drive downstream workflows (e.g., shipment notifications, POS enablement).

Key tasks this scenario enables:

Submit an order for terminals/services/supplies for a merchant
Receive the created order payload with fees, promotions, and supplies items
Retrieve order details to track status and fulfillment

📘
APIs used

POST /onboarding/merchants/{merchant-id}/orders — Create an order

GET /onboarding/merchants/{merchant-id}/orders/{merchant-order-id} — Retrieve an order

Prerequisites

Merchant is created and has a valid merchant-id.

Merchant must have a valid AgreementModelCode and RepresentativeCode provided by Moneris

API access with scopes:

onboarding.order.write for Create Order

onboarding.order.read for Retrieve Order

Authentication headers:

Api-Version

X-Correlation-Id

OAuth2 or ApiKey Auth

1. Create the Order (POST)

Submit the initial terminal/service/supplies order for the merchant.

Call POST /onboarding/merchants/{merchant-id}/orders with one of the supported request examples.

The API returns 201 Created with an order object representing the created order.

Required Inputs

merchant-id (path)
Request body matching

Create Order request (createOrderRequest)

Authentication headers:
- Api-Version
- X-Correlation-Id
- OAuth2 or ApiKey Auth

{
  "representativeCode": "0A",
  "userDetails": {
    "userIdentifier": "001",
    "firstName": "test",
    "lastName": "test"
  },
  "applicationDetails": {
    "applicationType": "NET_NEW_MERCHANT"
  },
  "marketSegment": "INTUIT",
  "applicablePromotions": [
    "1MONTHOFF",
    "3MONTHSOFF"
  ],
  "productDetails": {
    "cardPlanDetails": {
      "masterCard": {
        "cardBrandPlans": [
          { "merchantDiscountRate": 0.21, "transactionRate": 0.221, "feeTypeCode": "MASTERCARD_ASSESSMENT_FEE", "cardOriginCode": "ALL" },
          { "merchantDiscountRate": 0.23, "transactionRate": 0.231, "feeTypeCode": "MASTERCARD_ASSESSMENT_FEE_FOREIGN", "cardOriginCode": "FRGN" },
          { "merchantDiscountRate": 0.24, "transactionRate": 0.241, "feeTypeCode": "MASTERCARD_ASSESSMENT_FEE_FOREIGN", "cardOriginCode": "FRGN" },
          { "merchantDiscountRate": 0.25, "transactionRate": 0.251, "feeTypeCode": "MASTERCARD_ASSESSMENT_FEE_FOREIGN", "cardOriginCode": "IERR" },
          { "merchantDiscountRate": 0.26, "transactionRate": 0.261, "feeTypeCode": "MASTERCARD_ASSESSMENT_FEE_FOREIGN", "cardOriginCode": "IERR" }
        ],
        "serviceFeeDetails": {
          "maintenanceFee": {
            "feeType": "maintenance",
            "unitPrice": { "amount": 301, "currency": "USD" }
          }
        }
      },
      "programs": [ "MASTERCARD_PAY_PASS" ],
      "visa": {},
      "discover": {},
      "unionPay": {},
      "interac": {},
      "merchantDiscountRateType": "GROSS_GROSS",
      "currency": "CAD"
    }
  },
  "isExpeditedOrder": true,
  "orderCreatedBy": "jhundal@PERCOM",
  "isAutoAdjudicationRequired": true
}

2. Retrieve Order Details (GET)

Poll order status and details to drive fulfillment and notifications.

Call GET /onboarding/merchants/{merchant-id}/orders/{merchant-order-id}. The API returns 200 OK with the latest order details.

Required Inputs

merchant-id (path)
merchant-order-id (path)
Auth headers noted in Prerequisites

Response

{
    "merchantOrderId": 1471632,
    "merchantId": "0030211900586",
    "userIdentifier": "001",
    "representativeCode": "0A",
    "adjudicationRequired": true,
    "orderStatus": "APPLICATION_SUBMITTED",
    "orderType": "NET_NEW_MERCHANT",
    "orderOpenedAt": "2025-06-17T16:39:01.85-05:00",
    "orderChangedAt": "2025-06-17T17:40:55.577-05:00",
    "feeDetails": {
        "minimumMerchantDiscountRateFee": {
            "unitPrice": {
                "amount": 699,
                "currency": "CAD"
            },
            "taxes": []
        },
        "paperStatementFee": {
            "unitPrice": {
                "amount": 795,
                "currency": "CAD"
            },
            "taxes": []
        },
        "pciSecurityFee": {
            "unitPrice": {
                "amount": 895,
                "currency": "CAD"
            },
            "taxes": []
        }
    },
    "productDetails": {
        "cardPlanDetails": {
            "visaDebit": {
                "cardBrandPlans": [],
                "assessmentPlans": []
            },
            "discover": {
                "cardBrandPlans": [],
                "assessmentPlans": []
            },
            "unionPay": {
                "cardBrandPlans": [],
                "assessmentPlans": []
            },
            "amex": {
                "cardBrandPlans": [],
                "assessmentPlans": []
            },
            "otherFinancialInstitutionCards": [],
            "programs": []
        },
        "pointOfSaleSolutionType": "MONERIS_POINT_OF_SALE",
        "isAcceptedByConduct": false,
        "contractSignatureRequired": false,
        "faxRequired": true,
        "additionalInformation": "",
        "businessEntityName": "Intuit",
        "referralInformation": {
            "description": "Other",
            "additionalInformation": "NOT USED"
        },
        "hostType": "ESSENTIS",
        "autoApprovalStatus": "MANUAL_ADJUDICATION",
        "adjudicationApprovalStatus": "MANUAL",
        "hasImprinter": true,
        "isMarketSubSegmentationPreApprovalRequired": false,
        "optOutAmexCommunication": true,
        "multiCurrencyPricingPackageId": 1234
    },
    "limits": {
        "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"
}

Notes

NOTE: Expedited Orders

When isExpeditedOrder = true , coordinate with fulfillment SLAs accordingly.

Additional Notes

All monetary amounts are in cents.
Use idempotencyKey on create to prevent duplicate orders (where applicable).
Monitor orderStatus to drive shipment notices and POS enablement.
Common error responses include 400, 401, 403, 404, 409, 422, 429, 500, 503.

Additional Information

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