--- title: "Card acquisition" description: "Check the card and cardholder details before or outside of a payment." url: "https://docs.adyen.com/point-of-sale/card-acquisition" source_url: "https://docs.adyen.com/point-of-sale/card-acquisition.md" canonical: "https://docs.adyen.com/point-of-sale/card-acquisition" last_modified: "2023-02-23T11:26:00+01:00" language: "en" --- # Card acquisition Check the card and cardholder details before or outside of a payment. [View source](/point-of-sale/card-acquisition.md) With a Terminal API card acquisition request, you can obtain [card and shopper identifiers](/point-of-sale/card-acquisition/identifiers) before making a payment, or outside of a payment flow. This enables you to answer questions like: * What payment instrument is the customer using? * Who is the customer? * What country/region does the shopper come from? * What are the card details? Based on the answer, you decide what to do next. For example, make a Terminal API payment request with specific parameters, or use the acquired details in another system. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | A [Terminal API integration](/point-of-sale/basic-tapi-integration/) with payment terminals. | | **Limitations** | QR code wallet details and one-time numeric code details cannot be obtained through card acquisition. | | **Setup steps** | Before you begin:- Set up [receiving identifiers in Terminal API responses](/point-of-sale/card-acquisition/identifiers#receiving-identifiers-in-responses). - Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable **single tap**, for a better [customer experience](#customer-experience) with contactless transactions. | ## How it works The basic card acquisition flow is as follows. 1. You [make a card acquisition request](#card-acquisition-request). 2. On the terminal, the customer taps, inserts, or swipes their card or other payment instrument. 3. You process the acquired card data from the response in your own systems, depending on what you want to achieve.\ The terminal shows *One moment*, or *Keep card inserted* if the customer inserted their card into the card reader. 4. You finish the card acquisition in one of the following ways: * [Finish with a payment](#continue-with-payment). This tells the terminal it needs to use the acquired data for the payment. * [Finish with a cancellation](#cancel-completed). This tells the terminal it no longer needs to keep the acquired data. ### Customer experience For the customer, card acquisition followed by a payment is a single flow that is the same as a regular payment. But with contactless payments, if the customer tapped their card for the card acquisition, they need to tap their card again for the payment in these cases: * The card acquisition did not include an amount. * The card acquisition and payment amounts are different. To avoid the second tap, you can ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable **single tap**. ## Scenarios Card acquisition is a step in many advanced payment flows and other use cases. For example: * *Autonomous stores*: the shopper presents their card to gain access to the autonomous store. You use card acquisition to pre-authorize a default amount without showing that amount to the shopper, and then provide access. When the shopper leaves, you adjust the pre-authorization for the products that the shopper took, and capture the payment. * *Card recognition use cases*: * [Card-based customer identification](/point-of-sale/shopper-recognition/identification): For example, in a parking garage. Upon arrival, you identify the driver and record their time of arrival based on a card acquisition. Then you cancel the card acquisition. Upon departure, you identify the driver again through card acquisition, calculate the amount due, and make a payment for the calculated amount. * [Card check before refund](/point-of-sale/shopper-recognition/before-refund): Before issuing an unreferenced refund, you use card acquisition to verify if the shopper is using the same card for the refund as for the initial payment. * *Gift card usage*: You use card acquisition to check if the shopper is using a gift card. If you do not want to accept the gift card for this transaction, you cancel the card acquisition and ask for a different card. Or if you want to stimulate usage of your gift card, you give extra discounts in the payment following the card acquisition. * [Tax-free shopping](/point-of-sale/shopper-recognition/tax-free-shopping): You use the issuer country/region and the card BIN returned in the card acquisition response to determine whether the transaction qualifies for a tax refund. Then you make a payment request. * [Loyalty](/point-of-sale/loyalty): Based on the card acquisition, you look up the shopper in your loyalty program. You can then interact with the shopper on the terminal, through input requests. For example, if the shopper isn't recognized, you ask them to enroll in your loyalty program. Or if the shopper is recognized, you ask whether they want to redeem loyalty points. To finish, you make a payment request for the final transaction amount. * In loyalty flows based on [wallet passes](/point-of-sale/loyalty/wallet-passes), the card acquisition response tells you if the shopper has your NFC-enabled wallet pass in their mobile NFC wallet app. If they do not, you can issue a pass and add this data to your payment request so the shopper gets notified. Or if they do, you can use the pass for the payment. ## Make a card acquisition request 1. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) card acquisition request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **CardAcquisition**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **CardAcquisition** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [CardAcquisitionRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/cardacquisition) object with: | Parameter | Required | Description | | ----------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleData.TokenRequestedType` | | **Customer**. Returns the card alias in the `TokenValue` field of the response. Note that the card alias is always returned in the `AdditionalResponse`. | | `CardAcquisitionTransaction` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A required object that can be empty or contain:- `TotalAmount` (optional): the transaction amount. When you do not know the amount yet, you can omit this parameter or specify an initial amount and provide the final amount later, in the payment request. - `PaymentType` (optional): if you intend to continue with a payment, either omit this parameter or specify **Normal**. If you intend to continue with an unreferenced refund, see [Card check before refund](/point-of-sale/shopper-recognition/before-refund). | #### JSON ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"CardAcquisition", "MessageType":"Request", "ServiceID":"282", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" }, "CardAcquisitionRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"369", "TimeStamp":"2021-03-05T12:22:57.449Z" }, "{hint:Optional, returns the card alias in TokenValue}TokenRequestedType{/hint}":"Customer" }, "CardAcquisitionTransaction":{ "{hint:Optional}TotalAmount{/hint}":16.98 } } } } ``` #### Java ```java String serviceID = "YOUR_UNIQUE_ATTEMPT_ID"; String saleID = "YOUR_CASH_REGISTER_ID"; String POIID = "YOUR_TERMINAL_ID"; String transactionID = "YOUR_UNIQUE_TRANSACTION_ID"; SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest(); MessageHeader messageHeader = new MessageHeader(); messageHeader.setProtocolVersion("3.0"); messageHeader.setMessageClass( MessageClassType.SERVICE ); messageHeader.setMessageCategory( MessageCategoryType.CARD_ACQUISITION ); messageHeader.setMessageType( MessageType.REQUEST ); messageHeader.setServiceID(serviceID); messageHeader.setSaleID(saleID); messageHeader.setPOIID(POIID); saleToPOIRequest.setMessageHeader(messageHeader); CardAcquisitionRequest cardAcquisitionRequest = new CardAcquisitionRequest(); SaleData saleData = new SaleData(); TransactionIdentification saleTransactionID = new TransactionIdentification(); saleTransactionID.setTransactionID(transactionID); saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar())); saleData.setSaleTransactionID(saleTransactionID); saleData.setTokenRequestedType( TokenRequestedType.CUSTOMER ); cardAcquisitionRequest.setSaleData(saleData); CardAcquisitionTransaction cardAcquisitionTransaction = new CardAcquisitionTransaction(); cardAcquisitionTransaction.setTotalAmount( BigDecimal.valueOf(16.98) ); cardAcquisitionRequest.setCardAcquisitionTransaction(cardAcquisitionTransaction); saleToPOIRequest.setCardAcquisitionRequest(cardAcquisitionRequest); terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest); ``` 2. When the card acquisition succeeds, you receive a [CardAcquisitionResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/cardacquisition#responses-200-Response) with a `message` of **CARD\_ACQ\_COMPLETED** in the `AdditionalResponse`. **Card acquisition response** ```json { "SaleToPOIResponse": { "CardAcquisitionResponse": { "POIData": { "POITransactionID": { "{hint:For use in subsequent payment}TimeStamp{/hint}": "2021-03-05T12:22:59.000Z", "{hint:For use in subsequent payment}TransactionID{/hint}": "8ha5001614946979000" }, "SaleData": {...} }, "PaymentInstrumentData": { "CardData": { "{hint:Included if you enabled receiving the issuer country}CardCountryCode{/hint}": "528", "MaskedPan": "541333 **** 9999", "PaymentBrand": "mc", "PaymentToken": { "TokenRequestedType": "Customer", "TokenValue": "{hint:This is the card alias}M469509594859802{/hint}" }, "SensitiveCardData": { "ExpiryDate": "0228" } }, "PaymentInstrumentType": "Card" }, "Response": { "AdditionalResponse": "tid=46403161&transactionType=GOODS_SERVICES&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=1698&expiryYear=2028&alias=M469509594859802&posAmountGratuityValue=0&giftcardIndicator=false&paymentMethodVariant=mc&txtime=13%3a22%3a59&iso8601TxDate=2021-03-05T12%3a22%3a59.0000000%2b0000&cardType=mc&posOriginalAmountValue=1698&aliasType=Default&txdate=05-03-2021&paymentMethod=mc&merchantReference=369&expiryMonth=02&cardSummary=9999&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&message=CARD_ACQ_COMPLETED&cardIssuerCountryId=528&posAmountCashbackValue=0&posEntryMode=CLESS_CHIP&fundingSource=CREDIT&issuerCountry=NL&cardScheme=mc&cardBin=541333&posAuthAmountValue=1698", "Result": "Success" } }, "MessageHeader": {...} } } ``` 3. From the `CardAcquisitionResponse`, get the details that you need for your use case. | Parameter | Usage | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `POIData.POITransactionID` | If you are going to continue with a payment, keep the `TimeStamp` and `TransactionID`, because you need these card acquisition details in your payment request. | | `PaymentInstrumentData.CardData` | Includes:- `CardCountryCode`: The three-digit code of the issuer country/region. This parameter is included if you [enabled receiving the issuer country/region](/point-of-sale/card-acquisition/identifiers). - `PaymentToken.TokenValue`: The card alias. You can use this to identify the shopper based on their card, but not to make payments. This parameter is included if you specified a `TokenRequestedType` of **Customer** in the request. | | `Response.AdditionalResponse` | Transaction data that you may need in your use case. You receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. Data that you may need:- `alias`: The card alias, to identify the shopper based on their card. - `PaymentAccountReference`: If the shopper used an NFC wallet, you can use this instead of the `alias`. (Not present for card payments.) - `cardBin` and `issuerCountry`: Data to determine eligibility for tax free shopping. - `shopperReference` and `shopperEmail`: For use in loyalty use cases. - `giftcardIndicator`: If **true**, indicates the shopper presented a gift card. | If the `AdditionalResponse` doesn't include the expected details, you may need to enable receiving those details. Refer to [Receive identifiers](/point-of-sale/card-acquisition/identifiers#receiving-identifiers-in-responses). As an example, the `AdditionalResponse` from the `CardAcquisitionResponse` above contains: ```raw tid=46403161 transactionType=GOODS_SERVICES backendGiftcardIndicator=false posadditionalamounts.originalAmountValue=1698 expiryYear=2028 alias=M469509594859802 posAmountGratuityValue=0 giftcardIndicator=false paymentMethodVariant=mc txtime=13%3a22%3a59 iso8601TxDate=2021-03-05T12%3a22%3a59.0000000%2b0000 cardType=mc posOriginalAmountValue=1698 aliasType=Default txdate=05-03-2021 paymentMethod=mc merchantReference=369 expiryMonth=02 cardSummary=9999 posadditionalamounts.originalAmountCurrency=EUR posAuthAmountCurrency=EUR message=CARD_ACQ_COMPLETED cardIssuerCountryId=528 posAmountCashbackValue=0 posEntryMode=CLESS_CHIP fundingSource=CREDIT issuerCountry=NL cardScheme=mc cardBin=541333 posAuthAmountValue=1698 ``` ## Finish with a payment Depending on your use case, you may want to complete the card acquisition flow with a payment. To do so, the payment request must include a reference to the card acquisition. 1. [Make a payment request](/point-of-sale/basic-tapi-integration/make-a-payment), specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [PaymentRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment) object with: | Parameter | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `TransactionID`: Your reference to identify a payment. We recommend using a unique value per payment. - `TimeStamp`: The date and time of the request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleData.SaleToAcquirerData` | | Depending on your use case, you may need to provide [tender options](/point-of-sale/add-data/tender-options) or [additional data](/point-of-sale/add-data) here, or a [flag for tax free shopping](/point-of-sale/shopper-recognition/tax-free-shopping). | | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: The transaction [currency](/development-resources/currency-codes). - `RequestedAmount`: The final transaction amount. | | `PaymentData.CardAcquisitionReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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. | Here is how you make a payment referring to a card acquisition that had a `TimeStamp` of **2021-03-05T12:22:59.000Z** and a `TransactionID` of **8ha5001614946979000**. #### JSON ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "SaleID":"POSSystemID12345", "ServiceID":"2020711110", "POIID":"V400m-346403161" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"899", "TimeStamp":"2021-03-05T12:23:44.684Z" } }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":16.98 } }, "PaymentData":{ "CardAcquisitionReference":{ "{hint:From the POITransactionID of the card acquisition}TimeStamp{/hint}":"2021-03-05T12:22:59.000Z", "{hint:From the POITransactionID of the card acquisition}TransactionID{/hint}":"8ha5001614946979000" } } } } } ``` #### Java ```java String serviceID = "YOUR_UNIQUE_ATTEMPT_ID"; String saleID = "YOUR_CASH_REGISTER_ID"; String POIID = "YOUR_TERMINAL_ID"; String transactionID = "YOUR_UNIQUE_TRANSACTION_ID"; SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest(); MessageHeader messageHeader = new MessageHeader(); messageHeader.setProtocolVersion("3.0"); messageHeader.setMessageClass( MessageClassType.SERVICE ); messageHeader.setMessageCategory( MessageCategoryType.PAYMENT ); messageHeader.setMessageType( MessageType.REQUEST ); messageHeader.setServiceID(serviceID); messageHeader.setSaleID(saleID); messageHeader.setPOIID(POIID); saleToPOIRequest.setMessageHeader(messageHeader); PaymentRequest paymentRequest = new PaymentRequest(); SaleData saleData = new SaleData(); TransactionIdentification saleTransactionID = new TransactionIdentification(); saleTransactionID.setTransactionID(transactionID); saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar())); saleData.setSaleTransactionID(saleTransactionID); paymentRequest.setSaleData(saleData); PaymentTransaction paymentTransaction = new PaymentTransaction(); AmountsReq amountsReq = new AmountsReq(); amountsReq.setCurrency("EUR"); amountsReq.setRequestedAmount( BigDecimal.valueOf(16.98) ); paymentTransaction.setAmountsReq(amountsReq); paymentRequest.setPaymentTransaction(paymentTransaction); PaymentData paymentData = new PaymentData(); TransactionIdentification cardAcquisitionReference = new TransactionIdentification(); cardAcquisitionReference.setTransactionID(transactionID); cardAcquisitionReference.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar())); paymentData.setCardAcquisitionReference(cardAcquisitionReference); paymentRequest.setPaymentData(paymentData); saleToPOIRequest.setPaymentRequest(paymentRequest); terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest); ``` 2. In the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200) note the following: * `PaymentInstrumentData.CardData`: The same card details that you received in the card acquisition response. * `Response.AdditionalResponse`: Transaction data, including the same details that you received in the card acquisition response. You receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. **Payment response** ```json { "SaleToPOIResponse":{ "PaymentResponse":{ "POIData":{ "POIReconciliationID":"1000", "POITransactionID":{ "TimeStamp":"2021-03-05T12:23:00.000Z", "TransactionID":"8ha5001614946979000.NC6HT9CRT65ZGN82" }, "SaleData":{ "..." }, "PaymentReceipt":[ "..." ], "PaymentResult":{ "AmountsResp":{ "AuthorizedAmount":16.98, "Currency":"EUR" }, "PaymentInstrumentData":{ "CardData":{ "CardCountryCode":"826", "EntryMode":[ "Contactless" ], "MaskedPan":"541333 **** 9999", "PaymentBrand":"mc", "SensitiveCardData":{ "CardSeqNumb":"33", "ExpiryDate":"0228" } }, "PaymentInstrumentType":"Card" } }, "Response":{ "AdditionalResponse":"tid=46403161&AID=A000000004101001&transactionType=GOODS_SERVICES&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=1698&expiryYear=2028&alias=M469509594859802&posAmountGratuityValue=0&giftcardIndicator=false&pspReference=NC6HT9CRT65ZGN82&paymentMethodVariant=mc&batteryLevel=100%25&applicationPreferredName=mc%20en%20gbr%20gbp&store=StoreOne&txtime=13%3a23%3a46&iso8601TxDate=2021-03-05T12%3a23%3a46.0000000%2b0000&cardType=mc&posOriginalAmountValue=1698&offline=false&aliasType=Default&txdate=05-03-2021&paymentMethod=mc&startYear=2017&tc=FA13E605EE521667&cardIssueNumber=33&mid=1000&merchantReference=899&transactionReferenceNumber=NC6HT9CRT65ZGN82&expiryMonth=02&cardSummary=9999&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&cardHolderVerificationMethodResults=1F0302&cardIssuerCountryId=826&adjustAuthorisationData=BQABAQAMGo8BEaAMaNcBTGTHMTvXOdf7UbVZeYkBUCArY2Kem%2fu4oaTz4nBLiHBOBxsHvhGkdMy6qPnoJPWQAu2qgn9VDfHqaLvszJ9niBI7%2bCcW1n7mc7WyUXqI%2bXddD4iH5SQzeydVNs72fqjoBDm7TFnYy6FyVMQcROqWdTdOqbInN7e279CYf3Bg4XlRUdtWgkGwQEn%2bmmCPljvpqNY1HhWae61CKujEIpJl%2bOHvKSdQ0EUPjhABf12Knyo74XorVCUKS2eCg44lodVmz%2bXiQMgeTwnpAYOniVrOmuks5UFim0OM9NzuzYG1J3s76UMuIk43U4V0wQgdgrH%2fJMzmW61gEK42LACWgN%2fNLjLEa360kI0AAD%2fLAxXIzw9f11GbftqiweIehsMmoYRHqPO5CQseMVtRrE7zCV2FQSDYwGIH9MUKh%2fyiGYpB34tlRYT3GLOOK3Bp3GQfHSaChyTQEXHpvwR8Wd1rEWQDTIsLQawvK3W05uQZpSU%2bXbzoJy3txW0f2nlo91j%2fVRQR%2fBkQhiqT05uVHBldzQA%2bamjAcsHlRjJKgsGFIA4hKdeHIk6s5W3kfidbXMJDtue54gnKGXN1yvoblE5NLmQXBAHKx2eFvYxufLvB3om6AJD5ISc4XQLqE1vY3J%2bh%2bViBvsLRERSB3tij7fd3G%2bH5WtE6L%2b1dzs1MpZgSEWGVAfshmZ456jBlTJ2kFL%2bmE%2fHb462q1wFeXKIo8Llhi1tx%2b%2b0is7Z34%2bFuAMxSioaPUsle3Y9a%2b2J1ZhribRKBcZlSUlWiuXmlo%2fUSmeERC%2fiztpYs3%2fjdlbdO6Mkq3GlphRIQFwcR8fDvlygb&posAmountCashbackValue=0&posEntryMode=CLESS_CHIP&startMonth=01&fundingSource=CREDIT&issuerCountry=GB&cardScheme=mc&cardBin=541333&posAuthAmountValue=1698", "Result":"Success" } }, "MessageHeader":{ "..." } } } } ``` ## Finish with a cancellation Depending on your use case, you may want to stop the card acquisition flow after you have received the response. For this, you make an `EnableServiceRequest` to abort the transaction. The terminal then discards the acquired card data. 1. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) enable service request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **EnableService**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **EnableService** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [EnableServiceRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/enableservice) object with: | Parameter | Required | Description | | ------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `TransactionAction` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **AbortTransaction**. | | `DisplayOutput` | | [Optional object](#alternative) to show your own message and an 'Approved' icon (green check mark) or a 'Declined' icon (red cross). | The next example is the basic request, without `DisplayOutput` object, to end the card acquisition flow with a cancellation. The terminal will show *Canceled*, a red cross **![](/images/e/b/5/8/6/eb5864c171bd3eac47d4a415a1f7e5dc0b075c28-cancel2x.png)**, and *Transaction canceled*. **Basic request to cancel the card acquisition data** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"EnableService", "MessageType":"Request", "ServiceID":"3020711110", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" }, "EnableServiceRequest":{ "TransactionAction":"AbortTransaction" } } } ``` #### Show your own message To show your own message when ending the card acquisition with a cancellation, extend your `EnableServiceRequest` with a `DisplayOutput` object containing: | Parameter | Required | Description | | --------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Device` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **CustomerDisplay** | | `InfoQualify` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Display** | | `OutputContent.PredefinedContent.ReferenceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Icon to show:- **Accepted**: green check mark. - **AcceptedAnimated**: animated green check mark. - **Declined**: red cross. - **DeclinedAnimated**: animated red cross. - **Idle**: no icon.. | | `OutputContent.OutputFormat` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Text** | | `OutputContent.OutputText` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An array with one or two `Text` objects containing header and footer text. Provide empty values if you do not want to show text. | The following example will show *Welcome!*, an animated green check mark ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-"), and *We logged your arrival time*. **Cancellation using a custom message** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"EnableService", "MessageType":"Request", "ServiceID":"3020711110", "SaleID":"POSSystemID12345", "POIID":"V400m-346403161" }, "EnableServiceRequest":{ "TransactionAction":"AbortTransaction", "DisplayOutput":{ "Device":"CustomerDisplay", "InfoQualify":"Display", "OutputContent":{ "PredefinedContent":{ "ReferenceID":"AcceptedAnimated" }, "OutputFormat":"Text", "OutputText":[ { "Text":"Welcome!" }, { "Text":"We logged your arrival time" } ] } } } } } ``` 2. When the cancellation succeeds, you receive an [EnableServiceResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/enableservice#responses-200-Response) that contains: * `Response.Result`: **Success** **Response for canceling the card acquisition data** ```json { "SaleToPOIResponse":{ "EnableServiceResponse":{ "Response":{ "Result":"Success" } }, "MessageHeader":{ "ProtocolVersion":"3.0", "SaleID":"POSSystemID12345", "MessageClass":"Service", "MessageCategory":"EnableService", "ServiceID":"3020711110", "POIID":"V400m-346403161", "MessageType":"Response" } } } ``` If you try to make a payment with a `CardAcquisitionReference` referring to the completed card acquisition that you cancelled, the payment will fail with a message *Validation failed: No prior card acquisition data available*. ## Stop an in-progress card acquisition If necessary, you can cancel a card acquisition before you receive a response, while the terminal is prompting the shopper to present their card. To do this, send an abort request from your POS system. 1. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) abort request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Abort**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Abort** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [AbortRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/abort) object with: | Parameter | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AbortReason` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **MerchantAbort** | | `MessageReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `MessageCategory`: **CardAcquisition** - `SaleID`: Your unique ID of the POS system component that made the card acquisition request. - `ServiceID`: The `ServiceID` of the card acquisition request being cancelled. | The example shows a request to cancel an in-progress card acquisition with a `ServiceID` of **21796**. **Abort an in-progress card acquisition request** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Abort", "MessageType":"Request", "SaleID":"POSSystemID12345", "ServiceID":"29239", "POIID":"V400m-324688179" }, "AbortRequest":{ "AbortReason":"MerchantAbort", "MessageReference":{ "MessageCategory":"CardAcquisition", "SaleID":"POSSystemID12345", "ServiceID":"21796" } } } } ``` A successful `AbortRequest` returns a response with a 200 OK HTTP status code and no body. 2. Check whether the cancellation succeeded: * The *Present card* prompt generated by your `CardAcquisitionRequest` disappears from the terminal display. * You receive a `CardAcquisitionResponse` containing: * `Result`: **Failure** * `ErrorCondition`: **Aborted** The following example shows the response for a card acquisition that was cancelled before it was completed. **CardAcquisitionResponse after canceling before completion** ```json { "SaleToPOIResponse": { "CardAcquisitionResponse": { "POIData": { "POITransactionID": { "TimeStamp": "2020-11-04T18:44:11.000Z", "TransactionID": "8ha5001604515451028" }, "POIReconciliationID": "1000" }, "SaleData": { "SaleTransactionID": { "TimeStamp": "2020-11-04T18:44:11.022Z", "TransactionID": "152" } }, "Response": { "Result": "Failure", "AdditionalResponse": "refusalReason=104%20Merchant%20cancelled%20tx...", "ErrorCondition": "Aborted" } }, "MessageHeader": { "ProtocolVersion": "3.0", "SaleID": "POSSystemID12345", "MessageClass": "Service", "MessageCategory": "CardAcquisition", "ServiceID": "21796", "POIID": "V400m-346403161", "MessageType": "Response" } } } ``` ## See also **Card acquisition scenarios**: * [Card-based customer identification](/point-of-sale/shopper-recognition/identification) * [Card check before refund](/point-of-sale/shopper-recognition/before-refund) * [Tax-free shopping](/point-of-sale/shopper-recognition/tax-free-shopping) * [Shopper loyalty](/point-of-sale/loyalty) * [Wallet passes](/point-of-sale/loyalty/wallet-passes) **Other resources**: * [Receive card and shopper identifiers](/point-of-sale/card-acquisition/identifiers)