Acquire card details

Card acquisition allows you to retrieve shopper details before creating a payment request, for example, to perform an eligibility check for tax-free shopping.

To acquire and use shopper details:

  1. Make a CardAcquisition request, get the response and note the POIData.POITransaction.TransactiondID

    The response contains shopper details if available. Currently only contact chip transactions are supported. The card should remain in the terminal after Card Acquisition has been completed to continue with the payment transaction.

  2. Request a payment with the POIData.POITransaction.TransactiondID noted above. The transaction is performed with the given card data, and will look like a regular payment. If a card acquisition reference is absent or incorrect, an error is reported.

Endpoint

The URL used to send  Terminal API  messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview .

CardAcquisition Request

For a list of CardAcquisitionRequest fields, see CardAcquisitionRequest fields. The elements of the request are wrapped in a CardAcquisitionRequest envelope.

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

Pass the following fields when making a CardAcquisitionRequest call to the Terminal API.

CardAcquisitionRequest
 {
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"CardAcquisition",
         "MessageType":"Request",
         "ServiceID":"0612120525",
         "SaleID":"CashRegB3",
         "POIID":"P400Plus-275008565"
      },
      "CardAcquisitionRequest":{
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"7881",
               "TimeStamp":"2018-06-12T10:05:25+00:00"
            }
         },
         "CardAcquisitionTransaction":{

         }
      }
   }
}

Card Acquisition Response

For a list of Card Acquisition Response fields, see CardAcquisitionResponse fields.

The response contains information about the status of the request in the following fields:

CardAcquisitionResponse
{
   "SaleToPOIResponse":{
      "CardAcquisitionResponse":{
         "POIData":{
            "POITransactionID":{
               "TimeStamp":"2018-06-12T10:05:35.000Z",
               "TransactionID":"oLkO001528797935000"
            }
         },
         "SaleData":{
            "SaleTransactionID":{
               "TimeStamp":"2018-06-12T10:05:25.000Z",
               "TransactionID":"7881"
            }
         },
         "PaymentInstrumentData":{
            "PaymentInstrumentType":"Card"
         },
         "Response":{
            "Result":"Success",
            "AdditionalResponse":"tid=12000000&transactionType=GOODS_SERVICES&shopperReference=Mr.%20Big%20Spender&shopperEmail=big%40spender.com"
         }
      },
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "SaleID":"CashRegB3",
         "MessageClass":"Service",
         "MessageCategory":"CardAcquisition",
         "ServiceID":"0612120525",
         "POIID":"P400Plus-275008565",
         "MessageType":"Response"
      }
   }
}

Next Steps

After making a Card Acquisition request, continue with a payment request using the POIData.POITransaction.TransactiondID returned in the card acquisition response. Here's an example of what that looks like:

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "ServiceID":"0612121120",
         "SaleID":"CashRegB3",
         "POIID":"P400Plus-275008565"
      },
      "PaymentRequest":{
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"15887",
               "TimeStamp":"2018-06-12T10:11:20+00:00"
            }
         },
         "PaymentTransaction":{
            "AmountsReq":{
               "Currency":"EUR",
               "RequestedAmount":10.99
            }
         },
         "PaymentData":{
            "CardAcquisitionReference":{
               "TransactionID":"oLkO001528797935000",
               "TimeStamp":"2018-06-12T10:05:35.000Z"
            }
         }
      }
   }
}

Cancelling a request

Cancelling a card acquisition request involves making an EnableService request. For more information, see Cancel card acquisition.