Terminal API integration checklist

An integration with Adyen's Terminal API lets you to start payments from your POS app 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.

Requirements

• Read Get started with Adyen.
• Sign up for a test account.

Step 1: Set up your Adyen test account

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

You need to set up your account structure again when you go live, but the basic structure for the test environment should reflect the structure that you plan to have for your live environment.

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.

Step 2: Scope your integration

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

1. Choose your integration architecture:

   • With Terminal API local communications your POS app communicates directly with the payment terminal over your local network.

   • With Terminal API cloud communications your POS app communicates with the payment terminal through the Adyen payments platform.

     Always consult Adyen before building a cloud integration.

   • If you do not need a fully-featured POS system, you can use our Standalone solution instead. With this, you can accept payment directly from a terminal, without any development or integration work. Refer to the Standalone integration checklist.

   • With our mobile solution you start transactions from a mobile device that has our POS Mobile SDK added to your POS app. For this option, you must set up a Terminal API integration and add the SDK depending on your mobile solution.

2. Have a look at the overview of payment features and follow the links in that overview 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 is 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 test 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. For an integrated solution, enable Terminal API for your terminals.

2. Add payment methods and configure the terminal settings and payment features that are in the scope you decided on. Our Support Team will help you with any features that you cannot 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 want to create an API credential in addition to the default one, or create separate API credentials for point of sale and ecommerce. It is good practice (though not required) to do the same on your test account.

   Add Customer Area users

   Optional. Give team members access to the Customer Area.

   Create API credentials

   Optional. Add an API credential to each merchant account.

2. If you chose Terminal API integration, 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.

   Local integration?

   Configure your network and protect your requests.

   Cloud integration?

   Configure your network for cloud communication.

   Authentication

   Learn about IP addresses, endpoints, and authentication.

   Network recommendations

   Tips for network configuration and connectivity.

3. When you receive the test 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.

   Get terminals up and ready

   Connect and board the terminals when you receive them.

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.

   • Make payments:

     • Test the happy flow by making payments with your test terminals and test card.
     • Test non-happy flows such as time-outs and connection problems.
     • Simulate various acquirer responses to test your handling of declined transactions.

     • Test different card types and Cardholder Verification Methods (CVM).

   • Cancel payments, both from your POS app and from the terminal.

   • Refund payments, both with and without reference to an original transaction.

   • Test the payment methods and features that you added to your integration.

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

   Handle responses

   Learn about error conditions and when to retry failed payments.

   Troubleshooting terminals

   Learn how to solve issues with your terminals.

3. Make sure that your reconciliation is working.

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

   Settlement details

   Download this report automatically.

   Settlement reconciliation

   Learn how to do settlement reconciliation.

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.