Autonomous stores

Use Adyen payment terminals to process payments and grant access to unattended stores.

Autonomous stores are stores without staff or checkout. A shopper presents their card to the payment terminal before entering to pre-authorize a certain amount and gain entry. They then take the items and leave the store. The purchase amount is adjusted and charged to the card that they used to enter the store.

How it works:

You make a card acquisition request on the terminal to get the card details.
The shopper presents their card to the payment terminal.
You use identifiers from the card acquisition response to check if you recognize the shopper. If it is a first-time shopper, you collect their details like phone number or email. You can use card identifiers to tokenize the card for future recurring payments.
You send a payment request to pre-authorize an amount.
We recommend that you also tokenize the card for future recurring payments. This enables you to recover the full payment in case an authorization adjustment fails.
The shopper enters the store, takes items, and leaves the store.
If the purchase amount is different from the pre-authorized amount, you send an authorization adjustment request, followed by a capture request.
If the authorization adjustment fails for any reason, you can capture the pre-authorized amount. After that:
- If you tokenized the card, you can make a recurring online payment for the remaining amount.
- If you collected the shopper's email or phone number, you can send them a payment link for the remaining amount.

If you cannot charge the shopper for their purchase, you can put the card alias on the not-allowed list in your system to prevent the card from being used to enter the store again.

Requirements

Before you configure the autonomous stores flow:

Check if authorization adjustment is available for your merchant category code, and be aware of the expiration period of pre-authorization requests.
Make sure that you have built an integration that can make a payment.
Set up webhooks. You will need to rely on webhooks to know if the capture succeeded. If you use asynchronous authorization adjustment, you will also need to rely on webhooks for the authorization adjustment result.
Generate an API key. To adjust the authorization and finalize the pre-authorized payment, you need to have an API key.

If you are using cloud-based communications, you can use the existing API key that you use for Terminal API requests.
Contact our Support Team to configure your payment methods. If you plan to use synchronous authorization adjustment, also ask them to enable this for you.
Make sure that you have selected a terminal model suitable for use in unattended environments: P400 Plus or UX300.

Also be aware that you need to implement logic on your end, for example how to trigger card acquisition requests on the terminal, open the doors, or calculate the amount when you make an authorization adjustment.

Step 1: Get card details

In your back-end, implement a trigger for the card acquisition request on the terminal to prompt the shopper to present a card. From the response, you can take certain details such as the card alias to determine if the shopper should be let in.

Create a SaleToPOIData JSON object with:
- Operation.Type: Payment
- Operation.Variant: PreAuthToEnterShop. Hides the pre-authorization amount specified in CardAcquisitionTransaction.TotalAmount from showing on the initial screen. This is to prevent shoppers from thinking they need to pay to enter the store.
Encode the Operation JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData.
Create a SaleToAcquirerData JSON object with:
- authorisationType: PreAuth. Pre-authorizes the amount specified in CardAcquisitionTransaction.TotalAmount.
- recurringProcessingModel: UnscheduledCardOnFile. Enforces cardholder authentication during pre-authorisation (if configured by our Support Team). To tokenize the card, include this field in both the card acquisition and the follow-up pre-authorization payment request.
  
  If the PSD2 SCA compliance rules apply to your business, we recommend enforcing cardholder authentication. To enable this, contact our Support Team.
Encode the JSON object to Base64. You will pass the resulting string in SaleData.SaleToAcquirerData.

Make a CardAcquisitionRequest with:

CardAcquisitionRequest.SaleData:

Parameter	Required	Description
`SaleTransactionID`		An object with: `TransactionID`: your reference to identify the transaction. We recommend using a unique value. `TimeStamp`: date and time of the request in UTC format.
`TokenRequestedType`		Customer. Returns the card alias in the `TokenValue` field of the response. Note that the card alias is always returned in the `AdditionalResponse`.
`SaleToPOIData`		The Base64-encoded `Operation` JSON object from step 2.
`SaleToAcquirerData`		The Base64-encoded JSON object from step 4.

CardAcquisitionRequest.CardAcquisitionTransaction:

