Cheques

Ce contenu a été traduit par une intelligence artificielle. Si vous repérez une erreur, merci de nous le signaler pour nous aider à améliorer notre support. En cas de doute, la version originale en anglais fait foi.

Le chèque demeure un moyen de paiement courant en France, et notre API prend en charge son traitement via un échange synchrone s'appuyant sur les données du lecteur de chèques local fournies par le POS. Veuillez contacter notre équipe de support client si vous souhaitez activer cette extension de service pour le traitement des chèques.

1. Flux de travail (Workflow)

Le flux de paiement par chèque est un échange synchrone où la vérification et le résultat final sont gérés par le terminal.

Requête : Le POS envoie une requête Payment Request contenant les détails du chèque (Numéro de chèque et clé RLMC).
Traitement : Le POI (terminal) traite la transaction par chèque en communiquant avec le serveur backend pour interroger les partenaires (Verifiance, etc.) pendant que le POS reste en attente.
Résultat final : Le POI renvoie une Payment Response contenant les informations supplémentaires relatives au chèque.
Décision du POS : Sur la base de ces informations supplémentaires, le POS doit prendre sa décision finale :
- Accepter le chèque : Le POS enregistre la transaction.
- Refuser le chèque : Le POS déclenche une annulation de chèque (Cheques Reversal).

2. Requête de paiement par chèque (Cheques Request)

Une requête pour chèque est traitée comme une demande de paiement standard, à laquelle il faut ajouter un élément supplémentaire PaymentData dans le corps de la requête.

En-tête (Header)

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

Corps (Body)

Pour initier avec succès une PaymentRequest pour les chèques, le corps doit contenir les données standard attendues pour une demande de paiement. De plus, vous devez renseigner l'objet dédié : PaymentData.PaymentInstrumentData.

Component Object	Required	Type	Description
`CheckData.CheckCardNumber`	Yes	String	RLMC key, which can be read on Cheque
`CheckData.TrackData.TrackValue`	Yes	String	Raw cheque number to convert into a magnetic stripe track data format (e.g., from `0015468800000000909000000000000` to `D0015468D800000000909F000000000000B`)
`PaymentInstrumentType.IdentificationType`	Yes	String	static data to set to "Check"

Exemple

ChequePayment request example

Start a Cheque payment on terminal, requires providing a Track and RLMC data to perform transaction

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "102"
  },
  "PaymentRequest": {
    "PaymentData": {
      "PaymentInstrumentData": [
        {
          "CheckData": [
            {
              "CheckCardNumber": [
                "09"
              ],
              "TrackData": [
                {
                  "TrackValue": "D0015468D800000000909F000000000000B"
                }
              ]
            }
          ],
          "PaymentInstrumentType": "Check"
        }
      ]
    },
    "PaymentTransaction": {
      "AmountsReq": {
        "Currency": "EUR",
        "RequestedAmount": 10.00
      }
    },
    "SaleData": {
      "OperatorID": "Cashier_01",
      "SaleReferenceID": "8",
      "SaleTransactionID": {
        "TimeStamp": "2024-08-09T07:38:40Z",
        "TransactionID": "123"
      }
    }
  }
}

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

Comment transformer Track 2 Data

Component	Raw Value	Transformed Value	Purpose
Start Sentinel	(Absent)	`D`	The character 'D' (or sometimes ';') marks the beginning of the Track 2 data.
Primary Account Data	`0015468800000000909`	`0015468800000000909`	This sequence is typically the PAN (Primary Account Number) or Check Card Number.
Field Separator (Delimiter)	(Absent)	`D`	The character 'D' separates the card number from the expiration date and service code block.
Expiration/Service Code	(Partial)	`80000000`	These digits usually encode the Expiry Date and the Service Code (which defines allowed usage).
Padding/End of Data	`0000000000000`	`F000000000000`	The 'F' or '0's are used as padding or as the End Sentinel to fill the remaining length of the track.
End Sentinel	(Absent)	`B`	The character 'B' (or sometimes '?') marks the end of the data string on the track.

2. Cheques Response

Le MessageHeader que vous recevez dans la réponse reprend les valeurs que vous avez fournies dans la requête. La seule exception est le MessageType, qui est « Response ».

Corps (Body)

Dans le cadre de la réponse, nous recevons les informations standard liées à un paiement ainsi que des données supplémentaires relatives au mode de paiement par chèque utilisé. Référez-vous au flux d'intégration POS standard pour gérer ces informations.

Pour les chèques, nous recevons la réponse du serveur dans le champ MarketpayPaymentExtensions.issuerOption. Les données brutes transmises sont encodées en Base64.

ChequePayment Response example

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "PayOnSite",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "20"
  },
  "PaymentResponse": {
    "PaymentResult": {
      "AmountsResp": {
        "AuthorizedAmount": "10.00",
        "Currency": "EUR"
      },
      "PaymentAcquirerData": {
        "AcquirerPOIID": "cheque",
        "MerchantID": "Test Cheque"
      },
      "PaymentInstrumentData": {
        "CheckData": [
          {
            "TrackData": [
              {
                "TrackValue": "D0015455D800000000909F************B"
              }
            ]
          }
        ],
        "PaymentInstrumentType": "Check"
      }
    },
    "POIData": {
      "POITransactionID": {
        "TimeStamp": "2025-10-14T11:39:10.000",
        "TransactionID": "0"
      }
    },
    "Response": {
      "AdditionalResponse": "Refused operation by server Currency not managed",
      "Result": "Failure"
    },
    "SaleData": {
      "SaleTransactionID": {
        "TimeStamp": "2025-10-14T11:39:10.000",
        "TransactionID": "0"
      }
    }
  }
}

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

