Board merchantsBoarding

Order a terminal

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