Parameter	Required	Description
`TotalAmount`		The transaction amount you want to pre-authorize before entering the store. This amount needs to be equal to the `TotalAmount` in the pre-authorization request.

The example below shows a card acquisition request to get the card details:

The example below shows a card acquisition response with an amount of EUR 10:

From the CardAcquisitionResponse, save the following details :
- POIData.POITransactionID: since you are continuing with a payment, keep the TimeStamp and the TransactionID because you need these card acquisition details in your payment request.
- Response.AdditionalResponse.alias: this is a value that uniquely represents the shopper's card number (PAN), for example A37317672402294. With this, you can recognize the card that a shopper is using and identify if they are returning customers. You cannot use the card alias for making payments.
The format of the AdditionalResponse can be a Base64-encoded or URL-encoded. To always receive the AdditionalResponse in one of those formats, contact our Support Team.

If the shopper is entering the store for the first time, we recommend you collect their details. Otherwise, you can proceed with a pre-authorization payment request.

Step 2 (optional): Ask for shopper's details

If the shopper is entering the store for the first time, you can ask them to enter their contact details, or to provide consent to tokenize their card.

Ask the shopper's consent to save their details. For this, you can use confirmation or signature input requests.
Collect the shopper's contact details. For this you can use phone number or text input requests. You can then use these details when tokenizing the card or to send the shopper a payment link.
Save the shopper's contact details and the card alias received in the Response.AdditionalResponse.alias of the card acquisition response.

You can use the card alias to recognize the shopper the next time they present their card to enter the store. This way, the shopper does not have to enter their details again.

Step 3: Pre-authorize an amount

After you collect the card and shopper details, send a payment request to pre-authorize the amount specified in the card acquisition request.

You can also tokenize the card with Adyen. This enables recurring payments with the shopper's card and allows you to recover failed payments in case the shopper has insufficient funds at the time of purchase.

If you plan to tokenize the card, make sure that you enable receiving shopper identifiers and check with our Support Team if your account is correctly configured for your tokenization use case.

Inside SaleData.SaleToAcquirerData, flag this as a pre-authorization request. Include:
- authorisationType: PreAuth: indicates this is a pre-authorization request.
- To tokenize the card, in the SaleData.SaleToAcquirerData also include:
  - shopperReference: your unique reference for this shopper. Minimum length: three characters. Note that the value is case-sensitive. Do not include personally identifiable information (PII), such as name or email address.
  - recurringProcessingModel: UnscheduledCardOnFile. Creates a recurring contract for transactions that occur on a non-fixed schedule and/or have variable amounts. Enforces cardholder authentication (if configured by our Support Team).
  - shopperEmail: optional. The shopper's email address, if you collected that in the previous step.
  Pass the SaleData.SaleToAcquirerData value in one of the following formats:
  - Option 1: a JSON object converted to a Base64-encoded string. Refer to Add information to a payment. For example:
    
    Encode the Operation JSON object to Base64.
  - Option 2: form-encoded key-value pairs (using & as a separator). For example:
  The format of the SaleToAcquirerData, Base64-encoded or key-value pairs, determines the format of the AdditionalResponse that you receive. To always receive the AdditionalResponse in one of those formats, contact our Support Team.

Make a pre-authorization PaymentRequest with:

PaymentRequest: the request body. This includes:

Parameter	Required	Description
`SaleData.SaleTransactionID`		An object with: `TransactionID`: your reference to identify a payment. We recommend using a unique value per payment. `TimeStamp`: date and time of the request in UTC format.
`PaymentTransaction.AmountsReq`		An object with: `Currency`: the transaction currency. `RequestedAmount`: the pre-authorized transaction amount. This amount needs to be equal to the `TotalAmount` in the card acquisition request.
`PaymentData.CardAcquisitionReference`		An object referring to the card acquisition: `TimeStamp`: The time stamp returned in the `POIData.POITransactionID` of the card acquisition response. `TransactionID`: the transaction ID returned in the `POIData.POITransactionID` of the card acquisition response.
`SaleData.SaleToAcquirerData`		The Base64-encoded JSON object or form-encoded key-value pairs from step 1.

The following example shows how to pre-authorize a payment of EUR 10:

