Custom Receipts P3

After the transaction has been completed, you are required to provide a payment receipt to both the merchant and the shopper.

Sample Receipt

Actual receipt content varies depending on acquirer and payment method.

1 2 3 4 5


6 7 8

 

 

Required Receipt Information

You need to make sure, that your custom receipt contains all the required fields stated below and that you are able to also send receipts for successful refunds.

When building the receipt on your end, do the following both for transaction.merchantReceipt and transaction.customerReceipt:

  1. Add all the merchant information, such as address including country, by iterating over the merchantDetails
  2. Specify the receipt type:MerchantReceipt or CustomerReceipt. For a receipt sent to the merchant, it must clearly state Merchant Receipt
  3. RECEIPT_TYPE
  4. AMOUNT_AND_CURRENCY
  5. Add all payment related information by iterating over the paymentDetails
  6. STATUS_TEXT
  7. TIME and DATE
  8. And finally add all information from processing the transaction by iterating over the clearingDetails
  9. Check if you need to print a signature line on the receipt via signatureLineRequired
  10. [optional] SUBJECT

Receipt Format

The receipts are already embedded in the execute transaction response that you receive after a successful transaction. The transaction object provides access to the receipt for both merchant and the customer.

Receipts are only attached if the transaction did not fail, so always make sure to check the transaction and both receipt properties before accessing them.

The the receipt data in P3 looks like this:

"merchantReceipt": {
  "data": {
    "RECEIPT_TYPE": {
      "key": "RECEIPT_TYPE",
      "label": "Receipt Type",
      "value": "Merchant Receipt"
    },
    "TRANSACTION_TYPE": {
      "key": "TRANSACTION_TYPE",
      "label": "Type",
      "value": "Payment"
    },
    "SUBJECT": {
      "key": "SUBJECT",
      "label": "Description",
      "value": "Hey World!"
    },
    "IDENTIFIER": {
      "key": "IDENTIFIER",
      "label": "PWID",
      "value": "bf1bda0a0c9611e68a588f955891035b"
    },
    "AMOUNT_AND_CURRENCY": {
      "key": "AMOUNT_AND_CURRENCY",
      "label": "Amount",
      "value": "€1.00"
    },
    "DATE": {
      "key": "DATE",
      "label": "Date",
      "value": "4/27/2016"
    },
    "TIME": {
      "key": "TIME",
      "label": "Time",
      "value": "6:40:27 PM"
    },
    "STATUS_TEXT": {
      "key": "STATUS_TEXT",
      "label": "Information",
      "value": "Please retain receipt!"
    },
  },
  "clearingDetails": [
    {
      "key": "CLEARING_DETAILS_TRANSACTION_IDENTIFIER",
      "label": "Transaction",
      "value": "217500"
    },
    {
      "key": "CLEARING_DETAILS_AUTHORIZATION_CODE",
      "label": "Authorization",
      "value": "721100/055700"
    },
    {
      "key": "CLEARING_DETAILS_MERCHANT_IDENTIFIER",
      "label": "Merchant ID",
      "value": "100058700"
    },
    {
      "key": "CLEARING_DETAILS_TERMINAL_ID",
      "label": "Terminal ID",
      "value": "BAD04568"
    }
  ],
  "paymentDetails": [
    {
      "key": "PAYMENT_DETAILS_SCHEME_OR_LABEL",
      "label": "Card",
      "value": "VISA"
    },
    {
      "key": "PAYMENT_DETAILS_MASKED_ACCOUNT",
      "label": "Account",
      "value": "**** **** **** 0119"
    },
    {
      "key": "PAYMENT_DETAILS_EMV_APPLICATION_ID",
      "label": "AID",
      "value": "A00000000310109999"
    },
    {
      "key": "PAYMENT_DETAILS_SOURCE",
      "label": "Entry Mode",
      "value": "Contactless"
    }
  ],
  "merchantDetails": [
    {
      "key": "MERCHANT_DETAILS_PUBLIC_NAME",
      "label": "Name",
      "value": "Merchant"
    },
    {
      "key": "MERCHANT_DETAILS_ADDRESS",
      "label": "Address",
      "value": "Demo Street 12"
    },
    {
      "key": "MERCHANT_DETAILS_ZIP",
      "label": "Zip",
      "value": "12601"
    },
    {
      "key": "MERCHANT_DETAILS_CITY",
      "label": "City",
      "value": "City"
    },
    {
      "key": "MERCHANT_DETAILS_COUNTRY",
      "label": "Country",
      "value": "Country"
    },
    {
      "key": "MERCHANT_DETAILS_CONTACT",
      "label": "Contact",
      "value": "+49 (170) 1234567"
    },
    {
      "key": "MERCHANT_DETAILS_ADDITIONAL_INFORMATION",
      "label": "Additional Information",
      "value": ""
    }
  ],
  "signatureLineRequired": false,
		
},

Pre-formatted Receipt

Starting from PayServer version 1.28, you have access to pre-formatted receipts. These receipts can be printed right away without any necessity for further formatting. The pre-formatted receipts are flexible to be adjusted according to your printer's character limit for each line.

Setting Pre-formatted Receipts Line Limit

In order to define the maximum characters of each line of pre-formatted receipts, add the following setting to your config.yaml file:

settings:
   receipt:
     max_line_length: 40 # optional; will default to some predefined value if omitted

Please note that 40 is just an example value. The actual value depends on your printer's limit that it can print on its paper. Longer lines will be wrapped to their respective next lines in the returned output.

Retrieving Pre-formatted Receipts

Once you have defined the maximum line length of your pre-formatted receipts, you can simply print them for both customer receipt and merchant receipt. To retrieve the lines, there is an element called lines whose data type is an array of strings at the top level of both customerReceipt and merchantReceipt.

"customerReceipt": {
    ...,
    "lines": [
      "Payworks",
      "Dingolfingerstr.",
      "11111",
      "Munich",
      "Germany",
      "123",
      "",
      "Customer Receipt Payment",
      "",
      "€1.00",
      "",
      "Scheme                              Visa",
      "Account              **** **** **** 1234",
      "AID                       A0000000031010",
      "Entry Mode                          Chip",
      "TC                      B0F614B9BD0D43D1",
      "",
      "         Please retain receipt!         ",
      "",
      "10/21/2020                    3:58:31 PM",
      "",
      "Transaction                       CI_fhS",
      "Authorization              AI_Ffd/II_woR",
      "Merchant ID",
      "    a125ae92-3bad-43d0-a366-3ccb004f0214",
      "Terminal ID                     BAD12345",
      "",
      "________________________________________",
      ""
    ]
},

"merchantReceipt": {
    ...,
    "lines": [
      "Payworks",
      "Dingolfingerstr.",
      "11111",
      "Munich",
      "Germany",
      "123",
      "",
      "Merchant Receipt Payment",
      "",
      "€1.00",
      "",
      "Scheme                              Visa",
      "Account              **** **** **** 1234",
      "AID                       A0000000031010",
      "Entry Mode                          Chip",
      "TC                      B0F614B9BD0D43D1",
      "",
      "         Please retain receipt!         ",
      "",
      "10/21/2020                    3:58:31 PM",
      "",
      "Transaction                       CI_fhS",
      "Authorization              AI_Ffd/II_woR",
      "Merchant ID",
      "    a125ae92-3bad-43d0-a366-3ccb004f0214",
      "Terminal ID                     BAD12345",
      "",
      "________________________________________",
      ""
    ]
}