Card Acquisition

With a Terminal API card acquisition request, you can obtain card and customer identifiers before making a payment, or outside of a payment flow. The Card Acquisition operation is processed asynchronously. 

The basic card acquisition flow is as follows.

  1. POS triggers a card acquisition request.
  2. On the POI, customer taps, inserts, or swipes their card.
  3. POS processes the acquired card data from the response in your own systems, depending on what you want to achieve. The terminal displays a "processing in progress" state.
  4. POS finishes the card acquisition in one of the following ways:
    • with a payment, POI will use Acquired data to process transaction.
    • with an admin abort. This tells the terminal it no longer needs to keep the acquired data.

For the customer, card acquisition followed by a payment is as seamless asa standard payment.

 

1. Card Acquisition Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to CardAcquisition.

Body

To successfully initiate a CardAcquisitionRequest, the body must contain some key information related to SaleData and CardAcquisition. Do note CardAcquisitionTransaction is a required object which can be empty.

Component Object Required Type Description
SaleData.SaleTransactionID.TransactionID Yes Object

Unique ID generated by the POS for this acquisition event.
SaleData.SaleTransactionID.TimeStamp Yes Object

date and time of the request in UTC format.
CardAcquisitionTransaction.TotalAmount No String The total expected amount for the transaction.
CardAcquisitionTransaction.PaymentType No Enum if you intend to continue with a payment, either omit this parameter or specify Normal.
CardAcquisitionTransaction.TotalAmount No String  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.
AmountsReq.RequestedAmount No Object

Currency and requested amount details.
Card Acquisition Request example JSON
{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "CardAcquisition",
    "MessageType": "Request",
    "ServiceID": "9578",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "CardAcquisitionRequest": {
    "SaleData": {
      "SaleTransactionID": {
        "TransactionID": "123",
        "TimeStamp": "2025-11-28T14:14:42Z"
      }
    },
    "CardAcquisitionTransaction": {
      "TotalAmount": "12.34",
      "PaymentType": "Normal",

    },
    "AmountsReq": {
      "Currency": "EUR",
      "RequestedAmount": "12.34"
    }
  }
}

Review the full schema on the API specification page for required fields.

Card Acquisition Request example XML
<?xml version="3.1" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="CardAcquisition" MessageType="Request" ServiceID="3915" SaleID="ECR001" POIID="456"></MessageHeader>
	<CardAcquisitionRequest>
		<SaleData>
			<SaleTransactionID TransactionID="acq-3915" TimeStamp="2025-03-29T12:43:19Z"></SaleTransactionID>
		</SaleData>
		<CardAcquisitionTransaction></CardAcquisitionTransaction>
	</CardAcquisitionRequest>
</SaleToPOIRequest>

Review the full schema on the API specification page for required fields.

2. Intermediate Status

A card acquisition is running asynchronously, the Payment Terminal (POI) uses Display Request messages to inform the Point of Sale (POS) about the customer's required interaction or the current terminal state. The POS can interpret this information to update the customer display or cashier interface and then continue waiting for the final result. Refer to the Standard POS integration flow to manage it

3. Card Acquisition Response

The MessageHeader you receive in the response echoes the values you provided in the request. The only exception is the MessageType, which is Response.

From the CardAcquisitionResponse, get the details that you need for your use case:

Component Object Purpose for POS/Business
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.
LoyaltyAccount.LoyaltyAccountID

 LoyaltyID: ID of customer's loyalty

IdentificationSupport which allows to know where and how the loyalty account identification was done:

  • NoCard #The identification is not found on a card
  • LoyaltyCard #The identification is on a card dedicated to this loyalty brand.
  • HybridCard #The identification is on a card which might be used both for the loyalty and the payment.
  • LinkedCard #The loyalty account is implicitly attached to the payment card. This is usually detected by the loyalty Acquirer.
MarketpayPaymentExtensions Includes "BankID" which provides the BIN of the card
PaymentInstrumentData.CardData

