Make a payment

Make an in-person card payment.

This page describes how to make a basic Terminal API payment request.

As mentioned in the requirements, there are various integration design aspects that you must have decided on and implemented first. These aspects are described on other pages. Also note that you need to have a boarded test payment terminal or a mobile device for testing.

Requirements

Before you begin, take into account the following requirements and preparations.

Requirement	Description
Integration type	Use this information to build a Terminal API integration with payment terminals or with a Mobile solution.
Hardware	Make sure you have: A POS test card. A test payment terminal that has been boarded. Or if you are building a Mobile solution, you need to have an Android or iOS mobile device that you can use for testing.
Setup steps	Before you begin, make sure you have scoped and designed your integration and followed the applicable integration checklist up to the point where you are ready to integrate making a test payment. See the information for your integration type. Payment terminals: Terminal API integration checklist; Design your integration. Android Mobile solution: Get-started checklist; Build your solution. iOS Mobile solution: Get-started checklist; Build your solution.

How it works

From your POS app, you send an API request to make a payment.
The request is routed to the payment terminal or mobile device.
1. A screen appears that prompts the customer to present their means of payment. The customer can tap, insert, or swipe a credit or debit card, or use an NFC digital wallet like Apple Pay. If needed, the customer enters their PIN or signature.
2. A waiting screen is shown while we try to get the payment authorized.
3. After the authorization attempt, a screen appears that shows if the payment was approved or declined.
The following example screens show the payment flow.
Note that the position of screen elements can differ by payment terminal model (or other hardware as used in a Mobile solution). This applies, for example, to the icon that indicates the location of the contactless reader.

Payment screen Authorizing screen Approved screen
You check the API response. Note that if you use asynchronous cloud communications with payment terminals, you receive the API response in an event notification.
If you did not receive a response or if the payment failed, you take troubleshooting steps.

Make a payment request

To initiate the payment:

Make a Terminal API payment request, specifying:

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

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

The PaymentRequest object with:

Parameter	Required	Description
`SaleData.SaleTransactionID`		An object with: `TransactionID`: A string with 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`: A string with the date and time of the request in UTC format.
`PaymentTransaction.AmountsReq`		An object with: `Currency`: A string with the three-letter currency code for the transaction. `RequestedAmount`: The final transaction amount in number format, with a decimal point. For example, 10.99.

In the PaymentResponse, note the following:

Parameter	Description
`POIData.POITransactionID.TransactionID`	The unique transaction identifier for the payment. Save this ID in your system. You may need this ID later, for example, to look up the payment in your Customer Area, for reconciliation purposes, or to make other requests such as a refund or manual capture.
`Response.Result`	The result is Success for an approved payment, or Failure for a declined payment. In case of a partial payment the result can also be Partial.
`Response.ErrorCondition`	If the `Result` was Failure, this parameter indicates why the payment failed.
`Response.AdditionalResponse`	A string with additional transaction data. The string can consist of form-encoded key-value pairs, or a Base64-encoded JSON object. You can ask our Support Team to ensure you always receive the `AdditionalResponse` in one of these formats.
`PaymentReceipt`	An object with data you can use to generate a customer receipt and a cashier receipt.

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

Troubleshooting

There are two types of issues with payment requests that your integration must be able to handle:

You made a payment request but did not receive a response (either a direct Terminal API response, or a Terminal API response received as an event notification).
The payment response indicates a failure.

No response

It is possible that you do not receive a payment response due to a technical or connection issue. It is also possible that the payment remains in progress for a long time, for example when the customer does not react to a prompt on the payment terminal. To cope with these scenarios, we strongly recommend that your integration is able to automatically verify the transaction status. This can help reduce the risk that your store staff unnecessarily refunds the payment, or makes a duplicate payment.

Failure

If a payment fails, the PaymentResponse includes:

Response.Result: Failure.
Response.ErrorCondition: The type of failure. For example, Refusal when the card issuer refused the transaction.
Response.AdditionalResponse: Contains a message with additional information about why the payment failed. In the case of a declined payment, the additional response also includes the refusalReason, for example, Expired card.

To learn what to do, see:

Handle responses: The various scenarios that can lead to a failed payment request.
Refusal reasons: The most common refusal reasons grouped by ErrorCondition, with information about whether you can retry the transaction.

Testing

To make test payments, you need to have a POS test card and either a test payment terminal that has been boarded, or an Android or iOS mobile device that you can use for testing if you are building a Mobile solution.

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.

For information about the payment scenarios you can test, see Simulating declined payments.