Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Use API calls to order terminals

Order payment terminals and accessories using our Management API.

The Management API lets you order terminals and accessories for delivery to a location of your choice using API calls instead of the Customer Area.

This feature is in the development phase. The API, documentation, and processes will change as the feature evolves. If you have any feedback on the feature, reach out to your Adyen contact.

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, a sales 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.

Required roles

To use the Management API, your API credential must have the following roles:

  • Management API
  • Create/Manage terminal orders via API

Get the product ID

A sales order must contain the IDs of the products you want to order. To retrieve those IDs and decide what to order:

  1. Retrieve the ID of the account you want to order products for.

    Level Method Endpoint
    Company account GET https://management-test.adyen.com/v1/companies
    Merchant account GET https://management-test.adyen.com/v1/merchants

    For example, make a GET /merchants request:

    Get merchant ID
    curl https://management-test.adyen.com/v1/merchants \
    -H "x-API-key: YOUR_X-API-KEY" \
  2. When you receive the response, save the id for use in the URL of later requests:

    Level Endpoint
    Company account https://management-test.adyen.com/v1/companies/{companyId}
    Merchant account https://management-test.adyen.com/v1/merchants/{merchantId}

    In our example, the response returns an array with the merchant accounts that your API credential has access to.

    /merchants response
    {
      "data": [
        {
          "id": "MerchantPOSFrance",
          "name": "POS merchant account for France",
          "captureDelay": "120",
          "defaultShopperInteraction": "POS",
          "status": "Active",
          ...
        },
        {
          "id": "MerchantPOSGermany",
          "name": "POS merchant account for Germany",
          "captureDelay": "120",
          "defaultShopperInteraction": "POS",
          "status": "Active",
          ...
        }
      ]
      ...
    }
  3. To retrieve a list of payment terminal models you can order, make a GET request to the /terminalModels endpoint for your company or merchant account.

    Get model list for a merchant account

    The response returns the id and name of the various models. You can use the id as a query parameter to filter the product list in the next step.

    Model list
    {
      "data": [
        {
          "id": "Verifone.V400m",
          "name": "Verifone V400m"
        },
        ...
        {
          "id": "Castles.S1F2",
          "name": "Castles S1F2"
        }
      ]
    }
  4. To retrieve a list of products you can order, make a GET request to the /terminalProducts endpoint for your company or merchant account.

    You can filter the list using query parameters:

    • country: Filters the product list by country. Specify a two-letter country code in ISO 3166-1 alpha-2 format.
    • terminalModelId: Filters the product list by terminal model ID. This is the id returned in the /terminalModels response. The product list will show the IDs and other details of the box containing the terminal and all accessories you can order for that terminal model.
    • offset: Returns products starting from this offset.
    • limit: Sets a limit for the number of products to return.

    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.

    Get product list by terminal model for a French merchant account
  5. 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=V400m request (prices have been changed to 0.00 in the example).

Get the billing entity ID

A sales 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.

  1. To retrieve the billing entity ID, make a GET request to the /billingEntities endpoint for your company or merchant account.

    At the company level, a GET /billingEntities request returns the billing entities for the company and all merchant accounts belonging to the company.

    You can filter the list using a query parameter:

    • name: The name of the billing entity.
    Get billing entities for a company
    curl https://management-test.adyen.com/v1/companies/{companyId}/billingEntities \
    -H "x-API-key: YOUR_X-API-KEY" \
  2. 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.

    Billing entity list
    {
      "data": [
        {
          "id": "Company.ExampleCompany",
          "name": "ExampleCompany",
          "taxId": "111111111",
          "email": "financial@company.com",
          "address": {
            "companyName": "Example Company",
            "streetAddress": "Boulevard Principal 3",
            "streetAddress2": "Tour Azure",
            "postalCode": "23456",
            "city": "Paris",
            "country": "France"
          }
        },
        ...
        {
          "id": "MerchantAccount.ExampleCompanyFrance",
          "name": "ExampleCompanyFrance",
          "taxId": "222222222",
          "email": "jdupont@test.com",
          "address": {
            "companyName": "Example Company France",
            "streetAddress": "11 Rue de Ville",
            "postalCode": "12345",
            "city": "Paris",
            "country": "France"
          }
        }
      ]
    }

