Search

Are you looking for test card numbers?

Would you like to contact support?

Make a payment

Make a point of sale card payment.

After you have designed your integration and boarded your terminal, you are ready to make card payments on the Adyen payments platform.

To initiate a payment, you make a Terminal API call from your cash register. This routes the transaction to the terminal, which prompts the shopper to present their card and verify the payment. The terminal then sends the payment to Adyen for processing.

Once processed, your integration receives the result of the payment.

Before you begin

Before you make a payment with our Terminal API, make sure you have designed your Adyen point of sale integration. This includes:

  1. Signing up for an Adyen test account, and creating a store.
  2. Ordering a terminal and boarding it to a store.
  3. Determining whether your integration will use a local or cloud-based architecture.
  4. Reading and understanding the Terminal API fundamentals.
  5. If you are building a integration that uses asynchronous cloud communications, make sure you have set up display notifications. This is how your integration will receive the payment result.

Step 1: Initiate payment

The first step in making a card payment is to initiate it, with an API request from your cash register. Once you make this request, the terminal will prompt the shopper to present their card by swiping, inserting, or tapping it on the terminal. The shopper then verfies the payment by entering their PIN or signature.

To initiate the payment:

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

    • MessageHeader: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageCategory: Payment. This indicates you are initiating a payment request.
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for this transaction attempt. This needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal.¬†This indicates which terminal the payment will be routed to.
    • PaymentRequest: The request body for the payment request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this payment request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the payment request, in UTC format.
      • PaymentTransaction.AmountsReq.Currency: The currency of the transaction.
      • PaymentTransaction.AmountsReq.RequestedAmount: The transaction amount.

    The example below shows how you would initiate a 10.99 EUR payment on the terminal with the POIID V400m-324688179

    For more information on the Terminal API request structure, refer to the Terminal API fundamentals.

    {
      "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
            }
          }
        }
      }
    }

    The payment request is routed to the terminal, for the shopper to present their card and verify the payment.

  2. If you are building a test integration, you can use the Adyen test card (that came with your terminal). The PIN for this card is 1234.

The payment is then sent to the Adyen payments platform for processing. Once processed, your integration receives the payment result.

Keeping your staff informed with webhooks

While your shopper is interacting with the terminal, you may want to present progress messages on your cash register. These can keep your staff informed when:

  • The terminal is waiting for the shopper's PIN or signature.
  • The shopper's signature is ready for checking.

These messages are delivered using display notifications, which are webhooks that are sent to an endpoint that you specify. For information on how to set up and use display notifications, as well examples, refer to our display notifications documentation.

Step 2: Receive payment result

When your payment has been processed on the Adyen payments platform, you receive the payment result. This is provided in a synchronous API response, unless your integration uses asynchronous cloud communications.

If your integration uses asynchronous cloud communications, you receive the result in a TENDER_FINAL display notification.

If the payment is successful:

  • Approved is displayed on the terminal screen.
  • You receive the payment result. This contains:

    The example result below indicates that the payment was successful. The transaction identifier for this payment is oLkO0012498220087000.981517998282382C

    {
      "SaleToPOIResponse":{
        "MessageHeader":{...},
        "PaymentResponse":{
          "POIData":{
            "POITransactionID":{
              "TransactionID": "oLkO0012498220087000.981517998282382C"
            },
            ...
          },
          "Response":{
            "Result":"Success",
            "AdditionalResponse":"...shopperEmail=shoppersemail%40address.com..."
          },
          ...
        },
        "PaymentReceipt":{...}
      }
    }

You can also view the details of a payment in your Customer Area, under Transactions > Payments.

Handling failed payments

If a payment fails, the payment result includes the Result Failure, as well as information on why the payment failed.

While building a test integration, you can simulate payment failure scenarios. For example, if you initiate a payment with the RequestedAmount 1.23 the payment will be Declined. For more information on the payment scenarios you can test, see testing your integration.

When a payment fails:

  • Declined is displayed on the terminal screen.
  • You receive a payment result containing:

    • POIData.POITransactionID.TransactionID: Transaction identifier for the failed payment.
    • PaymentResponse.Response.Result: Failure
    • PaymentResponse.Response.ErrorCondition: Indicates why the payment failed.
      For example, Refused indicates the card issuer refused the transaction, and Cancel indicates the transaction was cancelled on the terminal. You can check our refusal reasons documentation for a list of failure reasons and what these mean.

    The example result below indicates that the payment failed because it was refused by the card issuer. The transaction identifier for this payment attempt is oLkO0012498700082200.982823828151799C

    {
      "SaleToPOIResponse":{
        "MessageHeader":{...},
        "PaymentResponse":{
          "POIData":{
            "POITransactionID":{
              "TransactionID": "oLkO0012498700082200.982823828151799C"
            },
            ...
          },
          "Response":{
            "AdditionalResponse":"...pspReference=982823828151799C...",
            "Result":"Failure",
            "ErrorCondition":"Refused"
          },
          ...
        }
      }
    }

You can also view the details of failed payments in your Customer Area, under Transactions > Payments.


After you've made a test payment, you can continue building your integration. You may want to learn how to issue refunds, accept other payment methods, or enable tipping and gratuities.

Alternatively, you can learn what to do when you do not receive a payment result (for example, due to a technical or connection issue). We strongly recommend that your integration is able to automatically verify the status of a payment in this scenario. This can help reduce the risk of your store staff unnecessarily refunding the transaction, or making a duplicate payment.

Next steps