Receipts

Formatted Receipts

In mAPI a PaymentReceipt object needs a Signature and list of Textlines. Formatted text lines have two attributes - height and width that can be set to SINGLE or DOUBLE. These attributes are required to give the receipt the needed styling when it needs to be printed. The PaymentReceipt object can be built with plainTextLines of formattedTextlines, this is needed to guarantee backwards compatibility. There is also an extra method converTextlines. This method converts TextLine objects from OPI_lib to Textline objects from mAPI.

PaymentReceipt.builder().formattedTextLines(convertTextlines(lines)).build();

JSON Receipts

As it is usually required to design a branded and designed receipt, the receipt’s data is required and parsing the formatted data is error prone, therefore Rubean offers a feature of additionally returning the receipt in a JSON format. The JSON is sent in the first line of the PaymentReceipt object mentioned above and can be handled using the callback functions printMerchantReceiptAndSignature and printCustomerReceiptAndSignature in PaymentDelegate as shown in the example in JSON Receipts

This feature is optional and, in some cases, must be specifically requested to be configured per terminal from Rubean.

Message Structure

{
  "receiptMode": "MERCHANT",
  "merchantHeaders": [
    "Rubean APAS Integration",
    "Kistlerhofstrasse 168",
    "81379 Muenchen"
  ],
  "amount": "80",
  "minorunits": "2",
  "currency": "EUR",
  "currencyNumeric": "978",
  "date": "2025-08-01",
  "time": "10:59",
  "tid": "71001269",
  "receiptNumber": "28",
  "traceNumber": "000135",
  "transactionType": "purchase",
  "cardBrand": "VISA",
  "paymentType": "VISA Chip",
  "maskedPan": "476173######0036",
  "cardSequenceNumber": "0001",
  "emvAid": "A0000000031010",
  "cardDataEntryMode": "contactless",
  "answerCode": "80",
  "answerText": "Saldo zu klein",
  "externalResponseCode": "80",
  "internalTid": "71001269",
  "transactionId": "31301"
}
 

Fields Description

Field Name	Format	Description
receiptMode	String	There are always two receipts generated which differ only in their EMV receipt DOL: "CUSTOMER" / "MERCHANT"
merchantHeaders	UTF-8 Strings	This data is configurable per merchant and is typically used to hold the merchant address information. There can be a maximum of 5 lines.
amount	String	The transaction amount in minor units. An amount of e.g. 1€ would be represented as “100”.
minorunits	String	Number of amount digits. For 1€ represented as 100 the minorunits would be “2”. The value is normally compliant with ISO 4217.
date	yyyy-MM-dd	Local date of this transaction in the terminals time zone
time	HH:mm	Local time of this transaction in the terminals time zone
tid	String	Terminal id which is sent to the acquirer
traceNumber	String	A number increased with every transaction for a specific terminal. This number is related to the acquirer protocol
originalTraceNumber	String	For a Reversal transaction this field contains the traceNumber of the referenced transaction
receiptNumber	String	A number increased with every transaction for a specific terminal. This number is more like an order number
transactionType	String	The type of this financial transaction: "purchase" / "refund" / "reversal"
mid	String	Merchant Id
cardBrand	String	The organization which provides the network to process transactions with this card: "VISA" / "MC"
paymentType	String	Card product used in the transaction (e.g. VISA CREDIT)
maskedPan	String	Masked PAN where only the 6 leftmost digits and 4 rightmost digits are shown
cardSequenceNumber	String	Issuer given sequence number for the PAN
authorizationCode	String	Code returned from the authorization authority for an approved transaction
emvDol	String	A list of EMV elements separated by “/” depending on the EMV configuration
emvAid	String	EMV Application Id
cardDataEntryMode	String	Will be “contactless” if provided
answerCode	String	Result of the transaction, “00” for successful transactions
externalResponseCode	String	Result returned from the processing host
currencyNumeric	String	ISO 4217 numeric currency code
answerText	String	Description for corresponding answerCode
transactionId	String	Rubean transaction identifier

note

For the IBERIA1 system there are additional unique fields that are not present for others

Fields Description

Field Name	Format	Description
internalTid	String	This is the internal terminal id representation of the terminal used for the personalization and attestation services
acquirerIdentificationCode	String	This additional field is assembled from P-11 (STAN), P12(DateTime) & P-35(Acquirer Identification).
method	String	Contains a fixed value of "tarjeta"
merchantReference	String	This field is provided by the ECR in the additionalHostData structure. It is sent in P-37 to the IBERIA1 system and returned to the ECR in the receipt.