Get the shipping location ID

A sales 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

  1. To create a new shipping location, make a POST request to the /shippingLocations endpoint for your company or merchant account, specifying:

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

    See the API reference for details.

    Create shipping location
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/shippingLocations \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X POST \
    -d '{
      "name": "POS France depot",
      "contact": {
        "firstName": "Jesse",
        "lastName": "Dupont",
        "phoneNumber": "+33 1 76 35 07 90",
        "email": "jdupont@test.com"
      }
      "address": {
        "companyName": "Example Company France",
        "streetAddress": "11 Rue de Ville",
        "postalCode": "12345",
        "city": "Paris",
        "country": "France"
      }
    }
  2. When you receive the response, you may want to save the following details:

    • id: The generated shipping location ID, for use in a sales order.
    • name: Your reference for this location. You can use this to filter the list of shipping locations.
    Shipping location created
    {
      "id": "S2-7145604F44356F424F4369432B3F486B6A6D",
      "name": "POS France depot",
      "contact": {
        "firstName": "Jesse",
        "lastName": "Dupont",
        "phoneNumber": "+33 1 76 35 07 90",
        "email": "jdupont@test.com"
      },
      "address": {
        "companyName": "Example Company France",
        "streetAddress": "11 Rue de Ville",
        "postalCode": "12345",
        "city": "Paris",
        "country": "France"
      }
    }

Existing shipping locations

  1. To retrieve a list of existing shipping locations, make a GET request to the /shippingLocations endpoint for your company or merchant account.

    You can filter the list using query parameters:

    • 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 return.
    Get shipping locations for a merchant account
  2. When you receive the response, save the id of the shipping location to use in your order.

    Shipping locations list
    {
      "data": [
        {
          "id": "S2-7145604F44356F424F4369432B3F486B6A6D",
          "name": "POS France depot",
          "contact": {
            "firstName": "Jesse",
            "lastName": "Dupont",
            "phoneNumber": "+33 1 76 35 07 90",
            "email": "jdupont@test.com"
          },
          "address": {
            "companyName": "Example Company France",
            "streetAddress": "11 Rue de Ville",
            "postalCode": "12345",
            "city": "Paris",
            "country": "France"
          }
        },
        {
          ...
        }
      ]
    }

Create a sales order

  1. Make sure you have the following details:

  2. To create an order, make a POST request to the /terminalOrders endpoint for your company or merchant account, specifying:

    Parameter Required Description
    customerOrderReference Your purchase order number. This will be printed on the packing list.
    billingEntityId -white_check_mark- ID of the billing entity for the company or merchant account.
    shippingLocationId -white_check_mark- ID of the shipping location where we need to send the order.
    items -white_check_mark- An array listing the id and quantity 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.

    The next example places a sales order for one V400m terminal and 20 receipt rolls.

    Place a sales order
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/terminalOrders \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X POST \
    -d '{
          "items": [
            {
              "id": "TBOX-V400m-774-EU",
              "quantity": 1
            },
            {
              "id": "PART-482077-EU",
              "quantity": 20
            }
          ],
          "customerOrderReference": "YOUR_REFERENCE_1",
          "shippingLocationId": "S2-7145604F44356F424F4369432B3F486B6A6D",
          "billingEntityId": "Company.ExampleCompany"
    }

    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.

    Order placed
    {
      "id": "5265677890100681",
      "customerOrderReference": "YOUR_REFERENCE_1",
      "status": "Placed",
      "shippingLocation": {
        "id": "S2-7145604F44356F424F4369432B3F486B6A6D",
        "name": "POS France depot",
        "contact": {
          "firstName": "Jesse",
          "lastName": "Dupont",
          "phoneNumber": "+33 1 76 35 07 90",
          "email": "jdupont@test.com"
        },
        "address": {
          "companyName": "Example Company France",
          "streetAddress": "11 Rue de Ville",
          "postalCode": "12345",
          "city": "Paris",
          "country": "France"
        }
      },
      "billingEntity": {
        "id": "Company.ExampleCompany",
        "name": "ExampleCompany",
        "taxId": "111111111",
        "email": "financial@company.com",
        "address": {
          "companyName": "Example Company",
          "streetAddress": "Boulevard Principal 3",
          "streetAddress2": "Tour Azure",
          "postalCode": "23456",
          "city": "Paris",
          "country": "France",
        }
      },
      "orderDate": "2020-01-22T14:12:33Z",
      "items": [
        {
          "id": "TBOX-V400m-684-EU",
          "name": "V400m Package",
          "quantity": 1
        },
        {
          "id": "PART-620222-EU",
          "name": "Receipt Roll",
          "quantity": 20
        }
      ]
    }

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 calls. However, updating and cancelling 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 retrieve a list of orders, make a GET request to the /terminalOrders endpoint for your company or merchant account.

    You can filter the list using query parameters:

    • customerOrderReference: Filters the list by your purchase order number.
    • offset: Returns orders starting from this offset.
    • limit: Sets a limit for the number of orders to return.
    • status: Filters the list by order status. Possible values (not case-sensitive): Placed, Confirmed, Cancelled, Shipped, Delivered.
    Get a list of placed orders for a merchant account

    The response returns an array of orders sorted by orderDate in ascending order. For each order, all order details are included.

