Skip to content
developers

Create terminal order

Browse API reference

POST/processing-accounts/{processingAccountId}/terminal-orderscreateTerminalOrder

Use this method to order and configure terminals for a processing account.

Note: You need the ID of the processing account before you can create an order. If you don't know the processingAccountId, go to the Retrieve a Merchant Platform method.

In the request, specify the gateway settings, device settings, and application settings for the terminal.

In the response, our gateway returns information about the terminal order including its status and terminalOrderId that you can use to retrieve the terminal order.

Note: You can subscribe to the terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to Events Subscriptions.

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

processingAccountIdRequiredpathstring

Unique identifier that we assigned to the processing account.

Request body

application/json
  • orderItemsobject[]required
    Array of order items. Provide a minimum of 1 order item and a maximum of 20 order items.1–20 items
    • deviceConditionstring
      Indicates if the order contains a new item or a refurbished item.≤ 11 charsnewrefurbished
    • solutionQuantityinteger
      Quantity of the solution.≤ 50
    • solutionSetupobject
      Object that contains the settings for the solution, including gateway settings, device settings, and application settings.
      • applicationSettingsobject
        Object that contains the application settings for the solution.
        • clerkPromptboolean
          Indicates if the terminal should prompt the clerk, for example, if the terminal should prompt when the clerk needs to enter an amount on the terminal.
        • securityobject
          Object that contains the password settings when running specific transaction types.
          • keyedSalePasswordboolean
            Indicates if the terminal should prompt the clerk for a password when running a keyed sale.
          • refundPasswordboolean
            Indicates if the terminal should prompt the clerk for a password when running a refund.
          • reversalPasswordboolean
            Indicates if the terminal should prompt the clerk for a password when canceling a transaction.
      • batchClosureobject
        Object that contains information about when and how the terminal closes the batch.
        • automaticobject
          Indicates how the merchant batches their transactions.
          • batchCloseTimestring
            Time that the batch automatically closes.≤ 5 chars
          • batchCloseTypestringrequired
            Indicates how the merchant batches their transactions. Send one of the following: automatic Terminal automatically closes the batch each day. To set the time the batch closes, send a value for the batchCloseTime parameter. manual Merchant manually closes their batch.automatic
        • manualobject
          Indicates how the merchant batches their transactions.
          • batchCloseTypestringrequired
            Indicates how the merchant batches their transactions. Send one of the following: automatic Terminal automatically closes the batch each day. To set the time the batch closes, send a value for the batchCloseTime parameter. manual Merchant manually closes their batch.manual
      • deviceSettingsobject
        Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer.
        • communicationTypestring
          Method of connection between a terminal or a peripheral device and the host.≤ 9 charsbluetoothcellularethernetwifi
        • numberOfMobileUsersinteger
          Number of users that we need to set up for mobile solutions.
      • gatewaySettingsobject
        Object that contains the gateway settings for the solution.
        • merchantPortfolioIdstring
          Unique identifier of the merchant portfolio.≤ 100 chars
        • merchantTemplateIdstring
          Unique identifier of the gateway merchant template.≤ 100 chars
        • terminalTemplateIdstring
          Unique identifier of the gateway terminal template.≤ 100 chars
        • userTemplateIdstring
          Unique identifier of the gateway user template.≤ 100 chars
      • industryTemplateIdstring
        Unique identifier of the industry template you want to apply to the solution. Send one of the following values: Retail Restaurant Moto Ecommerce≤ 100 chars
      • receiptNotificationsobject
        Object that indicates if the terminal can send email receipts, text receipts, or both.
        • emailReceiptboolean
          Indicates if the terminal can send receipts by email.
        • smsReceiptboolean
          Indicates if the terminal can send receipts by text message.
      • taxesobject[]
        Array of tax objects that contains the taxes that apply to the merchant's transactions.0–3 items
        • taxLabelstringrequired
          Short description of the tax rate, for example, "Sales Tax".≤ 10 chars
        • taxRatenumberdoublerequired
          Rate of tax that the terminal applies to each transaction.0–99.999
      • timezonestring
        Time zone of the terminal. Note: If you don't send a value for this parameter, we use the time zone of the processing account.≤ 28 charsPacific/MidwayPacific/HonoluluAmerica/AnchorageAmerica/Los_AngelesAmerica/DenverAmerica/PhoenixAmerica/ChicagoAmerica/Indiana/Indianapolis+1 more
      • tipsobject
        Object that contains the tip options for transactions ran on the terminal.
        • enabledboolean
          Indicates if the terminal can accept tips.
      • tokenizationboolean
        Indicates if the terminal can tokenize customer's payment details. For more information about tokenization, go to Tokenization.
    • solutionTemplateIdstringrequired
      Unique identifier of the solution. Send one of the following values: Roc Services_DX8000 Roc Services_DX4000 Roc Services_Web Roc Services_Mobile Payroc DX8000 Payroc DX4000 Payroc RX7000_Cloud Payroc DX8000_Cloud Payroc DX4000_Cloud Payroc A920Pro Payroc A80 Payroc A920Pro_Cloud Payroc A80_Cloud Roc Terminal Plus_N950 Roc Terminal Plus_N950-S Roc Terminal Plus_X800 Gateway_Payroc VAR_Only_TSYS ROC Services Chipper3X BBPOS Chipper 3X Augusta EMV Ingenico - AXIUM Full Functional Base Pax A920 Charging Base Pax A920 Comms Base A920 Pro Ethernet Axium Bundle≤ 100 chars
    • typestringrequired
      Type of item.≤ 8 charssolution
  • paymentIntentobject
    Polymorphic object that contains information about who pays for the terminal order and how they are paying for it.
    • option 1object
      • costBreakdownobject
        Object that contains information about the items in the terminal order and the cost of the items.
        • customChargesobject[]
          Object that contains additional charges for the terminal order.1–10 items
          • namestringrequired
            Name of the charge.1–50 chars
          • valueintegerrequired
            Cost of the charge. The value is in the currency’s lowest denomination, for example, cents.0–999999
        • itemsobject[]required
          Array of items objects.1–50 items
          • namestringrequired
            Name or brief description of the item.1–50 chars
          • quantityintegerrequired
            Quantity of the item in the order.≥ 1
          • unitCostintegerrequired
            Cost of the item. The value is in the currency’s lowest denomination, for example, cents.0–999999
        • shippingCostinteger
          Cost of shipping the terminal order. The value is in the currency’s lowest denomination, for example, cents.0–999999
      • paymentobjectrequired
        Polymorphic object that contains information about how the payer is paying for the terminal order. The value of the payer field determines which variant you should use: merchant Merchant pays for the terminal. partner Partner pays for the terminal.
        • option 1object
          • frequencyobject
            Object that indicates whether the merchant pays for the terminal in a single payment or in multiple installments.
            • numberOfInstallmentsinteger
              Number of monthly payments for the terminal order. The merchant can pay for their order over a minimum of two months or a maximum of six months.2–6
            • typestringrequired
              Indicates whether the merchant wants to pay for the terminal order in one payment or in multiple installments. If the merchant wants to pay in installments, send a value for the numberOfInstallments parameter.≤ 13 charssinglePaymentinstallments
          • methodstringrequired
            Method of payment for the terminal order. The value is one of the following: hostedPaymentPage We send a link to the merchant to pay for the terminal order. accountOnFile We use the merchant's payment details that we have stored to pay for the terminal order.≤ 17 charshostedPaymentPageaccountOnFile
          • payerstringrequired
            Indicates who is paying for the terminal order. Send a value of merchant.≤ 12 charsmerchant
        • option 2object
          • methodstringrequired
            Method of payment for the terminal order. The value is one of the following: accountOnFile We use the sales partner's account details that we have stored to pay for the order. residualOffset We use the sales partner's residuals to pay for the order.≤ 17 charsaccountOnFileresidualOffset
          • payerstringrequired
            Indicates who is paying for the terminal order. Send a value of salesPartner.≤ 12 charssalesPartner
      • paymentIntentTypestringrequired
        Type of payment intent.≤ 8 charspurchase
      • subTotalinteger
        Total amount of the terminal order before tax. The value is in the currency’s lowest denomination, for example, cents. Note: You must send a value for this parameter if the payer is merchant.0–999999
      • taxobject
        Object that contains the tax information for the terminal order.
        • isTaxExemptboolean
          Indicates if the terminal order is tax exempt. The default value is false. Note: If you send a value of false, send a value for the taxAmount parameter.
        • taxAmountinteger
          Amount of tax for the terminal order. The value is in the currency’s lowest denomination, for example, cents.0–999999
  • shippingobject
    Object that contains the shipping details for the terminal order. If you don't provide a shipping address, we use the Doing Business As (DBA) address of the processing account.
    • addressobject
      Object that contains the shipping address for the terminal order.
      • addressLine1stringrequired
        First line of the shipment address.≤ 100 chars
      • addressLine2string
        Second line of the shipment address.≤ 100 chars
      • businessNamestring
        Name of the business receiving the shipment.≤ 100 chars
      • citystringrequired
        City of the shipment address.≤ 50 chars
      • emailstringemailrequired
        Contact email address for the shipment.≤ 100 chars
      • phonestring
        Contact number for the shipment.≤ 15 chars
      • postalCodestringrequired
        Postal code of the shipment address.≤ 9 chars
      • recipientNamestringrequired
        Name of the person receiving the shipment.≤ 100 chars
      • statestringrequired
        State of the shipment address.≤ 30 chars
    • preferencesobject
      Object that contains the shipping preferences for the terminal order.
      • methodstring
        Shipping method for the terminal order. Send one of the following values: nextDay We schedule the order to be delivered the next day. ground We ship the order with ground shipping.nextDayground
      • saturdayDeliveryboolean
        Indicates if we can schedule the terminal order to be delivered on a Saturday.
  • trainingProviderstring
    Indicates who provides training to the merchant for the solution.≤ 7 charspartnerpayroc

