Board merchantsBoarding

Order a terminal

View as Markdown
Important: These documents are an early draft and are subject to change.
To order a terminal, you need the processingAccountId of the account you want to order the terminal for. To get the processingAccountId, go to Retrieve Merchant Platform.

To order one or more terminals for a processing account, provide the following information:

  • Training provider who will train the merchant to use the solution.
  • Shipping address for hardware devices and peripheral devices.
  • Solution details for each terminal including gateway settings, device settings, and application settings.
To receive a notification when we change the status of a terminal order, subscribe to our terminalOrder.status.changed event. For more information about how to subscribe to an event, go to Create a Subscription.

Integration steps

  • Create a terminal order.

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Create a terminal order

To order a terminal, send a POST request to our processing accounts endpoint.

Request parameters

To create the body of your request, use the following parameters:

Request

orderItemslist of objectsRequired
Array of order items. Provide a minimum of 1 order item and a maximum of 20 order items.
trainingProviderenumOptionalDefaults to partner
Indicates who provides training to the merchant for the solution.
shippingobjectOptional
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.
paymentIntentobjectOptional
Polymorphic object that contains information about who pays for the terminal order and how they are paying for it.

Example request

POST
/v1/processing-accounts/:processingAccountId/terminal-orders
1curl -X POST https://api.payroc.com/v1/processing-accounts/38765/terminal-orders \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "orderItems": [
7    {
8      "type": "solution",
9      "solutionTemplateId": "Roc Services_DX8000",
10      "solutionQuantity": 1,
11      "deviceCondition": "new",
12      "solutionSetup": {
13        "timezone": "America/Chicago",
14        "industryTemplateId": "Retail",
15        "gatewaySettings": {
16          "merchantPortfolioId": "Company Ltd",
17          "merchantTemplateId": "Company Ltd Merchant Template",
18          "userTemplateId": "Company Ltd User Template",
19          "terminalTemplateId": "Company Ltd Terminal Template"
20        },
21        "applicationSettings": {
22          "clerkPrompt": false,
23          "security": {
24            "refundPassword": true,
25            "keyedSalePassword": false,
26            "reversalPassword": true
27          }
28        },
29        "deviceSettings": {
30          "numberOfMobileUsers": 2,
31          "communicationType": "wifi"
32        },
33        "batchClosure": {
34          "batchCloseType": "automatic",
35          "batchCloseTime": "23:40"
36        },
37        "receiptNotifications": {
38          "emailReceipt": true,
39          "smsReceipt": false
40        },
41        "taxes": [
42          {
43            "taxRate": 6,
44            "taxLabel": "Sales Tax"
45          }
46        ],
47        "tips": {
48          "enabled": false
49        },
50        "tokenization": true
51      }
52    }
53  ],
54  "trainingProvider": "payroc",
55  "shipping": {
56    "preferences": {
57      "method": "nextDay",
58      "saturdayDelivery": true
59    },
60    "address": {
61      "recipientName": "Recipient Name",
62      "addressLine1": "1 Example Ave.",
63      "city": "Chicago",
64      "state": "Illinois",
65      "postalCode": "60056",
66      "email": "[email protected]",
67      "businessName": "Company Ltd",
68      "addressLine2": "Example Address Line 2",
69      "phone": "2025550164"
70    }
71  },
72  "paymentIntent": {
73    "paymentIntentType": "purchase",
74    "payment": {
75      "payer": "merchant",
76      "method": "hostedPaymentPage",
77      "frequency": {
78        "type": "singlePayment"
79      }
80    },
81    "costBreakdown": {
82      "items": [
83        {
84          "name": "dx8000",
85          "quantity": 1,
86          "unitCost": 4999
87        }
88      ],
89      "shippingCost": 599
90    },
91    "subTotal": 5598
92  }
93}'
Try it

Response fields

If the request is successful, we create the terminal order and return the following response:

Status code 201

Successful request. We created the terminal order.

Response

terminalOrderIdstringRequired
Unique identifier that we assigned to the terminal order.
statusenumRequired
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).
orderItemslist of objectsRequired
Array of orderItem objects. Provide a minimum of 1 order item and a maximum of 20 order items.
createdDatedatetimeRequiredRead-only
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.
lastModifiedDatedatetimeRequiredRead-only
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.
trainingProviderenumOptionalDefaults to partner
Indicates who provides training to the merchant for the solution.
shippingobjectOptional
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.
paymentIntentobjectOptional
Object that contains information about who pays for the terminal order and how they are paying for it.

Example response

Response
1{
2  "terminalOrderId": "2346",
3  "status": "open",
4  "orderItems": [
5    {
6      "type": "solution",
7      "solutionTemplateId": "Roc Services_DX8000",
8      "solutionQuantity": 1,
9      "deviceCondition": "new",
10      "solutionSetup": {
11        "timezone": "America/Chicago",
12        "industryTemplateId": "Retail",
13        "gatewaySettings": {
14          "merchantPortfolioId": "Example Corp",
15          "merchantTemplateId": "Example Corp Merchant Template",
16          "userTemplateId": "Example Corp User Template",
17          "terminalTemplateId": "Example Corp Terminal Template"
18        },
19        "applicationSettings": {
20          "clerkPrompt": false,
21          "security": {
22            "refundPassword": true,
23            "keyedSalePassword": false,
24            "reversalPassword": true
25          }
26        },
27        "deviceSettings": {
28          "numberOfMobileUsers": 2,
29          "communicationType": "wifi"
30        },
31        "batchClosure": {
32          "batchCloseType": "automatic",
33          "batchCloseTime": "23:40"
34        },
35        "receiptNotifications": {
36          "emailReceipt": true,
37          "smsReceipt": false
38        },
39        "taxes": [
40          {
41            "taxRate": 6,
42            "taxLabel": "Sales Tax"
43          }
44        ],
45        "tips": {
46          "enabled": false
47        },
48        "tokenization": true
49      }
50    }
51  ],
52  "createdDate": "2024-07-02T12:00:00.000Z",
53  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
54  "trainingProvider": "payroc",
55  "shipping": {
56    "preferences": {
57      "method": "nextDay",
58      "saturdayDelivery": true
59    },
60    "address": {
61      "recipientName": "Jane Doe",
62      "addressLine1": "1 Example Ave.",
63      "city": "Chicago",
64      "state": "Illinois",
65      "postalCode": "60056",
66      "email": "[email protected]",
67      "businessName": "Example Corp",
68      "addressLine2": "Example Address Line 2",
69      "phone": "2025550164"
70    }
71  }
72}