Order and set up equipment

Use the Equipment Ordering API to submit completed equipment surveys for selected hardware. This API helps streamline the process of configuring and ordering devices required for payment processing.

Merchants select the equipment they need, such as POS terminals or card readers and complete a survey specific to each device. Once submitted, the system provisions the hardware and links it to the corresponding Merchant ID (MID). This ensures seamless integration with the payment system.

1

Retrieve available equipment

The equipment setup process begins by retrieving the available hardware products that can be provisioned for a merchant.

Retrieving available equipment holds below methods that allow you either to retrieve a complete list of available products or a specific product.

Get all equipment products

Use the GET method with endpoint /api/equipment/products to retrieve a complete list of available products. This endpoint supports optional query parameters such as isSoftware to filter software-only products. Refer to the below sample code for reference:

{
  "frontends": [
    "string"
  ],
  "manufacturer": "string",
  "metadata": {
    "exchangeId": "string",
    "timestamp": "string"
  },
  "modelId": 0,
  "productName": "string",
  "productType": "Terminal"
}

Get a specific product

Use the GET method /api/equipment/products/{manufacturer}/{deviceType} to retrieve a specific product if the manufacturer and device type are already known. It is useful for targeting a specific piece of hardware when the selection is pre-defined. Refer to the below sample code for reference:

{
  "frontends": [
    "string"
  ],
  "manufacturer": "string",
  "metadata": {
    "exchangeId": "string",
    "timestamp": "string"
  },
  "modelId": 0,
  "productName": "string",
  "productType": "Terminal"
}

2

Equipment configuration survey

After selecting a product, the next step is to retrieve the Configuration Survey associated with that equipment. Each product includes a unique set of configuration options, captured through a dynamic survey. These options ensure that the device is properly set up for the merchant’s specific use case.

Use the GET method with endpoint /api/equipment/surveys/{productKey} to retrieve the complete configuration survey for the specified product. Refer to the below sample code for reference:

{
  "metadata": {
    "exchangeId": "text",
    "timestamp": "text"
  },
  "questionAnswerGroup": {
    "id": 1,
    "questionAnswerSets": {
      "ANY_ADDITIONAL_PROPERTY": [
        {
          "answers": [
            {
              "answer": "text",
              "id": 1,
              "selected": true
            }
          ],
          "children": [
            "[Circular Reference]"
          ],
          "conditionalOnAnswer": 1,
          "id": 1,
          "isHidden": true,
          "question": "text",
          "required": true,
          "selectedAnswer": 1,
          "sendToMerchantApp": true,
          "tags": [
            {
              "group": "text",
              "name": "text"
            }
          ],
          "type": "text"
        }
      ]
    },
    "questionAreas": [
      "text"
    ]
  }
}

3

Submit equipment order

Once the product is selected and the configuration survey is completed, the next step is to submit the equipment order. The Equipment Ordering used to submit the final order, that include the merchant's 16-digit Merchant ID (MID), selected product, and the completed configuration survey.

Use the POST method with endpoint /api/equipment/orders to create or submit an equipment order. Refer to the sample request code for reference:

{
  "errors": [
    {
      "field": "text",
      "message": "text"
    }
  ],
  "merchantNumber": "text",
  "metadata": {
    "exchangeId": "text",
    "timestamp": "text"
  },
  "orderCreateTime": {
    "calendarType": "text",
    "fieldsComputed": 1,
    "fieldsNormalized": 1,
    "firstDayOfWeek": 1,
    "lenient": true,
    "minimalDaysInFirstWeek": 1,
    "time": "2025-09-08T09:05:42.624Z",
    "timeInMillis": 1,
    "timeZone": {
      "displayName": "text",
      "dstsavings": 1,
      "id": "text",
      "rawOffset": 1
    },
    "weekCountData": {
      "country": "text",
      "displayCountry": "text",
      "displayLanguage": "text",
      "displayName": "text",
      "displayScript": "text",
      "displayVariant": "text",
      "extensionKeys": [
        {}
      ],
      "iso3Country": "text",
      "iso3Language": "text",
      "language": "text",
      "script": "text",
      "unicodeLocaleAttributes": [
        "text"
      ],
      "unicodeLocaleKeys": [
        "text"
      ],
      "variant": "text"
    },
    "weekDateSupported": true,
    "weekYear": 1,
    "weeksInWeekYear": 1,
    "zoneShared": true
  },
  "orderId": "text",
  "orderItems": [
    {
      "completionDate": "MM/dd/yyyy HH:mm a",
      "errors": [
        {
          "field": "text",
          "message": "text"
        }
      ],
      "manufacturer": "text",
      "orderItemId": 1,
      "orderItemMetadata": [
        {
          "apiKey": "text",
          "orderStatus": "text",
          "productManufacturer": "text",
          "productModel": "text",
          "publicKey": "text",
          "salesforceCaseNumber": "text",
          "serialNumber": "text",
          "storeNumber": 1,
          "tcn": "text",
          "terminalId": 1,
          "trackingNumber": "text",
          "vNumber": "text"
        }
      ],
      "productName": "text",
      "productType": "Software",
      "quantity": 1,
      "survey": {
        "metadata": {
          "exchangeId": "text",
          "timestamp": "text"
        },
        "questionAnswerGroup": {
          "questionAnswerSets": {
            "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
          },
          "questionAreas": [
            "text"
          ]
        }
      },
      "surveyValid": true,
      "trackingNumber": "text",
      "validFrontends": [
        "text"
      ]
    }
  ],
  "orderModifyTime": {
    "calendarType": "text",
    "fieldsComputed": 1,
    "fieldsNormalized": 1,
    "firstDayOfWeek": 1,
    "lenient": true,
    "minimalDaysInFirstWeek": 1,
    "time": "2025-09-08T09:05:42.624Z",
    "timeInMillis": 1,
    "timeZone": {
      "displayName": "text",
      "dstsavings": 1,
      "id": "text",
      "rawOffset": 1
    },
    "weekCountData": {
      "country": "text",
      "displayCountry": "text",
      "displayLanguage": "text",
      "displayName": "text",
      "displayScript": "text",
      "displayVariant": "text",
      "extensionKeys": [
        {}
      ],
      "iso3Country": "text",
      "iso3Language": "text",
      "language": "text",
      "script": "text",
      "unicodeLocaleAttributes": [
        "text"
      ],
      "unicodeLocaleKeys": [
        "text"
      ],
      "variant": "text"
    },
    "weekDateSupported": true,
    "weekYear": 1,
    "weeksInWeekYear": 1,
    "zoneShared": true
  },
  "resubmit": true,
  "status": "Active",
  "validFrontends": [
    "text"
  ]
}

This endpoint accepts a completed survey along with product details and order metadata.

For a detailed breakdown of the request and response fields and their descriptions, refer to the Equipment Boarding API.