The customer presents their card to the payment terminal. If the pre-authorization is successful, Approved shows on the screen.

From the response, save the following details:

For	Use these parameters
authorization adjustment and capture	`POIData.POITransactionID.TransactionID`: transaction identifier for the payment, in the format Tender_reference.PSP_reference. `Response.AdditionalResponse.pspReference`: the PSP reference of your pre-authorization request.
Calculating the amount for the authorization adjustment	`PaymentResult.AmountsResp`: the `AuthorizedAmount` and `Currency` of the pre-authorized payment. `Response.AdditionalResponse.authorisedAmountValue`: the pre-authorized amount in minor units.
Synchronous authorization adjustment	`Response.AdditionalResponse.adjustAuthorisationData`: a blob with authorization data, if the synchronous flow is enabled for your account.

For easier shopper recognition and recovering failed payments, from the Response.AdditionalResponse save the following details:

Parameter	Description
`alias`	The card alias. Also returned in `PaymentResult.PaymentInstrumentData.PaymentToken.TokenValue` if the request contains `TokenRequestedType`: Customer.
`PaymentAccountReference`	A value that represents the payment account that the card and/or NFC wallet is linked to.
`recurring.recurringDetailReference`	The token representing the shopper's payment method.
`recurring.shopperReference`	Your unique reference for this shopper.
`shopperEmail`	The shopper's email address .

The following example shows the response to a EUR 10.00 pre-authorization request.

Note that the PaymentToken object contains the card alias. You cannot use this for making payments. It is intended only for recognizing the card.

After a successful pre-authorization, you need to have logic implemented to open the door of the autonomous store. The shopper then enters the store, takes items, and leaves.

Step 4: Adjust the pre-authorized amount

If the purchase amount for items that shopper has taken differs from the pre-authorized amount, you need to send an authorization adjustment request. This is not a Terminal API request to the terminal itself or the Cloud endpoint for the terminal.
Depending on your infrastructure and implementation, you may want to use the asynchronous or synchronous authorization adjustment.

When building or testing the flow, make sure there is at least a 5 second delay between the pre-authorization and the authorization adjustment.

Step 5: Capture the amount

After you make the authorization adjustment, capture the payment manually to ensure the reserved funds are transferred to your account. Make sure that you have enabled manual capture, either for your account or for an individual transaction.

Make a POST request to the /payments/{paymentPspReference}/captures endpoint, specifying:

The path with:

Parameter	Required	Description
`paymentPspReference`		The `pspReference` of the authorization being captured. You received this as part of the `transactionID` field in the response to your payment request. See Transaction identifier.

The request header with:

Parameter Required Description

content-type application/json

x-api-key Your API key.

The request body with:

Parameter	Required	Description
`amount`		The `currency` and `value` of the final amount in minor units. This is the sum of the original, pre-authorized amount and all later adjustments.
`reference`		Your reference to this payment modification, for use in your reconciliation process.
`merchantAccount`		The name of your merchant account that is used to process the payment.

When you receive the capture response, note the following:
- pspReference: the PSP reference associated with this capture request. Note that this is different from the PSP reference associated with the pre-authorization request.
- status: received.
- reference: your reference to this payment modification, for use in your reconciliation process.
Wait for the asynchronous webhook. This informs you whether the final amount has been captured.
If the capture is successful, this webhook contains:
- eventCode: CAPTURE
- originalReference: The pspReference of the pre-authorization.
- pspReference: The PSP reference associated with this capture request.
- success: true
If success is false then your capture request failed. Review the reason you received in the webhook, fix the issue, and submit the capture request again.

Recover failed payments

If the authorization adjustment fails for any reason, for example because of a technical issue or insufficient funds on the cardholder’s bank account, there are several things you can do:

Send the capture request to collect the pre-authorized amount.
Make a recurring online payment for the remaining amount using the token you created in the pre-authorization payment request.
Send a payment link for the remaining amount to the shopper's email or phone number that you collected before the shopper entered the store.

You can also enable our Auto Rescue feature that automatically retries shopper-not-present card transactions when they are refused.

If all rescue attempts fail, you can put the card alias on the not-allowed list in your system to prevent the card from being used to enter the store again.