Make a payment

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

To initiate a payment, you make a Terminal API request from your POS app. 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.

Requirements

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

• Get an overview of the steps needed to accept live payments.
• Create your test account.

After you have created your test account:

1. Order a terminal and board it to a store.
2. Determine whether your integration will use a local or cloud-based architecture.
3. Read and understand the Terminal API fundamentals.
4. If you are building a integration that uses asynchronous cloud communications, make sure you have set up event notifications. This is how your integration will receive the payment result.

Make a payment request

The first step in making a card payment is to initiate it, with an API request from your POS app. When you make this request, the terminal prompts the shopper to present their card by swiping, inserting, or tapping it on the terminal. If required, the shopper then verifies the payment by entering their PIN or signature.

To initiate the payment:

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

   • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		Payment
     MessageType		Request
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     SaleID		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • PaymentRequest: The request body. This must include:

     Parameter	Required	Description
     SaleData.SaleTransactionID		An object with: TransactionID: your reference to identify a payment. We recommend using a unique value per payment. In your Customer Area and Adyen reports, this will show as the merchant reference for the transaction. TimeStamp: date and time of the request in UTC format.
     PaymentTransaction.AmountsReq		An object with: Currency: the transaction currency. RequestedAmount: The final transaction amount.

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

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

Payment response

When your payment has been processed, you receive the payment result. How you receive the payment response depends on whether your integration uses synchronous or asynchronous cloud communications.

If you are using synchronous communications, local or cloud, you receive the result in the API response. The main payment result is provided in the element PaymentResponse.Response.Result.

If you are using asynchronous cloud communications, you need to set up event notifications to receive the result of the transaction.

If the payment is successful:

• Approved is shown on the terminal display.

• You receive the payment result. This contains:

  • POIData.POITransactionID.TransactionID: Transaction identifier for the payment.
  • PaymentResponse.Response.Result: Success.

    Other possible results are Partial for a successful partial payment, or Failure for a declined payment.

  • PaymentResponse.Response.AdditionalResponse: additional transaction data. For example, data relating to features such as shopper recognition or shopper input.

    To always receive the AdditionalResponse as a Base64-encoded JSON object, or always as form-encoded key-value pairs, contact our Support Team.

  • PaymentReceipt: object containing data you can use to generate a receipt.

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

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.
To learn what you can do when a request fails, see Handle responses.
For information on the payment scenarios you can test, see Simulating declined payments and Testing QR code wallets.

When a payment fails:

• Declined is shown on the terminal display.

• 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.NC6HT9CRT65ZGN82:

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

After you have 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.