Acquisition de carte

Avec une requête d'acquisition de carte via l'API Terminal, vous pouvez obtenir les identifiants de carte et de client avant de réaliser un paiement, ou en dehors d'un flux de paiement. L'opération d'acquisition de carte est traitée de manière asynchrone.

Le flux basique d'acquisition de carte est le suivant.

Le POS déclenche une requête d'acquisition de carte.
Sur le POI, le client tapote, insère ou glisse sa carte.
Le POS traite les données de carte acquises à partir de la réponse dans vos propres systèmes, selon ce que vous souhaitez réaliser. Le terminal affiche un état "traitement en cours".
Le POS termine l'acquisition de carte de l'une des façons suivantes :
- avec un paiement, le POI utilisera les données acquises pour traiter la transaction.
- avec un abandon administrateur. Cela indique au terminal qu'il n'a plus besoin de conserver les données acquises.

Pour le client, l'acquisition de carte suivie d'un paiement est aussi fluide qu'un paiement standard.

1. Requête d'acquisition de carte

En-tête

L'objet standard SaleToPOIRequest.MessageHeader , avec MessageClass défini sur Service et MessageCategory défini sur CardAcquisition.

Corps

Pour initier avec succès une CardAcquisitionRequest, le corps doit contenir certaines informations clés liées à SaleData et CardAcquisition. Notez que CardAcquisitionTransaction est un objet requis qui peut être vide.

Objet composant	Requis	Type	Description
`SaleData.SaleTransactionID.TransactionID`	Oui	Objet	Identifiant unique généré par le POS pour cet événement d'acquisition.
`SaleData.SaleTransactionID.TimeStamp`	Oui	Objet	date et heure de la requête au format UTC.
`CardAcquisitionTransaction.TotalAmount`	Non	Chaîne	Le montant total attendu pour la transaction.
`CardAcquisitionTransaction.PaymentType`	Non	Enum	si vous avez l'intention de continuer avec un paiement, omettez ce paramètre ou spécifiez Normal.
`CardAcquisitionTransaction.TotalAmount`	Non	Chaîne	Le montant de la transaction. Lorsque vous ne connaissez pas encore le montant, vous pouvez omettre ce paramètre ou spécifier un montant initial et fournir le montant final plus tard, dans la requête de paiement.
`AmountsReq.RequestedAmount`	Non	Objet	Détails de la devise et du montant demandé.

Exemple JSON de requête d'acquisition de carte

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

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.

Exemple XML de requête d'acquisition de carte

<?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>

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.

2. Statut intermédiaire

Une acquisition de carte s'exécute de manière asynchrone, le Terminal de Paiement (POI) utilise des messages Display Request pour informer le Point de Vente (POS) de l'interaction requise du client ou de l'état actuel du terminal. Le POS peut interpréter ces informations pour mettre à jour l'affichage client ou l'interface du caissier, puis continuer à attendre le résultat final. Reportez-vous au flux Intégration standard POS pour le gérer.

3. Réponse d'acquisition de carte

L'en-tête de message (MessageHeader) que vous recevez dans la réponse reflète les valeurs que vous avez fournies dans la requête. La seule exception est le MessageType, qui est Response.

À partir de la CardAcquisitionResponse, récupérez les détails dont vous avez besoin pour votre cas d'utilisation :

Objet composant	Objectif pour POS/Entreprise
`POIData.POITransactionID`	Si vous allez continuer avec un paiement, conservez le TimeStamp et TransactionID, car vous aurez besoin de ces détails d'acquisition de carte dans votre requête de paiement.
`LoyaltyAccount.LoyaltyAccountID`	LoyaltyID : ID de la fidélité du client IdentificationSupport qui permet de savoir où et comment l'identification du compte fidélité a été réalisée : NoCard #L'identification n'est pas trouvée sur une carte LoyaltyCard #L'identification est sur une carte dédiée à cette marque de fidélité. HybridCard #L'identification est sur une carte qui peut être utilisée à la fois pour la fidélité et le paiement. LinkedCard #Le compte fidélité est implicitement attaché à la carte de paiement. Cela est généralement détecté par l'acquéreur de fidélité.
`MarketpayPaymentExtensions`	Inclut "BankID" qui fournit le BIN de la carte
`PaymentInstrumentData.CardData`	comprend : EntryMode : sans contact, mobile... MaskedPAN : XXXXXXXXXXXX0027, PaymentBrand : "VISA", qui peut être configuré avec une base de correspondance BIN
`Response.AdditionalResponse`	Valeur encodée en Base 64 contenant le LoyaltyErrorFlag (false ou true) pour déterminer si la lecture de fidélité a réussi ou non

Exemple JSON de réponse d'acquisition de carte

Réponse à un GET réussi avec détails de carte

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

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.

Exemple XML de réponse d'acquisition de carte

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

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.

4. Finalisation de l'acquisition de carte

En fonction de la réponse d'acquisition de carte, vous décidez de la suite : terminer par un paiement ou terminer par un abandon.

A. Terminer par un paiement

L'objectif principal de cette réponse est de fournir la Référence d'acquisition de carte qui lie les données acquises au paiement final :

Le champ PaymentData.CardAcquisitionReference doit contenir :
- Le TimeStamp de la transaction
- Le TransactionID fourni par le POI lors de la réponse d'acquisition de carte

Lors de cette requête, vous pouvez ajuster le montant et ajouter un code d'option commerçant par rapport à la requête d'acquisition de carte initiale.

Exemple de requête de paiement avec acquisition de carte

Requête de paiement avec référence d'acquisition de carte pour finaliser le paiement

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

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.

B. Terminer par un abandon

Pour les transactions complexes qui commencent par une acquisition de carte (paiement en deux étapes), la requête standard AbortRequest est contournée. Le POS doit utiliser MessageCategory Admin et le corps AdminRequest doit être utilisé, en fournissant le champ ServiceIdentification avec une charge utile XML spécifique encodée en Base64, définissant la balise <Action> sur DualTransactionAborted.

Selon votre cas d'utilisation, vous pouvez vouloir arrêter le flux d'acquisition de carte après avoir reçu la réponse. Pour cela, le POS doit envoyer un abandon administrateur :

MessageCategory est "Admin"
Encoder en Base64 l'Action ("DualTransactionAborted") et l'ID de service (depuis la requête d'acquisition de carte originale) :

Exemple décodé en JSON :
{ "Action": "DualTransactionAborted", "ServiceID": "82" }

Exemple décodé en XML :
<Request>
   <Action>DualTransactionAborted</Action>
   <ServiceID>82</ServiceID>
</Request>

Exemple de requête d'abandon après réponse d'acquisition de carte

Requête de paiement avec référence d'acquisition de carte pour finaliser le paiement

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

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.

Exemple de réponse d'abandon

Réponse à la requête d'abandon avec référence d'acquisition de carte pour finaliser le paiement

{
  "SaleToPOIResponse": {
    "AdminResponse": {
      "Response": {
        "Result": "Success",
        "AdditionalResponse": "PFJlc3BvbnNlPgogICA8QWN0aW9uPkR1YWxUcmFuc2FjdGlvbkFib3J0ZWQ8L0FjdGlvbj4KICAgPFNlcnZpY2VJRD45PC9TZXJ2aWNlSUQ+CjwvUmVzcG9uc2U+"
      }
    },
    "MessageHeader": {
      "MessageCategory": "Admin",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "POI_01",
      "ProtocolVersion": "3.1",
      "SaleID": "POS_01",
      "ServiceID": "4118"
    }
  }
}

Consultez le schéma complet sur la page de spécification de l'API pour les champs obligatoires.