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

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	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.
`processingAccountId`Required	path	`string`	Unique identifier that we assigned to the processing account.

Request body

application/json

Field Edit request inputs →

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.+5 more fields at deeper levels — see the full spec
  - batchClosureobject
    Object that contains information about when and how the terminal closes the batch.+5 more fields at deeper levels — see the full spec
  - deviceSettingsobject
    Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer.+2 more fields at deeper levels — see the full spec
  - gatewaySettingsobject
    Object that contains the gateway settings for the solution.+4 more fields at deeper levels — see the full spec
  - 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.+2 more fields at deeper levels — see the full spec
  - taxesobject[]
    Array of tax objects that contains the taxes that apply to the merchant's transactions.0–3 items+2 more fields at deeper levels — see the full spec
  - 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.+1 more fields at deeper levels — see the full spec
  - 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.+8 more fields at deeper levels — see the full spec
  - 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.+9 more fields at deeper levels — see the full spec
  - 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.+2 more fields at deeper levels — see the full spec
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 · 44 of 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.+5 more fields at deeper levels — see the full spec
  - batchClosureobject
    Object that contains information about when and how the terminal closes the batch.+5 more fields at deeper levels — see the full spec
  - deviceSettingsobject
    Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer.+2 more fields at deeper levels — see the full spec
  - gatewaySettingsobject
    Object that contains the gateway settings for the solution.+4 more fields at deeper levels — see the full spec
  - 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.+2 more fields at deeper levels — see the full spec
  - taxesobject[]
    Array of tax objects that contains the taxes that apply to the merchant's transactions.0–3 items+2 more fields at deeper levels — see the full spec
  - 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.+1 more fields at deeper levels — see the full spec
  - 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.+5 more fields at deeper levels — see the full spec
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

Bad request

400 Bad Request · application/problem+json

{
  "detail": "An 'Idempotency-Key' must be supplied for this request",
  "status": 400,
  "title": "Idempotency-Key header missing",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-missing"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- 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.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

order-a-terminal