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
- Read the Get started with Adyen overview and 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.
Determine the structure of your Adyen account, based on our documentation about the company account, merchant accounts, and stores.
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.
- If you require stores in your account structure, wait for confirmation that your merchant accounts are created and then submit your store request form.
Determine account structure
Learn about the company account, merchant accounts, and stores.
Request merchant accounts
Add one or more merchant accounts.
Optional. Add stores to your merchant accounts.
Step 2: Scope your Terminal API integration
The next step is to determine the scope of your integration.
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.
Always consult Adyen before building a cloud integration.
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.
- 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.
Choose between a local or cloud architecture.
Choose payment features beyond the basic operations.
Choose the default E2EE encryption or P2PE encryption.
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.
Choose the terminals that you want to use. Adyen has a wide range of terminal models for different business needs.
- 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.
Choose one or more terminal models.
Order one or more test terminals and a test card.
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.
Enable Terminal API for your terminals.
Add payment methods and configure the terminal settings 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.
- 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.
Enable Terminal API
Make your terminals ready to use the Adyen Terminal API.
Add branding and set up payment features.
Prepare your terminals for quicker boarding.
Step 5: Set up your integration
Now you can build out your integration.
- 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's good practice (though not required) to do the same on your test account.
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.
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.
Step 6: Test your integration
Now it is time to thoroughly test all aspects of your integration, from making a payment to reconciliation.
Make various types of test transactions.
- Test the happy flow by making payments with your test terminals and test card.
- Test non-happy flows such as timeouts and connection problems.
- Simulate various acquirer responses to test your handling of declined transactions.
- Cancel payments, both from the cash register 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.
Learn how to handle failed payments and other error conditions, and how to solve issues with your terminals.
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.
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.