Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Build your Terminal API integration

Checklist for building a point-of-sale integration with the Adyen Terminal API.

Support

Direct 24/7 contact: www.adyen.com/contact

Articles, FAQs, and requesting support: www.adyen.help

An integration with Adyen's Terminal API lets you to start payments from your cash register system and process these payments through Adyen using our payment terminals.

Here we describe how you can build such an integration in a test environment before going live.

Before you begin

Step 1: Set up your Adyen test account

After signing up for an Adyen test account, you have access to your test Customer Area. In this test environment, you need to set up a structure for your Adyen account. What structure is best for you comes down to your business needs.

  1. Determine the structure of your Adyen account, based on our documentation about the company account, merchant accounts, and stores.

  2. Request the merchant accounts that you need. Provide as many details as possible and ensure you submit the correct documents and links. This will make the application process smoother and faster.

  3. If you require stores in your account structure, wait for confirmation that your merchant accounts are created and then submit your store request form.

You can add more merchant accounts and stores later, but the basic structure should reflect the structure that you plan to have when you go live.

Step 2: Scope your Terminal API integration

The next step is to determine the scope of your integration.

This may also be a good time to learn about our Terminal API and the payments lifecyle.

  1. Choose your integration architecture:

    • With local communications your cash register communicates directly with the payment terminal over your local network.
    • With cloud communications your cash register communicates with the payment terminal through the Adyen payments platform.

  2. Have a look at the overview of payment features and follow the links to understand the features that you want to support. For example, additional payment methods, delayed capture, offline processing, tipping, and much more.

  3. Determine your PCI security needs. By default, we protect payment messages with our End-to-End Encryption (E2EE) solution, but we also offer Point-to-Point Encryption (P2PE). Both are equally secure. If you require P2PE, you have to inform us because we then need to provide different software on your payment terminals.

Step 3: Order test payment terminals

Now let's focus on the devices for processing payments. These devices are sometimes referred to as pin entry devices (PED) or points of interaction (POI), but we call them terminals.

  1. Choose the terminals that you want to use. Adyen has a wide range of terminal models for different business needs.

  2. When you know what terminals you want, it's time to order a test card and one or more terminals for testing.

It will take at least four business days before your terminals arrive.

Step 4: Prepare your terminals

Before you can use your terminals, you need to configure them in your Customer Area. You can do this at different levels: company account level, merchant account level, store level, and terminal level. Settings at the company level apply to all terminals under the company. Settings at the merchant account level override settings inherited from the company level, and so on.

  1. In your test Customer Area, enable Terminal API for your terminals.

  2. Add payment methods and configure the terminal and payment features that are in the scope you decided on. Our POS Support Team will help you with any features that you can't fully configure yourself.

  3. Assign the test terminals to a store. This makes it easier to start using terminals when you receive them. You can assign terminals from your Customer Area or using our Terminal Management API.

Step 5: Set up your integration

Now you can build out your integration.

  1. Optional. Add team members and API credentials to your account.

    • You can create additional Customer Area users for your team members.
    • With your test account you have a default API credential that we use for flows that require authentication, such as processing payments and ordering payment terminals.
      When you go live, you'll need to create API credentials yourself. For example, a separate API credential for each merchant account, or one for point of sale and one for ecommerce. It's good practice (though not required) to do the same on your test account.
  2. Depending on the integration architecture that you chose, set up either a local integration or a cloud integration. You also need to make sure you use the correct IP addresses or endpoints and proper authentication. For example, for a cloud integration you need to get an API key.
    While doing this, make sure you implement our network recommendations.

  3. When you receive the terminals, follow the steps in the manual for the terminal model to get the terminals up and running. The steps are to:

    • Inspect the terminal, to verify it has not been tampered with.
    • Insert the receipt paper roll.
    • Turn on the terminal.
    • Connect the terminal to your network.
    • Board the terminal.
    • Test the connection with the Adyen payments platform.

Step 6: Test your integration

Now it is time to thoroughly test all aspects of your integration, from making a payment to reconciliation.

  1. Make various types of test transactions.

  2. Learn how to handle failed payments and other error conditions, and how to solve issues with your terminals.

  3. Ensure your reconciliation is working.

    • Download the Settlement details report automatically.
    • Learn how to automate your payment reconciliation.
    • If you're using Store IDs or currency conversion (DCC), ask our POS Support Team to add these fields to your reports.

Going live

When you have finished testing, you first have to apply for a live account and sign the contract before you can take your integration live.