Search

Are you looking for test card numbers?

Would you like to contact support?

Card acquisition

Learn how to retrieve shopper details from the Adyen payments platform.

Card acquisition allows you to retrieve shopper details before creating a payment request. You would use this for example in an omnichannel solution, to look up shopping history, to perform an eligibility check for tax-free shopping, or to give loyal customers a discount based on their card number.

For chip transactions, do not remove the card from the terminal until it has completed acquiring card details.

When you acquire card details before making a payment request, you can specify an amount. If it is the same as the amount in the payment request, a shopper using a contactless card needs to tap their card only once. Otherwise, they will need to tap their card twice: once for the card details and again for the payment.

To acquire and use shopper details:

  1. Make a CardAcquisition request.
  2. Get the response and note the POIData.POITransaction.TransactiondID
  3. Make a payment, specifying a TransactionID with the value of 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.

When you have acquired the card and shopper details, you can either:

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.

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.

Without amount

 {
   "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":{

         }
      }
   }
}

With amount

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"CardAcquisition",
         "MessageType":"Request",
         "ServiceID":"0612120526",
         "SaleID":"CashRegB3",
         "POIID":"V400m-324689783"
      },
      "CardAcquisitionRequest":{
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"TID-2018-08-01-16:43:01",
               "TimeStamp":"2018-08-01T16:43:01"
            },
            "TokenRequestedType":"Customer"
         },
         "CardAcquisitionTransaction":{
            "TotalAmount":10
         }
      }
   }
}

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:

{
   "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=YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j&shopperEmail=big%40spender.com"
         }
      },
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "SaleID":"CashRegB3",
         "MessageClass":"Service",
         "MessageCategory":"CardAcquisition",
         "ServiceID":"0612120525",
         "POIID":"P400Plus-275008565",
         "MessageType":"Response"
      }
   }
}

Continue with payment

After making a Card Acquisition request, continue with a payment request using the POIData.POITransaction.TransactionID 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"
            }
         }
      }
   }
}

Cancel card acquisition

Card acquisition allows you to retrieve shopper details before creating a payment request. You may want to cancel this request if you do not require CardAcquisition, for example, if the retrieved cardData does not qualify for a transaction.

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.

EnableService Request

For a list of EnableServiceRequest fields, see EnableServiceRequest fields. The elements of the request are wrapped in a EnableServiceRequest 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 EnableServiceRequest call to the Terminal API.

 {
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"EnableService",
         "MessageType":"Request",
         "ServiceID":"$ServiceID",
         "SaleID":"$SaleID",
         "POIID":"$POIID"
      },
      "EnableServiceRequest":{
         "TransactionAction":"AbortTransaction",
         "DisplayOutput":{
            "Device":"CustomerDisplay",
            "InfoQualify":"Display",
            "OutputContent":{
               "PredefinedContent":{
                  "ReferenceID":"CustomAnimated"
               },
               "OutputFormat":"Text",
               "OutputText":[
                  {
                     "Text":"MESSAGE TITLE"
                  },
                  {
                     "Text":"MESSAGE BODY"
                  }
               ]
            }
         }
      }
   }
}

EnableService Response

For a list of EnableServiceResponse fields, see EnableServiceResponse fields.

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

{
   "SaleToPOIResponse":{
      "EnableServiceResponse":{
         "Response":{
            "Result":"Success"
         }
      },
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "SaleID":"Demo",
         "MessageClass":"Service",
         "MessageCategory":"EnableService",
         "ServiceID":"130822ec5",
         "POIID":"V400cPlus-401484835",
         "MessageType":"Response"
      }
   }
}