Card acquisition lets you retrieve card and shopper identifiers without making a payment. With these identifiers you can recognize the card used, and even the individual who is using the card. Although you can get these same identifiers through a payment request, there are use cases where this data is needed outside of a payment, or before a payment.
The card acquisition flow finishes either with a follow-up payment request, or with a cancellation after having received the card acquisition response. The cancellation tells the payment terminal it no longer needs to keep the acquired data.
Scenarios
To understand how you can apply card acquisition, have a look at some use cases:
-
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.
-
Gift card usage: you use card acquisition to check whether the shopper is using a gift card. If you don't 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: you use the issuer country 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.
-
Card-based shopper 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 identification before refunding: before issuing an unreferenced refund, you use card acquisition to verify whether the shopper is using the same card for the refund as for the initial payment.
For more information about these use cases, follow the links above.
How it works
Card acquisition triggers interaction with the shopper on the payment terminal. Here is how it works:
-
You make a card acquisition request. Optionally this includes the payable amount.
-
The terminal prompts the shopper to present their card by tapping, inserting into the card reader, or swiping.
Note that:- QR code wallet details can't be obtained through card acquisition, so the scan QR code button isn't shown.
- The shopper can present a credit or debit card, or a gift card.
-
If the card acquisition request includes an amount, the terminal shows the amount. Otherwise, the terminal shows the prompt to present a card.
-
The shopper presents their card and you receive the card acquisition response. From the response you take certain data and process these in your own systems, depending on your use case.
-
While this is going on, the terminal continually shows One moment. Or, if the shopper inserted their card into the card reader, the terminal shows Keep card inserted.
-
Depending on your use case, you may want to communicate with the shopper through input requests.
After such a request is completed, the terminal reverts to showing One moment, or Keep card inserted. The terminal is still holding the card acquisition details while it waits for you to finish the flow. - To finish the flow, you either continue with a payment request, or continue with a cancellation.
When you continue with a payment:
- The payment request must include a reference to the card acquisition. Otherwise, the payment request will fail because the terminal is waiting to use the acquired card details.
- The terminal shows the amount due.
- If the shopper inserted or swiped their card for the card acquisition, the terminal now asks them for their PIN or signature.
-
If the shopper tapped their card for the card acquisition and the payment amount is below the contactless CVM limit, the shopper doesn't need to tap their card again. But if the card acquisition had no amount or if the card acquisition and payment amounts are different, the shopper does need to tap their card again.
Make a card acquisition request
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: the standardSaleToPOIRequest.MessageHeader
object. This includes:Parameter Required Description MessageClass
Service MessageCategory
CardAcquisition
-
CardAcquisitionRequest
: The request body with:Parameter Required Description SaleData.SaleTransactionID
An object with: TransactionID
: your unique reference for this request.TimeStamp
: date and time of the request in UTC format.
SaleData.TokenRequestedType
Customer. Returns the card alias in the TokenValue
field of the response. Note that the card alias is always returned in theAdditionalResponse
.CardAcquisitionTransaction
This object is either empty, or contains: TotalAmount
: the transaction amount. You can omitTotalAmount
when you don't know the amount yet. Or you can also change the transaction amount later, in the payment request.PaymentType
: 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 refunding.
{ "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":"Customer{/hint}" }, "CardAcquisitionTransaction":{ "{hint:Optional}TotalAmount{/hint}":16.98 } } } }
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);
-
-
When the card acquisition succeeds, you receive a
CardAcquisitionResponse
with amessage
of CARD_ACQ_COMPLETED in theAdditionalResponse
.{ "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": {...} } }
-
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
andTransactionID
, because you need these card acquisition details in your payment request.PaymentInstrumentData.CardData
Includes: CardCountryCode
: the three-digit code of the issuer country. This parameter is included if you enabled receiving the issuer country.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 aTokenRequestedType
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 thealias
. (Not present for card payments.)cardBin
andissuerCountry
: data to determine eligibility for tax free shopping.shopperReference
andshopperEmail
: 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 Card and shopper identifiers.As an example, the
AdditionalResponse
from theCardAcquisitionResponse
above contains: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
Continue 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.
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: the standardSaleToPOIRequest.MessageHeader
object. This includes:Parameter Required Description MessageClass
Service MessageCategory
Payment
-
PaymentRequest
: The request body with:Parameter Required Description SaleData.SaleTransactionID
An object with: TransactionID
: your unique reference for this request.TimeStamp
: date and time of the request in UTC format.
SaleData.SaleToAcquirerData
Depending on your use case, you may need to provide tender options or additional data here, or a flag for tax free shopping. PaymentTransaction.AmountsReq
An object with: Currency
: the transaction currency.RequestedAmount
: the final transaction amount.
PaymentData.CardAcquisitionReference
An object referring to the card acquisition: TimeStamp
: The time stamp returned in thePOIData.POITransactionID
of the card acquisition response.TransactionID
: the transaction ID returned in thePOIData.POITransactionID
of the card acquisition response.
Here is how you would make a payment referring to a card acquisition that had a
TimeStamp
of 2021-03-05T12:22:59.000Z and aTransactionID
of 8ha5001614946979000.{ "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" } } } } }
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);
-
-
In the
PaymentResponse
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.
{ "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": {...} } }
Continue 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.
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: the standardSaleToPOIRequest.MessageHeader
object. This includes:Parameter Required Description MessageClass
Service MessageCategory
EnableService
-
EnableServiceRequest
: The request body with:Parameter Required Description TransactionAction
AbortTransaction. DisplayOutput
Optional object 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, and Transaction canceled.
{ "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 aDisplayOutput
object containing:Parameter Required Description Device
CustomerDisplay InfoQualify
Display OutputContent.PredefinedContent.ReferenceID
Icon to show: - Accepted: green check mark.
- AcceptedAnimated: animated green check mark.
- Declined: red cross.
- DeclinedAnimated: animated red cross.
- Idle: no icon.
OutputContent.OutputFormat
Text OutputContent.OutputText
An array with one or two Text
objects containing header and footer text. Provide empty values if you don't want to show text.The following example will show Welcome!, an animated green check mark
, and We logged your arrival time.
-
-
When the cancellation succeeds, you receive an
EnableServiceResponse
that contains:Response.Result
: Success
{ "SaleToPOIResponse":{ "EnableServiceResponse":{ "Response":{ "Result":"Success" } }, "MessageHeader":{ "ProtocolVersion":"3.0", "SaleID":"POSSystemID12345", "MessageClass":"Service", "MessageCategory":"EnableService", "ServiceID":"3020711110", "POIID":"V400m-346403161", "MessageType":"Response" } } }
For more details, see the EnableServiceRequest API reference and the EnableServiceResponse API reference.
Should 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.
Cancelling an in-progress card acquisition
By making an AbortRequest
from your cash register, you can cancel a card acquisition before you receive a response, while the terminal is prompting the shopper to present their card.
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: the standardSaleToPOIRequest.MessageHeader
object. This includes:Parameter Required Description MessageClass
Service MessageCategory
Abort
-
AbortRequest
: The request body with:Parameter Required Description AbortReason
MerchantAbort MessageReference
An object with: MessageCategory
: CardAcquisitionSaleID
: your unique ID of the cash register that made the payment request.ServiceID
: TheServiceID
of the card acquisition request being cancelled.
For more details see the AbortRequest API reference.
The example below shows how you would make a request to cancel an in-progress card acquisition with a
ServiceID
of 21796.{ "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. -
-
Check whether cancelling succeeded:
- The Present card prompt generated by your
CardAcquisitionRequest
disappears from the terminal display. - You receive a
CardAcquisitionResponse
containing:Result
: FailureErrorCondition
: Aborted
The following example shows the response for a card acquisition that was cancelled before it was completed.
{ "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" } } }
- The Present card prompt generated by your