Search

Are you looking for test card numbers?

Would you like to contact support?

Make a basic payment

Make a basic card payment using our Terminal API.

This page will take you through the process of 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.

Before accepting live payments, we 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 and make your first basic point of sale payment, 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.
  3. Board the terminal.
  4. If you are using cloud-based communications, generate an API key.

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

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.

You find the details of the payment in your Customer Area, under Transactions > Payments.

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 secure 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, see Secure local communications.

Next steps