Shopper journey<\/h2>\n
From the shopper's perspective, this Endless Aisle retail use case is as follows.<\/p>\n
In the store, it turns out that items that the shopper wants to purchase are not available at the location. Store staff helps the shopper to order the items online, and select the store where they want to pick up the order. If desired, the shopper can combine the online order with purchasing items from the store that do not need to be ordered. The shopper presents their card on the payment terminal.<\/p>\n
When the order arrives at the selected store, the shopper is notified. The shopper goes to the store for pickup, and identifies by presenting their card on the payment terminal. The shopper is then handed the ordered goods. If desired, the shopper can combine picking up the online order with purchasing items that are available in the store.<\/p>\n
The following diagram illustrates this shopper journey.<\/p>\n
Considerations<\/h2>\n
Before you set up a flow for this use case, there are a couple of points that you must be aware of or make a decision on.<\/p>\n
Legal entity and location<\/h3>\n
In this use case, you use the payment terminal to authorize the online order.<\/p>\n
If you want to process your Endless Aisle online transactions over a different merchant account than the regular in-person transactions, ask your Ayden Account Manager or Implementation Engineer about Merchant Account Sharing<\/em>. With this, orders for both merchant accounts are processed on the same terminal, but kept separate. Enabling Merchant Account Sharing is subject to compliance approval. Terminals require a local legal entity.<\/p>\n If compliance approval is not given, you have other options to keep the transactions separate:<\/p>\n This use case requires specific procedures to capture the payment. You must enable and use manual capture, and contact our Support Team<\/a> to enable multiple partial captures.<\/p>\n For the ordered items, the amount is initially authorized, but not captured. When the shopper picks up the items in the store, you make a manual capture request. If all items are picked up at the same time, you capture the full amount. If items are picked up at different times, you make a partial capture request for each pickup. If the shopper drops online items when picking up the order, you make a partial capture request for the reduced amount.<\/p>\n It depends on your other use cases whether it is best to enable manual capture for every payment, or in the API request for an individual payment.<\/p>\n After sending a notification that the order is ready for pickup and waiting for the shopper to collect the order, it is possible that the authorization has expired when you try to capture the payment. To deal with that, you have several options:<\/p>\n Implement authorization adjustments<\/strong>. You need to choose between a synchronous flow or an asynchronous flow. In the synchronous flow you keep track of an Authorization adjustment is also useful for:<\/p>\n Use the Extend on capture<\/strong> feature. Implement tokenization<\/strong>. If you want to support mixed baskets, where the shopper combines an online order with items that are available in the store, we recommend discussing your Adyen account structure and capture strategy with your Adyen implementation engineer or account manager.<\/p>\n You have the following options for capturing the payment:<\/p>\n One transaction with multiple partial captures: this option requires that online and in-store items are processed under the same merchant account.<\/p>\n Two separate transactions: you authorize the online order and capture the amount later as ordered items are picked up. For the in-store items, you make a separate payment request and capture the amount automatically, immediately or with a capture delay. This approach applies for mixed baskets both when the shopper places the order, and when the shopper picks up the order.<\/p>\n<\/li>\n<\/ul>\n At order pickup, you use a card acquisition<\/em> request to find the shopper's order: the shopper presents their card or other payment instrument to the payment terminal. You then use the card alias or PAR from the response to look up the shopper and the order in your CRM system.<\/p>\n To use card acquisition in this way, you must enable receiving shopper identifying data in API responses, and you must store the card alias and\/or the Payment Account Reference (PAR) in the shopper's profile.<\/p>\n If the shopper does not have a record in your CRM system yet at the time of ordering, the CRM must also support manual entry of shopper details and creation of a new CRM record.<\/p>\n You need to decide beforehand on how you will attribute the sale: if items are online items but ordered and paid for in-store, is this an in-store sale or an ecommerce sale?<\/p>\n If the shopper does not want an ordered item, the item may be returned to the store (during pickup or later), or to the warehouse. Both systems must be able to look up the PSP reference for the order and issue a (partial) referenced refund. You need to support both:<\/p>\n If discounts are offered over the phone or chat, customer service agents must be able to trigger partial referenced refunds as well.<\/p>\n There are several Adyen API requests involved in the described shopper journey, as shown in the following diagrams for:<\/p>\n The next section, \"Instructions\", provides more details about the API flow.<\/p>\n We usually recommend delayed automatic capture for point-of-sale transactions. That is why the diagram shows automatic capture for the separate payment request related to the in-store items.<\/p>\n This section provides high-level instructions focusing on how to use the Adyen APIs and webhooks in the described shopper journey.<\/p>\n The code samples show the minimally required parameters. You can add more parameters.<\/p>\n<\/div>\n After the shopper has ordered the online items and selected a pickup store:<\/p>\n Make a Terminal API CardAcquisitionRequest<\/a> where the If you support mixed baskets as a single transaction, use the total amount of the basket: the purchase amount for the ordered online items and any items from the store. When you receive the CardAcquisitionResponse<\/a>, save the following information:<\/p>\n The following example shows the Use the card alias and\/or PAR from the card acquisition response to look up the shopper's contact details in your ERP system. You need the contact details later, to send a notification when the order is ready for pickup.<\/p>\n<\/li>\n If the shopper is found in the ERP system, let the shop assistant verify the contact details with the shopper. If the shopper is not found in the ERP system, add a record for the shopper to the ERP system with the card alias and\/or PAR from the card acquisition response, and the other details that you need, specifically the contact details and the name of the shopper. You can collect those other details in various ways, for example:<\/p>\n Make sure the pickup store location is included on the order.<\/p>\n<\/li>\n<\/ol>\n Make a Terminal API PaymentRequest<\/a> with:<\/p>\n Use one of the following formats to provide the When you receive the payment response, save details from the following fields:<\/p>\n If you use synchronous authorization adjustment, save the If you use tokenization, save the token ( If you support mixed baskets as a single transaction, make a partial manual capture request for the in-store items. See the example<\/a> below, under \"In-store pickup\".<\/p>\n<\/li>\n If you support mixed baskets as two separate transactions, make another Terminal API payment request for the in-store items. At one or more moments before or after you notify the shopper that the order is ready for pickup, you may need to extend the authorization. This ensures you can still capture the payment later, when the shopper arrives at the store to pick up the order. When the shopper arrives at the pickup location to collect the order:<\/p>\n To find the shopper's order based on the card that was used to authorize the order:<\/p>\n Make a Terminal API CardAcquisitionRequest<\/a> with an empty When you receive the CardAcquisitionResponse<\/a>, find the shopper's order in your ERP system using the following information from the The following example shows the When you have found the order, finish the card acquisition by making an EnableServiceRequest<\/a> to stop the flow. Optional, if you used pre-authorization and you support mixed baskets as one transaction:<\/p>\n If the shopper adds in-store items that significantly increase the amount due, make a POST \/payments\/{paymentPspReference}\/amountUpdates<\/a> request to adjust the authorization amount.<\/p>\n The following examples show how to adjust the amount for the authorization with PSP reference DXCD52AY3WUGXS93 up from USD 124.66 to USD 214.03 for added in-store items with a value of USD 89.37.<\/p>\n\n Make a manual capture request for the amount due: In your request, include:<\/p>\n\n
Capture settings<\/h3>\n
Authorization expiry and late capture<\/h3>\n
\n
\nYou pre-authorize the order, and after a while send a \/payments\/{paymentPspReference}\/amountUpdates<\/code> request with the amount due, to renew the authorization. You can repeat this several times as needed, but each adjustment incurs costs.<\/p>\nadjustAuthorisationData<\/code> blob that you pass from request to request. In the asynchronous flow you rely on webhooks to learn if the authorization adjustment succeeded.<\/p>\n\n
\nWhen you capture the payment, Adyen checks the status of the initial authorization. If the authorization has expired, we perform a new authorization request. This feature is supported for American Express, Mastercard, and Visa.<\/p>\n<\/li>\n
\nIn your Terminal API payment request for the online items, you include tokenization parameters so that you receive a token and a shopper reference in the response. If at capture it turns out the initial authorization has expired, you make a new payment request to the Checkout API \/payments<\/a> endpoint. This request includes the token and shopper reference.<\/p>\nMixed baskets<\/h3>\n
\n
\n
Card recognition<\/h3>\n
Sale attribution<\/h3>\n
Refunds and discounts<\/h3>\n
\n
API flow<\/h2>\n
\n
No mixed basket or mixed basket as one transaction<\/h3>\n
Mixed basket as two transactions<\/h3>\n
Instructions<\/h2>\n
Contact details<\/h4>\n
\n
CardAcquisitionTransaction<\/code> object contains the TotalAmount<\/code> field with the purchase amount for the ordered items.<\/p>\n
\nIf you support mixed baskets as two separate transactions, use only the amount of the ordered online items.<\/p>\n\n
AdditionalResponse.PaymentAccountReference<\/code>: the PAR, if present.<\/li>\nAdditionalResponse.alias<\/code>: the card alias.<\/li>\nTimeStamp<\/code> and TransactionID<\/code> from the POIData.POITransactionID<\/code> object. You need these values later, when you (pre-)authorize the transaction.<\/li>\n<\/ul>\nAdditionalResponse<\/code> as a string of key-value pairs concatenated with an ampersand (&<\/strong>). It is possible you receive a Base64-encoded string instead, which you need to Base64 decode first.<\/p>\n
\nEnsure the shop assistant can update this information in the ERP system, if needed.<\/p>\n<\/li>\n\n
(Pre-)authorization<\/h4>\n
\n
\n
PaymentData.CardAcquisitionReference<\/code>: an object with the TimeStamp<\/code> and TransactionID<\/code> returned in the POIData.POITransactionID<\/code> object of the card acquisition response.<\/p>\n<\/li>\nPaymentTransaction.AmountsReq<\/code>: an object with the Currency<\/code> and the RequestedAmount<\/code>.
\nIf you support mixed baskets as a single transaction, use the total amount of the basket.
\nIf you support mixed baskets as two separate transactions, use only the amount of the ordered online items.<\/p>\n<\/li>\nSaleToAcquirerData<\/code>: a parameter with manualCapture<\/strong><\/span> set to true<\/strong><\/span>. Optionally you can add SaleToAcquirerData<\/code> parameters to pre-authorize or tokenize the transactions, as a method to handle authorization expiry and late captures<\/a>.<\/p>\nSaleToAcquirerData<\/code> value:<\/p>\n\n
\n
POITransactionID.TransactionID<\/code>: save the transaction ID. This is provided in the format tenderReference.pspReference<\/code>, for example, CW1r112876209163113.DXCD52AY3WUGXS93<\/strong>. The PSP reference is also provided in the AdditionalResponse<\/code>.
\nYou need the PSP reference later, to extend or adjust the authorization, and to capture the payment. You also need the PSP reference if the shopper returns items to the warehouse.
\nYou need the full transaction ID if the shopper returns items to the store.<\/p>\n<\/li>\nAdditionalResponse<\/code>:<\/p>\n\n
adjustAuthorisationData<\/code>. You need this data blob later, to extend or adjust the authorization.<\/p>\n<\/li>\nrecurring.recurringDetailReference<\/code> or tokenization.storedPaymenMethodId<\/code>) and the shopper reference (recurring.shopperReference<\/code> or tokenization.shopperReferece<\/code>).<\/p>\n<\/li>\n<\/ul>\n<\/li>\nPOITransactionID.TimeStamp<\/code>: save the payment date and time. You need the timestamp if the shopper returns items to the store.<\/p>\n<\/li>\n<\/ul>\n
\nIf your point-of-sale merchant account uses immediate or delayed capture by default (which we usually recommend), do not set manual capture in this payment request. Otherwise, see the example<\/a>under \"In-store pickup\", and make a separate manual capture request for the in-store items.<\/p>\n<\/li>\n<\/ol>\nAuthorization extension (optional)<\/h4>\n
\n
\nAuthorization adjustment<\/a><\/p>\n\nIn-store pickup<\/h4>\n
\n
\n
CardAcquisitionTransaction<\/code> object.
\nresponse.AdditionalResponse<\/code>:<\/p>\n\n
PaymentAccountReference<\/code>: the PAR, if present.<\/li>\nalias<\/code>: the card alias<\/li>\n<\/ul>\nAdditionalResponse<\/code> as a string of key-value pairs concatenated with an ampersand (&<\/strong>). It is possible you receive a Base64-encoded string instead, which you need to Base64 decode first.<\/p>\n
\nConsider including a DisplayOutput<\/code> object with an explanatory message for the shopper, as shown in the following example.
\n
\n<\/a>
\nSend a POST request to the \/payments\/{paymentPspReference}\/captures<\/a> endpoint, where paymentPspReference<\/code> is the PSP reference from the (pre-)authorization response.
<\/p>\n
![\"Required\"](\"\/user\/pages\/reuse\/image-library\/01.icons\/required\/required.svg?decoding=auto&fetchpriority=auto\")
<\/span><\/td>\n