Logging
NOTE: When we certify an ECR we demand that the ECR is equipped with a good enough logging to make troubleshooting in the future easy and accessible :::
Why does logging require a page on its own?
Logging is a crucial part of maintaining the performance and security of your ECR. Its helping you identify and troubleshoot issues effectively. This page will give you best practices and examples for implementing logging in your ECR.
We have been apart of way too many integrations where the logfile of the ECR is filled with shattered textfields, no timestamps, zero structure, etc. So we need to shine some light on this subject to help us, and you to troubleshoot issues in the future.
The structure of your logs
A well-defined log format ensures consistency which then results in an easier time when parsing a log. Consider using a structured format like:
- JSON
- XML
- CSV
- YAML
- MARKDOWN
- or a standardized log message pattern.
They are all accepted and we are looking forward to seeing how you log your communication! :)
What should the logs look like?
This example shows you a log that clearly defines where the message originated, what kind of message it is and its contents in an unaltered form:
Good looking log
"dateTime":\"2023-09-12 12:49:23:452\" From ECR: 192.168.23.102:1337 Payments Request
{
"integration-key":"Your integration Key",
\t\"amounts\": {
\t\"base\": 100,
\t\"currencySymbol\": \"SEK\",
}
}
"dateTime":\"2023-09-12 12:49:25:902\" From Terminal: 192.168.89.102 Payments Response
{
"amounts": {
"base": 100,
"total": 100,
"currency": {
"code": "752",
"symbol": "SEK",
"exponent": 2
}
},
"approvalCode": "600291",
"authorizationMethod": {
"id": "1",
"description": "Online"
},
"authorizationResponder": {
"id": "3",
"description": "Authorized by DPC"
},
"batchNumber": "974",
"cardProductName": "MASTERCARD",
"emvData": {
"aid": "A0000000041010",
"atc": "00743",
"psn": "00",
"tvr": "0000008001",
"ac": {
"arqc": "331A5BE067EEC68E"
}
},
"entryMode": {
"id": "K",
"description": "Contactless EMV"
},
"financialInstitution": "DUM",
"internalKernelStatus": "0x203",
"isoResponseCode": "00",
"maskedPan": "************3836",
"merchant": {
"acquirerId": "123456789",
"id": "65828034",
"name": "Petter Test - Sverige",
"address": "Slottsjordsvägen 5",
"city": "30238 Halmstad",
"organizationNumber": "556621-5215",
"phoneNumber": "432523452345"
},
"paymentAccountReference": "5001ERON1M70FLSE51WNNZE9UG2I6",
"receiptNumber": "070219",
"receipt": {
"customer": {
"shouldPrint": true,
"escpos": "GyEbUBtBUGV0dGVyIFRlc3QgLSBTdmVyaWdlClNsb3R0c2pvcmRzduRnZW4gNQozMDIzOCBIYWxtc3RhZApUZm46IDQzMjUyMzQ1MjM0NQpPUkcuTlI6IDU1NjYyMS01MjE1CgobJhtQG0BURVJNSU5BTDobQjE4Mjg1NzMwMzIwMTExMjIwMzI5NTQyNgobQEJVVElLOhtCMTIzNDU2Nzg5IDY1ODI4MDM0ChtAREFUVU06MjAyMy0wOS0xMhtCVElEOjIxOjQ4ChtAG0EKG1JL1lAKR09ES8ROVAobUAobQEJFTE9QUBtCU0VLIDEwMCwwMAobQBtSVE9UQUwbQlNFSyAxMDAsMDAKG0AbUApDT05UQUNUTEVTUwpNQVNURVJDQVJECioqKioqKioqKioqKjM4MzYbQlBTTjowMAobQAobQUJBTSBLLzEgMyAwMDAgRFVNIDk3NCA2MDAyOTEKG0BLVklUVE86MDcwMjE5G0JSRUY6MzA3MzQzNzYwNzY1ChtACkFUQzowMDc0MyAgG0IKG0BBSUQ6QTAwMDAwMDAwNDEwMTAKVFZSOjAwMDAwMDgwMDEKQVJRQzozMzFBNUJFMDY3RUVDNjhFCgobJBtQG0FTUEFSQSBLVklUVE9ULCBLVU5ERU5TIEtPUElBCgobJwAA",
"plain": "\\tPetter Test - Sverige\\n\\tSlottsjordsvägen 5\\n\\t30238 Halmstad\\n\\tTfn: 432523452345\\n\\tORG.NR: 556621-5215\\n\\nTERMINAL:\\t\\t182857303201112203295426\\nBUTIK:\\t\\t123456789 65828034\\nDATUM:2023-09-12\\t\\tTID:21:48\\n\\t\\n\\tKÖP\\n\\tGODKÄNT\\n\\nBELOPP\\t\\tSEK 100,00\\nTOTAL\\t\\tSEK 100,00\\n\\nCONTACTLESS\\nMASTERCARD\\n************3836\\t\\tPSN:00\\n\\n\\tBAM K/1 3 000 DUM 974 600291\\nKVITTO:070219\\t\\tREF:307343760765\\n\\nATC:00743 \\t\\t\\nAID:A0000000041010\\nTVR:0000008001\\nARQC:331A5BE067EEC68E\\n\\n\\tSPARA KVITTOT, KUNDENS KOPIA\\n\\n\""
},
"merchant": {
"shouldPrint": false,
"escpos": "GyEbUBtBUGV0dGVyIFRlc3QgLSBTdmVyaWdlClNsb3R0c2pvcmRzduRnZW4gNQozMDIzOCBIYWxtc3RhZApUZm46IDQzMjUyMzQ1MjM0NQpPUkcuTlI6IDU1NjYyMS01MjE1CgobJhtQG0BURVJNSU5BTDobQjE4Mjg1NzMwMzIwMTExMjIwMzI5NTQyNgobQEJVVElLOhtCMTIzNDU2Nzg5IDY1ODI4MDM0ChtAREFUVU06MjAyMy0wOS0xMhtCVElEOjIxOjQ4ChtAG0EKG1JL1lAKR09ES8ROVAobUAobQEJFTE9QUBtCU0VLIDEwMCwwMAobQBtSVE9UQUwbQlNFSyAxMDAsMDAKG0AbUApDT05UQUNUTEVTUwpNQVNURVJDQVJECioqKioqKioqKioqKjM4MzYbQlBTTjowMAobQAobQUJBTSBLLzEgMyAwMDAgRFVNIDk3NCA2MDAyOTEKG0BLVklUVE86MDcwMjE5G0JSRUY6MzA3MzQzNzYwNzY1ChtACkFUQzowMDc0MyAgG0IKG0BBSUQ6QTAwMDAwMDAwNDEwMTAKVFZSOjAwMDAwMDgwMDEKQVJRQzozMzFBNUJFMDY3RUVDNjhFCgobJBtQG0FTUEFSQSBLVklUVE9ULCBCVVRJS0VOUyBLT1BJQQoKGycA",
"plain": "\\tPetter Test - Sverige\\n\\tSlottsjordsvägen 5\\n\\t30238 Halmstad\\n\\tTfn: 432523452345\\n\\tORG.NR: 556621-5215\\n\\nTERMINAL:\\t\\t182857303201112203295426\\nBUTIK:\\t\\t123456789 65828034\\nDATUM:2023-09-12\\t\\tTID:21:48\\n\\t\\n\\tKÖP\\n\\tGODKÄNT\\n\\nBELOPP\\t\\tSEK 100,00\\nTOTAL\\t\\tSEK 100,00\\n\\nCONTACTLESS\\nMASTERCARD\\n************3836\\t\\tPSN:00\\n\\n\\tBAM K/1 3 000 DUM 974 600291\\nKVITTO:070219\\t\\tREF:307343760765\\n\\nATC:00743 \\t\\t\\nAID:A0000000041010\\nTVR:0000008001\\nARQC:331A5BE067EEC68E\\n\\n\\tSPARA KVITTOT, BUTIKENS KOPIA\\n\\n\""
}
},
"spdhResponseCode": "000",
"terminal": {
"id": "182857303201112203295426",
"dateTime": "2023-09-12T21:49",
"uptimeSeconds": 2101,
"software": {
"current": "bambora_pos-1.0.20.6993"
},
"rebootTime": "21:12"
},
"terminalResponse": {
"id": 0,
"description": "Successful"
},
"terminalRrn": "230912214859",
"timestamp": "230912214859",
"transactionId": "307343760765",
"transactionOutcome": "Approved",
"transactionType": "Payment",
"verificationMethod": {
"id": "/",
"description": "No CVM required"
}
}
Here is an example of a practically unusable logfile
- No identification of who sends and receives the data.
- Not any clear and readable timestamps.
- No IP/PORT of the ECR and Terminal.
- Scrambled data-elements. The values doesn't correlate to the data-elements.
Worse looking log
Message dateTime: 20230923-20314523
integration-key amounts/base amounts/currencySymbol
Your integration key 100 SEK
Message dateTime: 20230923-20314601
amounts/base amounts/total amounts/currency/code amounts/currency/symbol amounts/currency/exponent approvalCode authorizationMethod/id authorizationMethod/description authorizationResponder/id authorizationResponder/description batchNumber cardProductName emvData/aid emvData/atc emvData/psn
emvData/tvr emvData/ac/arqc entryMode/id entryMode/description financialInstitution internalKernelStatus isoResponseCode maskedPan merchant/acquirerId merchant/id merchant/name
merchant/address merchant/city merchant/organizationNumber merchant/phoneNumber paymentAccountReference receiptNumber receipt/customer/shouldPrint
receipt/customer/escpos receipt/customer/plain receipt/merchant/shouldPrint receipt/merchant/escpos receipt/merchant/plain spdhResponseCode terminal/id terminal/dateTime terminal/
uptimeSeconds terminal/software/current terminal/rebootTime terminalResponse/id terminalResponse/description terminalRrn timestamp transactionId transactionOutcome transactionType verificationMethod/id verificationMethod/description
100 100 752 SEK 2 600291 1 Online 3 Authorized by DPC 974 MASTERCARD A0000000041010 00743 00 0000008001 331A5BE067EEC68E K Contactless EMV DUM 0x203 00 ************3836 123456789 65828034 Petter Test - Sverige Slottsjordsvägen 5 30238 Halmstad 556621-5215 432523452345 5001ERON1M70FLSE51WNNZE9UG2I6 070219 true GyEbUBtBUGV0dGVyIFRlc3QgLSBTdmVyaWdlClNsb3R0c2pvcmRzduRnZW4gNQozMDIzOCBIYWxtc3RhZApUZm46IDQzMjUyMzQ1MjM0NQpPUkcuTlI6IDU1NjYyMS01MjE1CgobJbtQG0BURVJNSU5BTDobQjE4Mjg1NzMwMzIwMTExMjIwMzI5NTQyNgobQEJVVElLOhtCMTIzNDU2Nzg5IDY1ODI4MDM0ChtAREFUVU06MjAyMy0wOS0xMhtCVElEOjIxOjQ4ChtAG0EKG1JL1lAKR09ES8ROVAobUAobQEJFTE9QUBtCU0VLIDEwMCwwMAobQBtSVE9UQUwbQlNFSyAxMDAsMDAKG0AbUApDT05UQUNUTEVTUwpNQVNURVJDQVJECioqKioqKioqKioqKjM4MzYbQlBTTjowMAobQAobQUJBTSBLLzEgMyAwMDAgRFVNIDk3NCA2MDAyOTEKG0BLVklUVE86MDcwMjE5G0JSRUY6MzA3MzQzNzYwNzY1ChtACkFUQzowMDc0MyAgG0IKG0BBSUQ6QTAwMDAwMDAwNDEwMTAKVFZSOjAwMDAwMDgwMDEKQVJRQzozMzFBNUJFMDY3RUVDNjhFCgobJBtQG0FTUEFSQSBLVklUVE9ULCBLVU5ERU5TIEtPUElBCgobJwAA "\"" false GyEbUBtBUGV0dGVyIFRlc3QgLSBTdmVyaWdlClNsb3R0c2pvcmRzduRnZW4gNQozMDIzOCBIYWxtc3RhZApUZm46IDQzMjUyMzQ1MjM0NQpPUkcuTlI6IDU1NjYyMS01MjE1CgobJbtQG0BURVJNSU5BTDobQjE4Mjg1NzMwMzIwMTExMjIwMzI5NTQyNgobQEJVVElLOhtCMTIzNDU2Nzg5IDY1ODI4MDM0ChtAREFUVU06MjAyMy0wOS0xMhtCVElEOjIxOjQ4ChtAG0EKG1JL1lAKR09ES8ROVAobUAobQEJFTE9QUBtCU0VLIDEwMCwwMAobQBtSVE9UQUwbQlNFSyAxMDAsMDAKG0AbUApDT05UQUNUTEVTUwpNQVNURVJDQVJECioqKioqKioqKioqKjM4MzYbQlBTTjowMAobQAobQUJBTSBLLzEgMyAwMDAgRFVNIDk3NCA2MDAyOTEKG0BLVklUVE86MDcwMjE5G0JSRUY6MzA3MzQzNzYwNzY1ChtACkFUQzowMDc0MyAgG0IKG0BBSUQ6QTAwMDAwMDAwNDEwMTAKVFZSOjAwMDAwMDgwMDEKQVJRQzozMzFBNUJFMDY3RUVDNjhFCgobJBtQG0FTUEFSQSBLVklUVE9ULCBCVVRJS0VOUyBLT1BJQQoKGycA "\"" 000 182857303201112203295426 2023-09-12T21:49 2101 bambora_pos-1.0.20.6993 21:12 0 Successful 230912214859 230912214859 307343760765 Approved Payment / No CVM required
Effort put into good logs is never wasted!