Order a terminal | Payroc

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:

Include your API key in the x-api-key parameter in the header of a POST request.
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

1 curl --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.

1 curl
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.

Endpoint	Prefix	URL
Test	`api.uat.`	https://api.uat.payroc.com/v1/processing-accounts/{processingAccountId}/terminal-orders
Production	`api.`	https://api.payroc.com/v1/processing-accounts/{processingAccountId}/terminal-orders

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 10 order items.

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

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Boarding.ProcessingAccounts;
4 using System.Collections.Generic;
5 
6 namespace Usage;
7 
8 public class Example
9 {
10     public async Task Do() {
11         var client = new BasePayrocClient(
12             clientOptions: new ClientOptions {
13                 Environment = PayrocEnvironment.Production
14             }
15         );
16 
17         await client.Boarding.ProcessingAccounts.CreateTerminalOrderAsync(
18             new CreateTerminalOrder {
19                 ProcessingAccountId = "38765",
20                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
21                 OrderItems = new List<OrderItem>(){
22                     new OrderItem {
23                         Type = OrderItemType.Solution,
24                         SolutionTemplateId = "Roc Services_DX8000",
25                         SolutionQuantity = 1,
26                         DeviceCondition = OrderItemDeviceCondition.New,
27                         SolutionSetup = new OrderItemSolutionSetup {
28                             Timezone = SchemasTimezone.AmericaChicago,
29                             IndustryTemplateId = "Retail",
30                             GatewaySettings = new OrderItemSolutionSetupGatewaySettings {
31                                 MerchantPortfolioId = "Company Ltd",
32                                 MerchantTemplateId = "Company Ltd Merchant Template",
33                                 UserTemplateId = "Company Ltd User Template",
34                                 TerminalTemplateId = "Company Ltd Terminal Template"
35                             },
36                             ApplicationSettings = new OrderItemSolutionSetupApplicationSettings {
37                                 ClerkPrompt = false,
38                                 Security = new OrderItemSolutionSetupApplicationSettingsSecurity {
39                                     RefundPassword = true,
40                                     KeyedSalePassword = false,
41                                     ReversalPassword = true
42                                 }
43                             },
44                             DeviceSettings = new OrderItemSolutionSetupDeviceSettings {
45                                 NumberOfMobileUsers = 2,
46                                 CommunicationType = OrderItemSolutionSetupDeviceSettingsCommunicationType.Wifi
47                             },
48                             BatchClosure = new OrderItemSolutionSetupBatchClosure(
49                                 new AutomaticBatchClose {
50                                     BatchCloseTime = "23:40"
51                                 }
52                             ),
53                             ReceiptNotifications = new OrderItemSolutionSetupReceiptNotifications {
54                                 EmailReceipt = true,
55                                 SmsReceipt = false
56                             },
57                             Taxes = new List<OrderItemSolutionSetupTaxesItem>(){
58                                 new OrderItemSolutionSetupTaxesItem {
59                                     TaxRate = 6f,
60                                     TaxLabel = "Sales Tax"
61                                 },
62                             }
63                             ,
64                             Tips = new OrderItemSolutionSetupTips {
65                                 Enabled = false
66                             },
67                             Tokenization = true
68                         }
69                     },
70                 }
71                 ,
72                 TrainingProvider = TrainingProvider.Payroc,
73                 Shipping = new CreateTerminalOrderShipping {
74                     Preferences = new CreateTerminalOrderShippingPreferences {
75                         Method = CreateTerminalOrderShippingPreferencesMethod.NextDay,
76                         SaturdayDelivery = true
77                     },
78                     Address = new CreateTerminalOrderShippingAddress {
79                         RecipientName = "Recipient Name",
80                         AddressLine1 = "1 Example Ave.",
81                         City = "Chicago",
82                         State = "Illinois",
83                         PostalCode = "60056",
84                         Email = "[email protected]",
85                         BusinessName = "Company Ltd",
86                         AddressLine2 = "Example Address Line 2",
87                         Phone = "2025550164"
88                     }
89                 }
90             }
91         );
92     }
93 
94 }

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).

Allowed values:

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.

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 }