includes:

  • EntryMode: contacltess, mobile... 
  • MaskedPAN: XXXXXXXXXXXX0027,
  • PaymentBrand: "VISA", which can be configured with a BIN mapping base
Response.AdditionalResponse Base 64 encoded value which contain LoyaltyErrorFlag (false or true) to determine if the loyalty reading was successful or not
Card Acquisition Response example JSON

Response to a successful GET with Card Details

{
  "MessageHeader": {
    "MessageCategory": "CardAcquisition",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "321",
    "ProtocolVersion": "3.1",
    "SaleID": "123",
    "ServiceID": "9578"
  },
  "CardAcquisitionResponse": {
    "LoyaltyAccount": [
      {
        "LoyaltyAccountID": {
          "EntryMode": "Contactless",
          "IdentificationSupport": "LoyaltyCard",
          "LoyaltyID": "987654321"
        }
      }
    ],
    "MarketpayPaymentExtensions": {
      "ApplicationID": "A0000000031010",
      "BankID": "476173",
      "PANSequenceNumber": "01",
      "CardAcquisitionReference": {
        "TimeStamp": "2025-11-28T15:14:57.5+01:00",
        "TransactionID": "89"
      }
    },
    "PaymentInstrumentData": {
      "PaymentInstrumentType": "Card",
      "CardData": {
        "EntryMode": "Contactless",
        "MaskedPAN": "XXXXXXXXXXXX0027",
        "PaymentBrand" : "VISA",
        "PaymentToken" : "FXA3HAAWGSPC5",
        "PaymentAccountRef" : "583B0024C8737D1796A43B313A200"
      }
    },
    "POIData": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T15:14:57.5+01:00",
        "TransactionID": "89"
      }
    },
    "Response": {
      "Result": "Success",
      "AdditionalResponse": "PFJlc3BvbnNlPgogICA8RGVzY3JpcHRpb24+VG9rZW4gcmVzcG9uc2UgY29ycnVwdGVkLiBGYWlsZWRUb2tlbkdlbmVyYXRpb25SZXNwb25zZShlcnJvcklEPSwgcmV0dXJuQ29kZT0sIHJldHVybk1lc3NhZ2U9MSBleGNlcHRpb25zIG9jY3VycmVkLiAsIHN0YXJ0VGltZT0sIGVuZFRpbWU9KTwvRGVzY3JpcHRpb24+CiAgIDxMb3lhbHR5RXJyb3JGbGFnPnRydWU8L0xveWFsdHlFcnJvckZsYWc+CjwvUmVzcG9uc2U+"
    },
    "SaleData": {
      "OperatorID": "661",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:14:42Z",
        "TransactionID": "123"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

Card Acquisition Response example XML
<SaleToPOIResponse>
   <CardAcquisitionResponse>
      <MarketpayPaymentExtensions ApplicationID="A0000000041010" BankID="513640" PANSequenceNumber="01">
         <CardAcquisitionReference TimeStamp="2025-03-29T13:43:18.6+01:00" TransactionID="4"/>
      </MarketpayPaymentExtensions>
      <PaymentInstrumentData PaymentInstrumentType="Card">
         <CardData EntryMode="Contactless" MaskedPAN="XXXXXXXXXXXX7462"/>
      </PaymentInstrumentData>
      <POIData>
         <POITransactionID TimeStamp="2025-03-29T13:43:18.6+01:00" TransactionID="4"/>
      </POIData>
      <Response Result="Success">
         <AdditionalResponse>PFJlc3BvbnNlPgogICA8RGVzY3JpcHRpb24+R2VuZXJhdGlvbiBpcyBmb3JiaWRkZW4gYnkgY29uZmlndXJhdGlvbjwvRGVzY3JpcHRpb24+CiAgIDxMb3lhbHR5RXJyb3JGbGFnPmZhbHNlPC9Mb3lhbHR5RXJyb3JGbGFnPgo8L1Jlc3BvbnNlPg==</AdditionalResponse>
      </Response>
      <SaleData>
         <SaleTransactionID TimeStamp="2025-03-29T12:43:19Z" TransactionID="acq-3915"/>
      </SaleData>
   </CardAcquisitionResponse>
   <MessageHeader MessageCategory="CardAcquisition" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3915"/>
</SaleToPOIResponse>

Review the full schema on the API specification page for required fields.

4. Complete Card Acquisition

Based on CardAcquisition response, you decide what to do next: Finish with a Payment or Finish with an Abort.

A. Finish with a Payment

The primary purpose of this response is to provide the Card Acquisition Reference that links the acquired data to the final payment:

  • PaymentData.CardAcquisitionReference must be field with:
    • TimeStamp of the transaction
    • TransactionID provided by POI during CardAcquisition response

During this request, you can adjust Amount and Add a merchant option code compared to original CardAcquisition request.

Card Acquisition Payment Request example

Payment request with CardAcquisition reference to complete payment

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "PayOnSite",
    "ProtocolVersion": "3.1",
    "SaleID": "POS01",
    "ServiceID": "3"
  },
  "PaymentRequest": {
    "PaymentData": {
      "CardAcquisitionReference": {
        "TimeStamp": "2025-11-29T22:03:42Z",
        "TransactionID": "15"
      }
    },
    "PaymentTransaction": {
      "AmountsReq": {
        "Currency": "EUR",
        "RequestedAmount": 12.34
      }
    },
    "SaleData": {
      "OperatorID": "Cashier01",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-29T22:03:49Z",
        "TransactionID": "TransactionID12345"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

B. Finish with an Abort

For complex transactions that begin with a Card Acquisition (a two-step payment), the standard AbortRequest is bypassed. The POS must use MessageCategory Admin and the AdminRequest body must be used, supplying the ServiceIdentification field with a specific Base64-encoded XML payload, setting the <Action> tag to DualTransactionAborted.

Depending on your use case, you may want to stop the card acquisition flow after you have received the response. For this, the POS needs to send an Admin abort:

  • MessageCategory is "Admin"

  • Encode in Base64 the Action ("DualTransactionAborted") and Service ID (from original CardAcquisition Request):

Example decoded in JSON:
{ "Action": "DualTransactionAborted", "ServiceID": "82" }

Example decoded in XML:
<Request>
   <Action>DualTransactionAborted</Action>
   <ServiceID>82</ServiceID>
</Request>
Abort Request after CardAcquisition response example

Payment request with CardAcquisition reference to complete payment

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Admin",
      "MessageType": "Request",
      "ServiceID": "4118",
      "SaleID": "POS_01",
      "POIID": "POI_01"
    },
    "AdminRequest": {
      "ServiceIdentification": "PFJlcXVlc3Q+CiAgICA8QWN0aW9uPkR1YWxUcmFuc2FjdGlvbkFib3J0ZWQ8L0FjdGlvbj4KICAgIDxTZXJ2aWNlSUQ+OTwvU2VydmljZUlEPgo8L1JlcXVlc3Q+Cg=="
    }
  }
}

Review the full schema on the API specification page for required fields.

Abort Response example

Abort response request with CardAcquisition reference to complete payment

{
    "CardAcquisitionResponse": {
        "POIData": {
            "POITransactionID": {
                "TimeStamp": "2026-04-30T13:46:22.602",
                "TransactionID": "27"
            }
        },
        "Response": {
            "ErrorCondition": "Aborted",
            "Result": "Failure"
        },
        "SaleData": {
            "OperatorID": "661",
            "SaleTransactionID": {
                "TimeStamp": "2025-11-28T14:14:42Z",
                "TransactionID": "123"
            }
        }
    },
    "MessageHeader": {
        "MessageCategory": "CardAcquisition",
        "MessageClass": "Service",
        "MessageType": "Response",
        "POIID": "POI_01",
        "ProtocolVersion": "3.1",
        "SaleID": "POS_01",
        "ServiceID": "9578"
    }
}

Review the full schema on the API specification page for required fields.