Individual order

  • To retrieve an individual order, make a GET request to the /terminalOrders/{orderId} endpoint for your company or merchant account.

    Get the details of a specific order
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/terminalOrders/{orderId} \
    -H "x-API-key: YOUR_X-API-KEY" \

    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.

  1. Get the ID of the order you want to update and check that the order has the status Placed.

  2. Make a PATCH request to the /terminalOrders/{orderId} endpoint for your company or merchant account, specifying the following optional parameters as needed:

    Parameter Description
    billingEntityId ID of the billing entity for the company or merchant account.
    shippingLocationId ID of the shipping location where we need to send the order.
    items An array listing the id and quantity 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 by listing only the remaining order item, and changes the billing entity.

    Update order items and billing entity
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/terminalOrders/{orderId} \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X PATCH \
    -d '{
          "items": [
            {
              "id": "V400m_1",
              "quantity": 1
            }
          ],
          "billingEntityId": "MerchantAccount.ExampleCompanyFrance"
    }

    The response returns all order details.

    Order updated
    {
      "id": "5265677890100681",
      "status": "Placed",
      "customerOrderReference": "YOUR_REFERENCE_1",
      "shippingLocation": {
        "id": "S2-7145604F44356F424F4369432B3F486B6A6D",
        "name": "POS France depot",
        "address": {
          "companyName": "Example Company France",
          "streetAddress": "11 Rue de Ville",
          "postalCode": "12345",
          "city": "Paris",
          "country": "France"
        },
        "contact": {
          "firstName": "Jesse",
          "lastName": "Dupont",
          "phoneNumber": "+33 1 76 35 07 90",
          "email": "jdupont@test.com"
        }
      },
      "billingEntity": {
        "id": "MerchantAccount.ExampleCompanyFrance",
        "name": "ExampleCompanyFrance",
        "taxId": "222222222",
        "email": "jdupont@test.com",
        "address": {
          "companyName": "Example Company France",
          "streetAddress": "11 Rue de Ville",
          "postalCode": "12345",
          "city": "Paris",
          "country": "France"
        }
      },
      "orderDate": "2020-01-22T14:12:33Z",
      "items": [
        {
          "id": "V400m_1",
          "name": "V400m terminal package EU/GB",
          "quantity": 1
        }
      ]
    }

Cancel an order

