IntegrateBoarding

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/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}'

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.
createdDatedatetimeRequired
Date that we received the terminal order.
lastModifiedDatedatetimeRequired
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}