Make transactions

To enable the Adyen POS Mobile SDK for Android to handle payments, you need to add code to your Android POS app. This code starts a transaction with:

• A Terminal API request.
• The NFC reader on your mobile device.

After you have added this code, payments take place as follows:

1. Your Android POS app creates a Terminal API request that is serialized to JSON, or you receive the Terminal API payment request from your backend.
2. You pass the Terminal API request to the Adyen POS Mobile SDK.
3. The SDK checks if the session is still valid, and if necessary establishes a new session.
4. The transaction starts on your mobile device.
5. The SDK passes the Terminal API response to your POS app.

Handle a payment

In your Android POS app, add code for the following steps:

1. If you create the Terminal API payment request in your POS app, use InPersonPayments.getInstallationId() as POIID in the MessageHeader of the payment request.
   Note that if you create the Terminal API payment request in the backend, the backend uses the installationId from the /checkout/posskd/v68/sessions response.

   For the structure of a Terminal API payment request, see Make a payment.

2. Create an instance of TransactionRequest using TransactionRequest.create(nexoRequest), and pass the Terminal API payment request from your POS app or backend.

   val transactionRequest = TransactionRequest.create(nexoRequest)

3. Get a PaymentInterface from InPersonPayments using InPersonPayments.getPaymentInterface(TapToPay).

   val paymentInterface = InPersonPayments.getPaymentInterface(TapToPay)

4. Register a listener for the PaymentResult and pass the transactionResponse to your POS app. This is the Terminal API payment response, including data you can use to generate a receipt.

   InPersonPayments.registerForPaymentResult(context) { result -> 
     result.fold( 
       onSuccess = { paymentResult -> {
                     // Here your logic for paymentResult if (paymentResult.success) "Payment Successful" else "Payment Failed" 
                   }, 
       onFailure = { error -> {
                   // Here your logic for failure case 
                   },
           )
   

5. Invoke InPersonPayments.performTransaction() with your transaction data, payment launcher, and authentication service.

   Customize the user interface using merchantUiParameters with the following optional fields:

   • merchantLogo: A logo in WEBP, JPEG, or PNG format to show on your mobile device during the transaction flow. The logo will be shown at 100dp x 32dp (width x height).
   • autoDismissDelay: Indicates how long the SDK shows the screen that indicates the transaction succeeded. If not specified, this success screen is dismissed after four seconds. You can set a time in milliseconds as a Long with a minimum of 0.5 seconds (500L) and a maximum of 4 seconds (4000L).

   InPersonPayments.performTransaction(
              context = context,
              paymentInterface = paymentInterface,
              transactionRequest = transactionRequest,
              paymentLauncher = paymentLauncher,
              merchantUiParameters = MerchantUiParameters.create(
                 merchantLogo = R.drawable.temp_merchant_logo_int,
                 autoDismissDelay = 2000L
                 )
          )

   The Adyen POS Mobile SDK checks for a session and shows the transaction screen on your mobile device.

Handle a refund

There are two types of refund: referenced and unreferenced. The main difference is that a referenced refund is connected to the original payment, and an unreferenced refund isn't. That makes unreferenced refunds a bit riskier. For an overview of the differences, see Refund a payment.

Refunds are usually not processed synchronously. When you send a request for a referenced or unreferenced refund, the Terminal API response only confirms we received the request. Unreferenced refunds, however, can be processed synchronously. This depends on the card scheme and the country/region where the card is used. If processed synchronously, you receive an additional field in the Terminal API response: acquirerResponseCode.

To learn the outcome of a refund, you need to set up webhooks.

Handle a referenced refund

The Terminal API request for a referenced refund is a reversal request. The SDK contains a dedicated function for this.

In your Android POS app, add code for the following steps:

1. If you create the Terminal API reversal request in your POS app, use InPersonPayments.getInstallationId() as POIID in the MessageHeader of the payment request.
   Note that if you create the Terminal API reversal request in the backend, the backend uses the installationId from the /checkout/posskd/v68/sessions response.

   For the structure of the Terminal API reversal request, see Referenced refund.

2. Create an instance of TransactionRequestReversal using TransactionRequestReversal.create(nexoRequest), and pass the Terminal API payment request from your POS app or backend.

3. Register a listener for the PaymentResult and pass the transactionResponse to your POS app. This is the Terminal API payment response, including data you can use to generate a receipt.

   val paymentLauncher = InPersonPayments.registerForPaymentResult(this) { refundResult ->
       // handle refund response here
       ...
   }

4. Invoke performReversal() with your transaction data and authenticationProvider.
   Note that authenticationProvider is an implementation of the AuthenticationProvider interface, which extracts the sdkData from the server response.

   public fun performReversal(
       context: Context,
       paymentLauncher: ActivityResultLauncher<Intent>,
       transactionRequestReversal: TransactionRequestReversal,
   )  

5. Check the refundResult that you receive in the paymentLauncher callback.

6. Pass the refundResult to your POS app.

Handle an unreferenced refund

The Terminal API request for an unreferenced refund is a payment request with an additional parameter:

• PaymentData.PaymentType: Refund

This means you can use the same code as for handling a payment. The only difference is the structure of the Terminal API payment request that you pass as the payload to the TransactionRequest.

Testing

To test transactions, you can use the following Adyen point-of-sale test cards:

• White-green test card
• Blue-green test card version 2.4 or later

The instructions are the same for both cards; see either of the pages mentioned above.

Troubleshooting

The Adyen payments platform performs regular checks to make sure that the mobile device on which the SDK is installed is secure. Below you can find the table with the most common errors and how to handle them.

Next steps