While an order has the status Placed, you can revoke the order.

  1. Get the ID of the order you want to cancel and:

    1. Check that the order has the status Placed.
    2. If the order is Placed, copy the full order details.

  2. Make a POST request to the /terminalOrders/{orderId}/cancel endpoint for your company or merchant account, specifying:

    • The full order details, but with the status changed to Cancelled.

    The next request cancels our example order.

    Cancel a placed sales order
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/terminalOrders/{orderId}/cancel \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X POST \
    -d '{
      "id": "5265677890100681",
      "status": "Cancelled",
      "customerOrderReference": "YOUR_REFERENCE_1",
      "shippingLocation": {
        "id": "S2-7145604F44356F424F4369432B3F486B6A6D",
        "name": "POS France depot",
        "contact": {
          "firstName": "Jesse",
          "lastName": "Dupont",
          "phoneNumber": "+33 1 76 35 07 90",
          "email": "jdupont@test.com"
        },
        "address": {
          "companyName": "Example Company France",
          "streetAddress": "11 Rue de Ville",
          "postalCode": "12345",
          "city": "Paris",
          "country": "France"
        }
      },
      "billingEntity": {
        "id": "MerchantAccount.ExampleCompanyFrance",
        "name": "ExampleCompanyFrance",
        "taxId": "222222222",
        "email": "jdupont@test.com",
        "address": {
          "companyName": "Example Company France",
          "streetAddress": "11 Rue de Ville",
          "postalCode": "12345",
          "city": "Paris",
          "country": "France"
        }
      },
      "orderDate": "2020-01-22T14:12:33Z",
      "items": [
        {
          "id": "V400m_1",
          "name": "V400m terminal package EU/GB",
          "quantity": 1
        }
      ]
    }

    The response returns all order details.

API reference

Terminal model

The GET /terminalModels call returns a data array of terminal models with the following parameters:

Parameter Data type Description
id String ID of the terminal model.
name String Name of the terminal model.

Terminal product

The GET /terminalProducts call returns a data array of products with the following parameters:

Parameter Data type Description
id String ID of the product.
name String Name of the product.
description String Description of the terminal package. Not present for parts.
price Object Price of the product, expressed in currency (String, three-character ISO currency code) and value (BigDecimal).
itemsIncluded Array (String) List of parts included in the terminal package. Not present for parts.

Billing entity

A billing entity consists of the following parameters:

Parameter Data type Required Description
id String -white_check_mark- Unique identifier of the billing entity, for use as billingEntityId when creating an order.
name String -white_check_mark- Unique name of the billing entity.
taxId String -white_check_mark- Tax number (VAT number) of the billing entity.
email String Email address of the billing entity.
address Object -white_check_mark- Address details.

An address object consists of:

Parameter Data type Required Description
companyName String -white_check_mark- Name of the company as part of the address.
streetAddress String -white_check_mark- Name of the street.
streetAddress2 String Additional address details like the house or building number.
postalCode String -white_check_mark- Postal code (zip code).
city String -white_check_mark- Name of the city.
stateOrProvince String State or province as defined in ISO 3166-2. For example, CA in the USA. Applicable for some countries.
country String -white_check_mark- Two-letter country code, in ISO 3166-1 alpha-2 format.

Shipping location

A shipping location consists of the following parameters:

Parameter Data type Required Description
id String -white_check_mark- Unique identifier of the shipping location. for use as shippingLocationId when creating an order.
name String -white_check_mark- Your unique name for the shipping location.
contact Object -white_check_mark- Contact details of an individual.
address Object -white_check_mark- Address details. This object has the same parameters as the billing entity address.

The contact object consists of:

Parameter Data type Required Description
firstName String -white_check_mark- The individual's first name.
infix String The infix in the individual's name.
lastName String -white_check_mark- The individual's last name.
phoneNumber String -white_check_mark- The individual's telephone number.
email String The individual's email address.

Terminal order

A terminal order consists of the following parameters:

Parameter Data type Required Description
id String -white_check_mark- Unique identifier of the order, generated by us.
customerOrderReference String Purchase order number defined by you. This will be printed on the packing list.
status String -white_check_mark- Status of the order. Possible values: Placed, Confirmed, Cancelled, Shipped, Delivered.
shippingLocation Object -white_check_mark- All shipping location details
orderDate String -white_check_mark- Order date and time, in UTC ISO 8601 format. For example, "2011-12-03T10:15:30Z".
trackingUrl String URL provided by the carrier company where you can track the shipment.
billingEntity Object -white_check_mark- All billing entity details
items Array -white_check_mark- List of items included in the order.

Each product in the items array consists of:

Parameter Data type Required Description
id String -white_check_mark- The ID of the product.
name String -white_check_mark- The name of the product.
quantity Integer -white_check_mark- The number of items with the specified ID included in the order.

See also