Responses

Successful request. We created the terminal order.

201 Created · application/json
{
  "createdDate": "2024-07-02T12:00:00.000+00:00",
  "lastModifiedDate": "2024-07-02T12:00:00.000+00:00",
  "orderItems": [
    {
      "deviceCondition": "new",
      "solutionQuantity": 1,
      "solutionSetup": {
        "applicationSettings": {
          "clerkPrompt": false,
          "security": {
            "keyedSalePassword": false,
            "refundPassword": true,
            "reversalPassword": true
          }
        },
        "batchClosure": {
          "batchCloseTime": "23:40",
          "batchCloseType": "automatic"
        },
        "deviceSettings": {
          "communicationType": "wifi",
          "numberOfMobileUsers": 2
        },
        "gatewaySettings": {
          "merchantPortfolioId": "Example Corp",
          "merchantTemplateId": "Example Corp Merchant Template",
          "terminalTemplateId": "Example Corp Terminal Template",
          "userTemplateId": "Example Corp User Template"
        },
        "industryTemplateId": "Retail",
        "receiptNotifications": {
          "emailReceipt": true,
          "smsReceipt": false
        },
        "taxes": [
          {
            "taxLabel": "Sales Tax",
            "taxRate": 6
          }
        ],
        "timezone": "America/Chicago",
        "tips": {
          "enabled": false
        },
        "tokenization": true
      },
      "solutionTemplateId": "Roc Services_DX8000",
      "type": "solution"
    }
  ],
  "shipping": {
    "address": {
      "addressLine1": "1 Example Ave.",
      "addressLine2": "Example Address Line 2",
      "businessName": "Example Corp",
      "city": "Chicago",
      "email": "jane.doe@example.com",
      "phone": "2025550164",
      "postalCode": "60056",
      "recipientName": "Jane Doe",
      "state": "Illinois"
    },
    "preferences": {
      "method": "nextDay",
      "saturdayDelivery": true
    }
  },
  "status": "open",
  "terminalOrderId": "2346",
  "trainingProvider": "payroc"
}
Response schema · 70 fields
  • createdDatestringdate-timerequired
    Date that we received the terminal order. We return this value in the ISO-8601 format.
  • lastModifiedDatestringdate-timerequired
    Date that the terminal order was last changed. We return this value in the ISO-8601 format.
  • orderItemsobject[]required
    Array of orderItem objects. Provide a minimum of 1 order item and a maximum of 20 order items.1–20 items
    • deviceConditionstring
      Indicates if the order contains a new item or a refurbished item.≤ 11 charsnewrefurbished
    • solutionQuantityinteger
      Quantity of the solution.≤ 50
    • solutionSetupobject
      Object that contains the settings for the solution, including gateway settings, device settings, and application settings.
      • applicationSettingsobject
        Object that contains the application settings for the solution.
        • clerkPromptboolean
          Indicates if the terminal should prompt the clerk, for example, if the terminal should prompt when the clerk needs to enter an amount on the terminal.
        • securityobject
          Object that contains the password settings when running specific transaction types.
          • keyedSalePasswordboolean
            Indicates if the terminal should prompt the clerk for a password when running a keyed sale.
          • refundPasswordboolean
            Indicates if the terminal should prompt the clerk for a password when running a refund.
          • reversalPasswordboolean
            Indicates if the terminal should prompt the clerk for a password when canceling a transaction.
      • batchClosureobject
        Object that contains information about when and how the terminal closes the batch.
        • automaticobject
          Indicates how the merchant batches their transactions.
          • batchCloseTimestring
            Time that the batch automatically closes.≤ 5 chars
          • batchCloseTypestringrequired
            Indicates how the merchant batches their transactions. Send one of the following: automatic Terminal automatically closes the batch each day. To set the time the batch closes, send a value for the batchCloseTime parameter. manual Merchant manually closes their batch.automatic
        • manualobject
          Indicates how the merchant batches their transactions.
          • batchCloseTypestringrequired
            Indicates how the merchant batches their transactions. Send one of the following: automatic Terminal automatically closes the batch each day. To set the time the batch closes, send a value for the batchCloseTime parameter. manual Merchant manually closes their batch.manual
      • deviceSettingsobject
        Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer.
        • communicationTypestring
          Method of connection between a terminal or a peripheral device and the host.≤ 9 charsbluetoothcellularethernetwifi
        • numberOfMobileUsersinteger
          Number of users that we need to set up for mobile solutions.
      • gatewaySettingsobject
        Object that contains the gateway settings for the solution.
        • merchantPortfolioIdstring
          Unique identifier of the merchant portfolio.≤ 100 chars
        • merchantTemplateIdstring
          Unique identifier of the gateway merchant template.≤ 100 chars
        • terminalTemplateIdstring
          Unique identifier of the gateway terminal template.≤ 100 chars
        • userTemplateIdstring
          Unique identifier of the gateway user template.≤ 100 chars
      • industryTemplateIdstring
        Unique identifier of the industry template you want to apply to the solution. Send one of the following values: Retail Restaurant Moto Ecommerce≤ 100 chars
      • receiptNotificationsobject
        Object that indicates if the terminal can send email receipts, text receipts, or both.
        • emailReceiptboolean
          Indicates if the terminal can send receipts by email.
        • smsReceiptboolean
          Indicates if the terminal can send receipts by text message.
      • taxesobject[]
        Array of tax objects that contains the taxes that apply to the merchant's transactions.0–3 items
        • taxLabelstringrequired
          Short description of the tax rate, for example, "Sales Tax".≤ 10 chars
        • taxRatenumberdoublerequired
          Rate of tax that the terminal applies to each transaction.0–99.999
      • timezonestring
        Time zone of the terminal. Note: If you don't send a value for this parameter, we use the time zone of the processing account.≤ 28 charsPacific/MidwayPacific/HonoluluAmerica/AnchorageAmerica/Los_AngelesAmerica/DenverAmerica/PhoenixAmerica/ChicagoAmerica/Indiana/Indianapolis+1 more
      • tipsobject
        Object that contains the tip options for transactions ran on the terminal.
        • enabledboolean
          Indicates if the terminal can accept tips.
      • tokenizationboolean
        Indicates if the terminal can tokenize customer's payment details. For more information about tokenization, go to Tokenization.
    • solutionTemplateIdstringrequired
      Unique identifier of the solution. Send one of the following values: Roc Services_DX8000 Roc Services_DX4000 Roc Services_Web Roc Services_Mobile Payroc DX8000 Payroc DX4000 Payroc RX7000_Cloud Payroc DX8000_Cloud Payroc DX4000_Cloud Payroc A920Pro Payroc A80 Payroc A920Pro_Cloud Payroc A80_Cloud Roc Terminal Plus_N950 Roc Terminal Plus_N950-S Roc Terminal Plus_X800 Gateway_Payroc VAR_Only_TSYS ROC Services Chipper3X BBPOS Chipper 3X Augusta EMV Ingenico - AXIUM Full Functional Base Pax A920 Charging Base Pax A920 Comms Base A920 Pro Ethernet Axium Bundle≤ 100 chars
    • typestringrequired
      Type of item.≤ 8 charssolution
    • linksobject[]
      Array of objects that contain information about each processing terminal that the terminal order is linked to.
      • option 1object
        Object that contains information about the processing terminal.
        • linkobjectrequired
          Array of links related to your request. For more information about HATEOAS, go to Hypermedia as the engine of application state.
          • hrefstringrequired
            URL of the target resource.
          • methodstringrequired
            HTTP method that you need to use with the target resource.
          • relstringrequired
            Indicates the relationship between the current resource and the target resource.
        • processingTerminalIdstringrequired
          Unique identifier that we assigned to the processing terminal.
  • paymentIntentobject
    Object that contains information about who pays for the terminal order and how they are paying for it.
    • linkobjectrequired
      Array of useful links related to your request.
      • hrefstringrequired
        The URL.
      • methodstringrequired
        The REST method.
      • relstringrequired
        The link type.
    • paymentIntentIdstringrequired
      Unique identifier that we assigned to the payment intent.
    • paymentIntentTypestringrequired
      Type of payment intent.purchasefreeloan
  • shippingobject
    Object that contains the shipping details for the terminal order. If you don't provide a shipping address, we use the Doing Business As (DBA) address of the processing account.
    • addressobject
      Object that contains the shipping address for the terminal order.
      • addressLine1stringrequired
        First line of the shipment address.≤ 100 chars
      • addressLine2string
        Second line of the shipment address.≤ 100 chars
      • businessNamestring
        Name of the business receiving the shipment.≤ 100 chars
      • citystringrequired
        City of the shipment address.≤ 50 chars
      • emailstringemailrequired
        Contact email address for the shipment.≤ 100 chars
      • phonestring
        Contact number for the shipment.≤ 15 chars
      • postalCodestringrequired
        Postal code of the shipment address.≤ 9 chars
      • recipientNamestringrequired
        Name of the person receiving the shipment.≤ 100 chars
      • statestringrequired
        State of the shipment address.≤ 30 chars
    • preferencesobject
      Object that contains the shipping preferences for the terminal order.
      • methodstring
        Shipping method for the terminal order. Send one of the following values: nextDay We schedule the order to be delivered the next day. ground We ship the order with ground shipping.nextDayground
      • saturdayDeliveryboolean
        Indicates if we can schedule the terminal order to be delivered on a Saturday.
  • statusstringrequired
    Status of the terminal order. Note: You can subscribe to our terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to Event Subscriptions.openhelddispatchedfulfilledcancelled
  • terminalOrderIdstringrequired
    Unique identifier that we assigned to the terminal order.
  • trainingProviderstring
    Indicates who provides training to the merchant for the solution.≤ 7 charspartnerpayroc

Used in workflows

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer