Terminal-2 icon

Card acquisition

Check the card and cardholder details before or outside of a payment.

With a Terminal API CardAcquisition request, you can obtain card and shopper identifiers before making a payment, or outside of a payment flow.

This enables you to answer questions like:

  • What type of 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.

How it works

The basic card acquisition flow is as follows.

  1. You make a 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:

Customer experience

For the customer, card acquisition followed by a payment is a single flow that is the same as a regular payment.

However, if the customer tapped their card for the card acquisition, they need to tap their card again for the payment in either of these cases:

  • The card acquisition didn't include an amount.
  • The card acquisition and payment amounts are different.

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: 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: 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: 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: 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, 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.

Requirements

Be aware of the following limitation:

QR code wallet details cannot be obtained through card acquisition.

Make a card acquisition request

  1. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- CardAcquisition
      MessageType -white_check_mark- Request
      ServiceID -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- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • CardAcquisitionRequest : The request body with:

      Parameter Required Description
      SaleData.SaleTransactionID -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.
      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- 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.

  2. When the card acquisition succeeds, you receive a CardAcquisitionResponse with a message of CARD_ACQ_COMPLETED in the AdditionalResponse.

  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.
    • 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.

    As an example, the AdditionalResponse from the CardAcquisitionResponse 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

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 POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -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- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • PaymentRequest: The request body with:

      Parameter Required Description
      SaleData.SaleTransactionID -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.
      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 -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: the final transaction amount.
      PaymentData.CardAcquisitionReference -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.

  2. 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.

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 POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- EnableService
      MessageType -white_check_mark- Request
      ServiceID -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- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • EnableServiceRequest: The request body with:

      Parameter Required Description
      TransactionAction -white_check_mark- 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.

    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- CustomerDisplay
    InfoQualify -white_check_mark- Display
    OutputContent.PredefinedContent.ReferenceID -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- Text
    OutputContent.OutputText -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-, and We logged your arrival time.

  2. When the cancellation succeeds, you receive an EnableServiceResponse that contains:

    • Response.Result: Success

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 AbortRequest from your POS system:

  1. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Abort
      MessageType -white_check_mark- Request
      ServiceID -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- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • AbortRequest: The request body with:

      Parameter Required Description
      AbortReason -white_check_mark- MerchantAbort
      MessageReference -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.

    For more details see the AbortRequest API reference.

    The example below shows a request to cancel an in-progress card acquisition with a ServiceID of 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.

See also

Card acquisition scenarios:

Other resources: