Order a terminal

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

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

  1. Include your API key in the x-api-key parameter in the header of a POST request.
  2. Send your request to https://identity.payroc.com/authorize.

Note: You need to generate a new Bearer token before the previous Bearer token expires.

Example request

1curl --location --request POST 'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

1{
2 "access_token": "eyJhbGc....adQssw5c",
3 "expires_in": 3600,
4 "scope": "service_a service_b",
5 "token_type": "Bearer"
6}

Headers

To create the header of each POST request, you must include the following parameters:

  • Content-Type: Include application/json as the value for this parameter.
  • Authorization: Include your Bearer token in this parameter.
  • Idempotency-Key: Include a UUID v4 to make the request idempotent.
1curl
2 -H "Content-Type: application/json"
3 -H "Authorization: <Bearer token>"
4 -H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, 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
One or more items to be ordered
trainingProviderenumOptionalDefaults to partner
Indicates who provides training to the merchant for the solution.
Allowed values:
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.

Example request

POST
/v1/processing-accounts/:processingAccountId/terminal-orders
1curl -X POST https://api.payroc.com/v1/processing-accounts/ \
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": "foo"
10 }
11 ]
12}'

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 of the terminal order.
statusenumRequired
Status of the terminal order.
Allowed values:
orderItemslist of objectsRequired
Array of orderItem objects. Provide a minimum of 1 order item and a maximum of 20 order items.
createdDatestringRequiredformat: "date-time"
Date that we received the terminal order.
lastModifiedDatestringRequiredformat: "date-time"
Date that the terminal order was last changed.
trainingProviderenumOptionalDefaults to partner
Indicates who provides training to the merchant for the solution.
Allowed values:
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.

Example response

Response
1{
2 "terminalOrderId": "12345",
3 "status": "open",
4 "orderItems": [
5 {
6 "solutionTemplateId": "Roc Services_DX8000",
7 "type": "solution",
8 "deviceCondition": "new",
9 "solutionQuantity": 1,
10 "solutionSetup": {
11 "timezone": "America/Chicago",
12 "industryTemplateId": "Retail",
13 "gatewaySettings": {
14 "merchantPortfolioId": "Company Ltd",
15 "merchantTemplateId": "Company Ltd Merchant Template",
16 "userTemplateId": "Company Ltd User Template",
17 "terminalTemplateId": "Company Ltd 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": "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}