Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

Make a basic payment

Make a basic card payment using our Terminal API.

This page will take you through the process of setting up a terminal, and making a basic card payment using Adyen's Terminal API. From here you can build an integration that supports NFC and digital wallet payment methods, lets shoppers pay in their own currency, or offers a unique omnichannel shopper experience.

The terminal and cash register communicate using JSON messages. These are transmitted over either a cloud-based or local network, depending on your choice of architecture.

To make basic point of sale payments, you need to:

  1. Configure your Adyen account for basic in-store payments.
  2. Board the terminal.
  3. Make the payment.

Before accepting live payments, we also recommend that you thoroughly test your point of sale integration

If you are using local communication you'll also need to set up encryption before you can accept live payments.

Before you begin

Before you start integrating with our Terminal API, make sure that you have performed the following steps:

  1. Sign up for an Adyen test account at https://www.adyen.com/signup.
  2. Order a test terminal and cards.

For more information on integrating with Adyen, refer to Get started with Adyen.

Step 1: Configure your Adyen account

When you've received an Adyen test terminal, configure your Adyen account for basic point of sale payments:

  1. Log in to your Customer Area.
  2. Navigate to Account > Users, and click Add new user.
  3. Under User Account Details, click Webservice.
  4. Under Roles and Associated Accounts, enable Submit POS payments.
  5. Click Save.
  6. If you are using a cloud integration you also need an API key. To generate one:

    1. Under Authentication, click Generate New API Key
      Your API key is displayed. 
    2. Save a copy of this in your system, as you will need it to make payments.
    3. Click Save Generated API Key.

Your account is now configured to make basic point of sale payments. You can now board the test terminal.

Step 2: Board terminal

By boarding a terminal you associate it with your merchant account, and can use it to make payments. Boarding involves:

  1. Connecting the terminal to a network.
  2. Assigning the terminal to your Adyen account, using a one time password.

Connect terminal to network 

To connect the terminal to your network:

  1. Press the Configure Network button on the terminal display.
  2. Select your network type. If prompted, select your network from the list and enter the network password.

    If you're building an integration that uses local communications, you must connect the terminal to the same network as your cash register.

    The terminal will connect to the network, and prompt you to assign the terminal to your account.

Assign terminal to your account 

Assigning the terminal to your Adyen account requires you to enter a one time password, which you find in your Customer Area. The one time password is a six-digit code that refreshes every 30 seconds.

To assign the terminal:

  1. Log in to your Customer Area:
  2. Select your merchant account.
  3. Navigate to Point of sale > Terminals, and click the Inventory tab.
  4. Select your test terminal and enter:

    1. Assign to account: Your merchant account name.
    2. Assign to store: Your store ID, if you have one. This is optional.
  5. Click Assign
    The page refreshes.
  6. In the Terminal API tab, set:

    1. Enable Terminal API to Yes.
    2. Enable WebSockets to Yes. This is only required if your integration uses cloud-based communications.
    3. Click Save.
  7. Copy the Serial number of the terminal, which is presented at the top of the screen. You will need this later to make the payment.
  8. A One time password is also presented at the top of the screen. 
    To complete registration, enter this on your terminal:

    1. On the terminal screen, tap the Board the terminal button.
    2. Enter the one time password using the keypad.
      The terminal will reboot.

After rebooting, the terminal receives your merchant configuration. You can now use this terminal to make payments.

Step 3: Make a payment

Communication between the terminal and cash register is via JSON messages. To initiate a payment, you make a JSON request from your cash register. This is routed to the terminal, where the shopper can present their card and complete the payment.

To initiate the payment:

  1. Make a POST request to a Terminal API endpoint, specifying:

    • content-type: application/json
    • x-api-key: API key that you generated earlier

      An API key is only required if you're using cloud-based communications.

    • ProtocolVersion: 3.0
    • MessageCategory: Payment
    • MessageType: Request
    • SaleID: Your unique ID for the cash register.
    • ServiceID: Your unique ID generated by this cash register for this transaction. This needs to be unique within the last 48 hours.
    • POIID: Unique ID of the terminal. 

      The POIID = [Terminal model]-[Serial number], for example: P400Plus-123456789

    • TransactionID: Your unique reference for this transaction.
    • TimeStamp: Date and time of this transaction.
    • AmountsReq: The Currency and value (RequestedAmount) of the transaction.

    The example below shows how you would make a 10.99 EUR payment using synchronous cloud-based communication.

    curl -H "content-type:application/json" -H "x-api-key:YOUR_API_KEY" -X POST --data-binary '{
      "SaleToPOIRequest":{
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "SaleID":"POSSystemID12345",
          "ServiceID":"0207111104",
          "POIID":"V400m-324688179"
        },
        "PaymentRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"27908",
              "TimeStamp":"2019-03-07T10:11:04+00:00"
            }
          },
          "PaymentTransaction":{
            "AmountsReq":{
              "Currency":"EUR",
              "RequestedAmount":10.99
            }
          }
        }
      }
    }' --url https://terminal-api-test.adyen.com/sync

    For a complete list of fields you can pass in a payment request, see the PaymentRequest API reference.

    The request is routed to the terminal, for the shopper to complete the transaction.

  2. Present the test card to the terminal.

  3. Follow the instructions on the terminal to complete the transaction. 

    The PIN for the test card is 1234.

If the payment is successful:

  • Approved is displayed on the terminal screen.

  • You receive a JSON response with:

    • AdditionalResponse: Contains a pspReference value, which is our unique identifier for this transaction.
    • Result: Success
    {
      "SaleToPOIResponse":{
        "PaymentResponse":{
          "Response":{
            "AdditionalResponse":"...pspReference=981517998282382C...",
            "Result":"Success"
          },
        {...}
      }
    }

    For a complete list of fields you can receive in a payment response, see the PaymentResponse API reference.

Terminal API endpoints

For test transactions, use the endpoint below that corresponds to your integration architecture.

For more information on these architectures, see our Terminal API overview.

Local

Endpoints for local communications with the Terminal API use the format:

  • https://[TERMINAL]:8443/nexo/ on port 8443 (https).
    Replace [TERMINAL] with the IP or resolvable hostname of the terminal.

Cloud

For cloud-based communications with the Terminal API use either:

Encrypting local communications

If your cash register has a local connection with the terminal you will need to encrypt any communications between these devices. This is not a requirement for making test payments, but will need to be configured before you can accept live payments.

For more information on encrypting local communications, see Encrypting messages.

Next steps