issuerOption decoding

Exemple d'une réponse avec un encodage Base64

issuerOption example

Base64 encoded: IyMjIyA0LiBOZXB0aW5nIFN1Y2Nlc3MgUGF5bWVudCBSZXNwb25zZToKCmBgYApTSUdOQVRVUkVfUkVRVUlSRUQgPSAwCkNVUlJFTkNZX0ZSQUNUSU9OID0gMgpFWFRFTkRFRF9SRVNVTFRfVEVYVCA9ICIiCk1BU0tFRF9BQ0NPVU5UX0lERU5USUZJRVIgPSAiRDAwMTU0NTVEODAwMDAwMDAwOTA5RioqKioqKioqKioqKkIiCkxPQ0FMX1RJTUVTVEFNUCA9IDIwMjUtMTAtMTRUMTE6Mzk6MTAuMDAwCk1FU1NBR0VfSUQgPSAiMCIKTUVTU0FHRV9UWVBFID0gIkRlYml0IgpNRVNTQUdFX05BTUUgPSAiUG9zUmVzcG9uc2UiCkVYVEVOREVEX1JFU1VMVCA9ICIiCk1FUkNIQU5UX1RSU19JRCA9ICIxIgpBUFBMSUNBVElPTl9OQU1FID0gImNoZXF1ZSIKT0ZGTElORV9UUlNfQ09VTlQgPSAiMCIKR0xPQkFMX1NUQVRVUyA9ICIxIgpTVEFOID0gMQpDVVJSRU5DWV9DT0RFID0gOTc4ClRFU1RfSU5ESUNBVE9SID0gMApPRkZMSU5FX1RSU19CTE9DS0VEID0gMApDVVJSRU5DWV9BTFBIQSA9IEVVUgpNRVJDSEFOVF9MQUJFTCA9IFRlc3QgQ2hlcXVlCkVOVFJZX01PREUgPSAiMTYiClNDSEVNRSA9IENIRVFVRQpQT1NfRklOQUxfQU1PVU5UID0gMTAwMApDSFFfQ1BUMSA9ICIwMSIKQ0hRX0NQVDIgPSAiMDMiCkNIUV9DUFQzID0gIjA1IgpDSFFfQkFOSz0gImJhbmtOYW1lIgpDSFFfQ09MT1IgPSAiQkxBTkMi

Decoded:

#### 4. Nepting Success Payment Response:

```
SIGNATURE_REQUIRED = 0
CURRENCY_FRACTION = 2
EXTENDED_RESULT_TEXT = ""
MASKED_ACCOUNT_IDENTIFIER = "D0015455D800000000909F************B"
LOCAL_TIMESTAMP = 2025-10-14T11:39:10.000
MESSAGE_ID = "0"
MESSAGE_TYPE = "Debit"
MESSAGE_NAME = "PosResponse"
EXTENDED_RESULT = ""
MERCHANT_TRS_ID = "1"
APPLICATION_NAME = "cheque"
OFFLINE_TRS_COUNT = "0"
GLOBAL_STATUS = "1"
STAN = 1
CURRENCY_CODE = 978
TEST_INDICATOR = 0
OFFLINE_TRS_BLOCKED = 0
CURRENCY_ALPHA = EUR
MERCHANT_LABEL = Test Cheque
ENTRY_MODE = "16"
SCHEME = CHEQUE
POS_FINAL_AMOUNT = 1000
CHQ_CPT1 = "01"
CHQ_CPT2 = "03"
CHQ_CPT3 = "05"
CHQ_BANK= "bankName"
CHQ_COLOR = "BLANC"

Dans la réponse, vous trouverez les informations clefs pour accepter ou refuser le chèque au niveau de la caisse (POS).

Component	Purpose
CHQ_CPT1	Cheque Counter 1
CHQ_CPT2	Cheque Counter 2
CHQ_CPT3	Cheque Counter 3
CHQ_BANK	Bank Name of the cheque returned by server
CHQ_COLOC	Color code
CHQ_CPT2	This sequence is typically the PAN (Primary Account Number) or Check Card Number.

Comment interpréter la réponse

Source: Verifiance

3. Annulation

Une annulation de chèque (Cheques Reversal) est traitée comme une extourne de paiement standard, à laquelle il faut ajouter un élément « PaymentData » supplémentaire dans le corps de la requête.

En-tête (Header)

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

Corps (Body)

Cheque Reversal Request example JSON

{
  "MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "ReversalRequest": {
    "Currency": "EUR",
    "MarketpayPaymentExtensions": {
      "CheckData": {
        "CheckCardNumber": [
          "09"
        ],
        "TrackData": [
          {
            "TrackValue": "D0015468D800000000909F000000000000B"
          }
        ]
      },
      "PaymentInstrumentType": "Check"
    },
    "OriginalPOITransaction": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    },
    "ReversalReason": "MerchantCancel",
    "ReversedAmount": "11.99",
    "SaleData": {
      "OperatorID": "Cashier_01",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    }
  }
}

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