Make a payment

Make an in-person 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 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.

Before you begin

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:

Order a terminal and board it to a store.
Determine whether your integration will use a local or cloud-based architecture.
Read and understand the Terminal API fundamentals.
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:

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.

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

See the PaymentRequest API reference.

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

If you are building a test integration, you can use an Adyen test card (that you ordered with your test terminal).
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 your POS app to show progress messages that 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, see our display notifications documentation.

Payment response

When your payment has been processed by the terminal you receive the payment result. This is provided either in a synchronous API response or via a webhook when your integration uses asynchronous cloud communications.

For 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.

For asynchronous cloud communications you receive the result in an event notification.

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
```
{
  "SaleToPOIResponse":{
    "MessageHeader":{...},
    "PaymentResponse":{
      "POIData":{
        "POITransactionID":{
          "TransactionID": "oLkO0012498220087000.KHQC5N7G84BLNK43"
        },
        ...
      },
      "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.
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.

While building a test integration, you can simulate payment failure scenarios. For example, if you specify a RequestedAmount with 123 as the last three digits, such as 101.23 or 41.23, the payment will be Declined.

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
```
{
  "SaleToPOIResponse":{
    "MessageHeader":{...},
    "PaymentResponse":{
      "POIData":{
        "POITransactionID":{
          "TransactionID": "oLkO0012498700082200.NC6HT9CRT65ZGN82"
        },
        ...
      },
      "Response":{
        "AdditionalResponse":"...pspReference=NC6HT9CRT65ZGN82...",
        "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

required

Refund a payment

Issue a point of sale refund.

required

Verify payment status

Verify the status of a transaction when you don't receive a result.