The Management API lets you order terminals and accessories for delivery to a location of your choice using API requests instead of the Customer Area.
You can only create orders for live terminals using the Management API. To order test terminals, you need to submit a sales order in your Customer Area.
Products and orders
You can order products for a company account or a merchant account. A product can be:
- A box containing a payment terminal and default items like a power cable.
- An accessory, like a privacy shield, a stylus pen, or a replacement power cable.
Apart from the products, an order includes:
- A billing entity for the company or merchant account. This is where we charge the order to. We create billing entities for you based on the details you provided when you applied for the accounts.
- A shipping location for the company or merchant account. This is where we send the order. A shipping location is linked to a company account or a merchant account. You create shipping locations yourself.
API key and roles
To authenticate your requests to Management API, you need to have an API credential with an API key and the following roles:
- Management API—Terminal ordering read
- Management API—Terminal ordering read and write
If you are using a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.
Get the product ID
An order for terminal products must contain the IDs of the products you want to order. To retrieve those IDs and decide what to order:
-
Get the ID of the account you want to order products for. You need to specify that ID in the URL of later requests.
- For the company ID, make a GET /companies request.
- For the merchant ID, make a GET /merchants request.
-
Get a list of payment terminal models you can order for your company or merchant account. Use the following endpoints:
The response returns the
id
andname
of the various models. You can use theid
as a query parameter to filter the product list in the next step. -
Get a list of products you can order for your company or merchant account. Use the following endpoints, with the
country
as a query parameter:These are the query parameters to filter the paginated response:
Query parameter Required Result country Returns products for the country/region specified by a two-letter country code in ISO 3166-1 alpha-2 format. terminalModelId Returns products for the terminal model specified by its ID. This is the id returned in the /terminalModels
response. The product list will show the details of the box containing the terminal and all accessories you can order for that terminal model.offset Returns products shown on the specified page. limit The number of products to have on a page. The following example retrieves a list of all products related to the V400m payment terminal that can be ordered for a merchant account in France.
-
When you receive the response, save the
id
values of the products you want to order.The next example shows the response for the GET
merchants/{merchantId}/terminalProducts?country=FR&terminalModelId=Verifone.V400m
request (prices have been changed to 0.00 in the example).
Get the billing entity ID
An order for terminal products must contain the ID of a billing entity. This is the legal entity where we charge the order to. We create billing entities for you based on the details provided when you applied for your company and merchant accounts.
When ordering products in Brazil, you do not need to include the billingEntityId
in the request.
-
Get the billing entity ID for your company or merchant account. Use the following endpoints:
- GET /companies/{companyId}/billingEntities for the billing entities of the company and all merchant accounts belonging to the company.
- GET /merchants/{merchantId}/billingEntities for the billing entities of the merchant account.
You can filter the response using the name of the billing entity as the query parameter:
-
When you receive the response, save the id of the billing entity to use in your order. The response also returns the name, taxId (VAT number) and contact details for each billing entity.
Get the shipping location ID
An order for terminal products must contain the ID of a shipping location. This is the street address of the location where you want us to send the order to.
New shipping location
-
To create a shipping location for your company or merchant account, use the following endpoints:
Specify the following parameters in the request body:
Parameter Description name A unique reference that lets you recognize the location. contact Name and phone number of the individual who can be contacted about the shipment. address Where to send the order. -
When you receive the response, note the following details:
- id: the generated shipping location ID, for use in an order for terminal products.
- name: your reference for this location. You can use this to filter the list of shipping locations.
If your next step after creating a new shipping location is to create an order for the new location, wait a few seconds before sending the order creation request.
Existing shipping locations
-
To get a list of existing shipping locations for your company or merchant account, use the following endpoints:
You can filter the paginated response using the following query parameters:
Parameter Description name Filters the list by your reference to the shipping location. offset Returns locations starting from this offset. limit Sets a limit for the number of locations to 3return. -
When you receive the response, save the id of the shipping location to use in your order.
Create a terminal order
Use this request to order live terminals for your company or merchant account.
Requests to the Management API test endpoint do not create actual orders for test terminals. To order test terminals, you need to submit a sales order in your Customer Area.
-
Make sure that you have the following details:
- The IDs of the products you want to order.
- The ID of the billing entity.
- The ID of the shipping location.
If the order includes a new shipping location, wait a few seconds after creating the new location before sending the order creation request.
-
To create an order for your company or merchant account, use the following endpoints:
Specify the following parameters in the request body:
Parameter Required Description customerOrderReference Your purchase order number. This will be printed on the packing list. billingEntityId ID of the billing entity for the company or merchant account. When ordering products in Brazil, you do not need to include thebillingEntityId
in the request.shippingLocationId ID of the shipping location where we need to send the order. items An array listing the id
andquantity
of each product you want to order.taxId Tax number (VAT number) of the billing entity. Specify this parameter when the shipping location and the billing entity are in different countries/regions. The next example places an order for one V400m terminal and 20 receipt rolls.
The response echoes the parameters you provided and additionally includes the id and status of your order, the date and time you placed the order, and the full details of the billing entity and the shipping location.
When an order reaches the status Shipped, the response also includes a URL where you can track your order.
Terminal Order notifications
To stay informed about your order, you can subscribe to Terminal Order notifications. These notifications are triggered at certain steps in the logistical process and contain information such as shipment date, terminal serial numbers, and track & trace number. We send these platform notifications as an HTTP callback (webhook) to your server.
We also keep you up to date on the status of your order through email messages and in your Customer Area > Orders and returns.
Manage orders
You can view , update, and cancel orders using API requests. However, updating and canceling is only allowed while the order has the status Placed. This indicates we haven't started processing the order yet.
View orders
You can use the /terminalOrders
endpoint to check which orders can still be updated or cancelled, and to get the ID of those orders. To keep up to date on the progress of your order, we recommend using Terminal Order notifications.
List of orders
-
To get the details of all orders for your company or merchant account, use the following endpoints:
You can filter the paginated response using the following query parameters:
Parameter Description customerOrderReference Returns the details of the specified purchase order number. status Returns orders with the specified status. Possible values (not case-sensitive): Placed, Confirmed, Cancelled, Shipped, Delivered. offset Returns the orders shown on the specified page. limit The number of orders to have on a page. The response returns an array of orders sorted by order date in ascending order. For each order, all order details are included.
Individual order
-
To get the details of an individual order for your company or merchant account, use the following endpoints:
- GET /companies/{companyId}/terminalOrders/{orderId}
- GET /merchants/{merchantId}/terminalOrders/{orderId}
The response returns all order details.
Update an order
While an order has the status Placed, you can change the order items, the shipping location, and the billing entity. The request body only needs to contain what you want to change. However, to update the items
array, you need to replace the entire array. For example, let's assume the array has three items. To remove one item, the array must include the remaining two items. Or to add one item, the array must include all four items.
-
Get the ID of the order you want to update and check that the order has the
status
Placed. -
To update the order for your company or merchant account, use the following endpoints:
- PATCH /companies/{companyId}/terminalOrders/{orderId}
- PATCH /merchants/{merchantId}/terminalOrders/{orderId}
Specify the following optional parameters in the request body as needed:
Parameter Description billingEntityId ID of the billing entity for the company or merchant account. When ordering products in Brazil, you do not need to include thebillingEntityId
in the request.shippingLocationId ID of the shipping location where we need to send the order. items An array listing the id
andquantity
of each product you want to order. To remove an item, specify all remaining items. To add an item, specify all items already in the order plus the additional item.The next request removes the 20 receipt rolls from our example order 7219627091701347 by listing only the remaining order item, and changes the billing entity.
The response returns all order details.
Cancel an order
While an order has the status Placed, you can revoke the order.
-
Get the ID of the order you want to cancel and check that the order has the
status
Placed. -
To cancel an order for your company or merchant account, use the following endpoints:
- POST /companies/{companyId}/terminalOrders/{orderId}/cancel
- POST /merchants/{merchantId}/terminalOrders/{orderId}/cancel
Do not specify a request body.
The next request cancels our example order 7219627091701347.
-
The response returns all order details, but now the status is changed to Cancelled.