--- title: "Create terminal order" method: POST path: "/processing-accounts/{processingAccountId}/terminal-orders" tags: ["processingAccounts"] --- # Create terminal order `POST /processing-accounts/{processingAccountId}/terminal-orders` 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](https://docs.payroc.com/api/schema/boarding/merchant-platforms/retrieve) 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](https://docs.payroc.com/api/schema/boarding/terminal-orders/retrieve). **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](https://docs.payroc.com/guides/board-merchants/event-subscriptions). ## Path parameters - `processingAccountId` string, required ## Headers - `Authorization` string, required - `Idempotency-Key` string, uuid, required ## Request body - CreateTerminalOrder - `trainingProvider` 'partner' | 'payroc' — Indicates who provides training to the merchant for the solution. - `shipping` PropertiesShipping — 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. - `preferences` PropertiesShippingPreferences — Object that contains the shipping preferences for the terminal order. - `method` 'nextDay' | 'ground' — 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. - `saturdayDelivery` boolean — Indicates if we can schedule the terminal order to be delivered on a Saturday. - `address` PropertiesShippingAddress — Object that contains the shipping address for the terminal order. - `recipientName` string, required — Name of the person receiving the shipment. - `businessName` string — Name of the business receiving the shipment. - `addressLine1` string, required — First line of the shipment address. - `addressLine2` string — Second line of the shipment address. - `city` string, required — City of the shipment address. - `state` string, required — State of the shipment address. - `postalCode` string, required — Postal code of the shipment address. - `email` string, email, required — Contact email address for the shipment. - `phone` string — Contact number for the shipment. - `orderItems` OrderItem[], required — Array of order items. Provide a minimum of 1 order item and a maximum of 20 order items. - `type` 'solution', required — Type of item. - `solutionTemplateId` string, required — 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` - `solutionQuantity` integer — Quantity of the solution. - `deviceCondition` 'new' | 'refurbished' — Indicates if the order contains a new item or a refurbished item. - `solutionSetup` OrderItemSolutionSetup — Object that contains the settings for the solution, including gateway settings, device settings, and application settings. - `timezone` 'Pacific/Midway' | 'Pacific/Honolulu' | 'America/Anchorage' | 'America/Los_Angeles' | 'America/Denver' | 'America/Phoenix' | 'America/Chicago' | 'America/Indiana/Indianapolis' | 'America/New_York' — 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. - `industryTemplateId` string — Unique identifier of the industry template you want to apply to the solution. Send one of the following values: - `Retail` - `Restaurant` - `Moto` - `Ecommerce` - `gatewaySettings` OrderItemSolutionSetupGatewaySettings — Object that contains the gateway settings for the solution. - `merchantPortfolioId` string — Unique identifier of the merchant portfolio. - `merchantTemplateId` string — Unique identifier of the gateway merchant template. - `userTemplateId` string — Unique identifier of the gateway user template. - `terminalTemplateId` string — Unique identifier of the gateway terminal template. - `applicationSettings` OrderItemSolutionSetupApplicationSettings — Object that contains the application settings for the solution. - `clerkPrompt` boolean — 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. - `security` OrderItemSolutionSetupApplicationSettingsSecurity — Object that contains the password settings when running specific transaction types. - `refundPassword` boolean — Indicates if the terminal should prompt the clerk for a password when running a refund. - `keyedSalePassword` boolean — Indicates if the terminal should prompt the clerk for a password when running a keyed sale. - `reversalPassword` boolean — Indicates if the terminal should prompt the clerk for a password when cancelling a transaction. - `deviceSettings` OrderItemSolutionSetupDeviceSettings — Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer. - `numberOfMobileUsers` integer — Number of users that we need to set up for mobile solutions. - `communicationType` 'bluetooth' | 'cellular' | 'ethernet' | 'wifi' — Method of connection between a terminal or a peripheral device and the host. - `batchClosure` union — Object that contains information about when and how the terminal closes the batch. - object — Indicates how the merchant batches their transactions. - `batchCloseType` 'automatic', required — Discriminator value: automatic - `batchCloseTime` string — Time that the batch automatically closes. - object — Indicates how the merchant batches their transactions. - `batchCloseType` 'manual', required — Discriminator value: manual - `receiptNotifications` OrderItemSolutionSetupReceiptNotifications — Object that indicates if the terminal can send email receipts, text receipts, or both. - `emailReceipt` boolean — Indicates if the terminal can send receipts by email. - `smsReceipt` boolean — Indicates if the terminal can send receipts by text message. - `taxes` OrderItemSolutionSetupTaxesItems[] — Array of tax objects that contains the taxes that apply to the merchant's transactions. - `taxRate` number, double, required — Rate of tax that the terminal applies to each transaction. - `taxLabel` string, required — Short description of the tax rate, for example, "Sales Tax". - `tips` OrderItemSolutionSetupTips — Object that contains the tip options for transactions ran on the terminal. - `enabled` boolean — Indicates if the terminal can accept tips. - `tokenization` boolean — Indicates if the terminal can tokenize customer's payment details. For more information about tokenization, go to [Tokenization.](https://docs.payroc.com/knowledge/basic-concepts/tokenization) - `paymentIntent` CreatePaymentIntent — purchase variant - `paymentIntentType` 'purchase', required — Discriminator value: purchase - `payment` union, required — 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. - object — merchant variant - `payer` 'merchant', required — Discriminator value: merchant - `method` 'hostedPaymentPage' | 'accountOnFile', required — 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. - `frequency` Frequency — Object that indicates whether the merchant pays for the terminal in a single payment or in multiple installments. - `type` 'singlePayment' | 'installments', required — 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. - `numberOfInstallments` integer — 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. - object — partner variant - `payer` 'partner', required — Discriminator value: partner - `method` 'accountOnFile' | 'residualOffset', required — 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. - `costBreakdown` CreatePaymentIntentDiscriminatorMappingPurchaseCostBreakdown — Object that contains information about the items in the terminal order and the cost of the items. - `items` CreatePaymentIntentDiscriminatorMappingPurchaseCostBreakdownItemsItems[], required — Array of items objects. - `name` string, required — Name or brief description of the item. - `quantity` integer, required — Quantity of the item in the order. - `unitCost` integer, required — Cost of the item. The value is in the currency’s lowest denomination, for example, cents. - `customCharges` CreatePaymentIntentDiscriminatorMappingPurchaseCostBreakdownCustomChargesItems[] — Object that contains additional charges for the terminal order. - `name` string, required — Name of the charge. - `value` integer, required — Cost of the charge. The value is in the currency’s lowest denomination, for example, cents. - `shippingCost` integer — Cost of shipping the terminal order. The value is in the currency’s lowest denomination, for example, cents. - `subTotal` integer — 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`. - `tax` CreatePaymentIntentDiscriminatorMappingPurchaseTax — Object that contains the tax information for the terminal order. - `isTaxExempt` boolean — 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. - `taxAmount` integer — Amount of tax for the terminal order. The value is in the currency’s lowest denomination, for example, cents. ## Response `201` Successful request. We created the terminal order. - TerminalOrder - `terminalOrderId` string, required — Unique identifier that we assigned to the terminal order. - `status` 'open' | 'held' | 'dispatched' | 'fulfilled' | 'cancelled', required — 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](https://docs.payroc.com/guides/board-merchants/event-subscriptions). - `trainingProvider` 'partner' | 'payroc' — Indicates who provides training to the merchant for the solution. - `shipping` TerminalOrderShipping — 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. - `preferences` TerminalOrderShippingPreferences — Object that contains the shipping preferences for the terminal order. - `method` 'nextDay' | 'ground' — 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. - `saturdayDelivery` boolean — Indicates if we can schedule the terminal order to be delivered on a Saturday. - `address` TerminalOrderShippingAddress — Object that contains the shipping address for the terminal order. - `recipientName` string, required — Name of the person receiving the shipment. - `businessName` string — Name of the business receiving the shipment. - `addressLine1` string, required — First line of the shipment address. - `addressLine2` string — Second line of the shipment address. - `city` string, required — City of the shipment address. - `state` string, required — State of the shipment address. - `postalCode` string, required — Postal code of the shipment address. - `email` string, email, required — Contact email address for the shipment. - `phone` string — Contact number for the shipment. - `orderItems` TerminalOrderOrderItemsItems[], required — Array of orderItem objects. Provide a minimum of 1 order item and a maximum of 20 order items. - `type` 'solution', required — Type of item. - `solutionTemplateId` string, required — 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` - `solutionQuantity` integer — Quantity of the solution. - `deviceCondition` 'new' | 'refurbished' — Indicates if the order contains a new item or a refurbished item. - `solutionSetup` TerminalOrderOrderItemsItemsSolutionSetup — Object that contains the settings for the solution, including gateway settings, device settings, and application settings. - `timezone` 'Pacific/Midway' | 'Pacific/Honolulu' | 'America/Anchorage' | 'America/Los_Angeles' | 'America/Denver' | 'America/Phoenix' | 'America/Chicago' | 'America/Indiana/Indianapolis' | 'America/New_York' — 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. - `industryTemplateId` string — Unique identifier of the industry template you want to apply to the solution. Send one of the following values: - `Retail` - `Restaurant` - `Moto` - `Ecommerce` - `gatewaySettings` TerminalOrderOrderItemsItemsSolutionSetupGatewaySettings — Object that contains the gateway settings for the solution. - `merchantPortfolioId` string — Unique identifier of the merchant portfolio. - `merchantTemplateId` string — Unique identifier of the gateway merchant template. - `userTemplateId` string — Unique identifier of the gateway user template. - `terminalTemplateId` string — Unique identifier of the gateway terminal template. - `applicationSettings` TerminalOrderOrderItemsItemsSolutionSetupApplicationSettings — Object that contains the application settings for the solution. - `clerkPrompt` boolean — 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. - `security` TerminalOrderOrderItemsItemsSolutionSetupApplicationSettingsSecurity — Object that contains the password settings when running specific transaction types. - `refundPassword` boolean — Indicates if the terminal should prompt the clerk for a password when running a refund. - `keyedSalePassword` boolean — Indicates if the terminal should prompt the clerk for a password when running a keyed sale. - `reversalPassword` boolean — Indicates if the terminal should prompt the clerk for a password when cancelling a transaction. - `deviceSettings` TerminalOrderOrderItemsItemsSolutionSetupDeviceSettings — Object that contains the device settings if the solution includes a terminal or a peripheral device such as a printer. - `numberOfMobileUsers` integer — Number of users that we need to set up for mobile solutions. - `communicationType` 'bluetooth' | 'cellular' | 'ethernet' | 'wifi' — Method of connection between a terminal or a peripheral device and the host. - `batchClosure` union — Object that contains information about when and how the terminal closes the batch. - object — Indicates how the merchant batches their transactions. - `batchCloseType` 'automatic', required — Discriminator value: automatic - `batchCloseTime` string — Time that the batch automatically closes. - object — Indicates how the merchant batches their transactions. - `batchCloseType` 'manual', required — Discriminator value: manual - `receiptNotifications` TerminalOrderOrderItemsItemsSolutionSetupReceiptNotifications — Object that indicates if the terminal can send email receipts, text receipts, or both. - `emailReceipt` boolean — Indicates if the terminal can send receipts by email. - `smsReceipt` boolean — Indicates if the terminal can send receipts by text message. - `taxes` TerminalOrderOrderItemsItemsSolutionSetupTaxesItems[] — Array of tax objects that contains the taxes that apply to the merchant's transactions. - `taxRate` number, double, required — Rate of tax that the terminal applies to each transaction. - `taxLabel` string, required — Short description of the tax rate, for example, "Sales Tax". - `tips` TerminalOrderOrderItemsItemsSolutionSetupTips — Object that contains the tip options for transactions ran on the terminal. - `enabled` boolean — Indicates if the terminal can accept tips. - `tokenization` boolean — Indicates if the terminal can tokenize customer's payment details. For more information about tokenization, go to [Tokenization.](https://docs.payroc.com/knowledge/basic-concepts/tokenization) - `links` TerminalOrderOrderItemsItemsLinksItems[] — Array of objects that contain information about each processing terminal that the terminal order is linked to. - `processingTerminalId` string, required — Unique identifier that we assigned to the processing terminal. - `link` ProcessingTerminalSummaryLink, required — Array of links related to your request. For more information about HATEOAS, go to [Hypermedia as the engine of application state](https://docs.payroc.com/knowledge/basic-concepts/hypermedia-as-the-engine-of-application-state-hateoas). - `href` string, required — URL of the target resource. - `rel` string, required — Indicates the relationship between the current resource and the target resource. - `method` string, required — HTTP method that you need to use with the target resource. - `paymentIntent` PaymentIntentSummary — Object that contains information about who pays for the terminal order and how they are paying for it. - `paymentIntentId` string, required — Unique identifier that we assigned to the payment intent. - `paymentIntentType` 'purchase' | 'free' | 'loan', required — Type of payment intent. - `link` PaymentIntentSummaryLink, required — Array of useful links related to your request. - `href` string, required — The URL. - `rel` string, required — The link type. - `method` string, required — The REST method. - `createdDate` string, date-time, required — Date that we received the terminal order. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. - `lastModifiedDate` string, date-time, required — Date that the terminal order was last changed. We return this value in the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. ## Other responses - `400` — Bad request - `401` — Identity could not be verified - `403` — Do not have permissions to perform this action - `404` — Not found - `409` — Conflict - `500` — An error has occured --- [API](https://skmtc.dev/payroc/apis/schema.md) · [All operations](https://skmtc.dev/payroc/apis/schema/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payroc/schema/revisions/1d9d3e305945/schema)