Custom Receipts using the API

Should you require more flexibility than the ready-made receipts, you can also send out or print your own receipts including the payment related data! Here is how you can access receipt data using the backend API:

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.

Sample Receipt

1 2 3 4 5


6 7 8

 

 

Required Receipt Information

The image above shows where the data contained in the API response should be displayed:

  1. Full address of the merchant, including the country. Iterate over $.merchantDetails, for each item print $.value.
  2. $.receiptType.value
  3. $.transactionType.value
  4. $.amountAndCurrency
  5. The payment details, e.g. the masked account number. Iterate over $.paymentDetails , for each item print $.label and  $.value .
  6. $.statusText.value 
  7. $.date.value and $.time.value
  8. The clearing details, e.g. the merchant identifier. Iterate over  $.clearingDetails , for each item print $.label and  $.value .
  9. If the $.signatureLineRequired is true, then you have to print a signature line on your merchant receipt. 

 

Query Receipt Data from the Platform API

You can query receipt data for a transaction by its transactionIdentifier and the language code, e.g. en-us.  You can find the necessary authentication and endpoints for this API here.

get /v2/transactions/{transactionIdentifier}/receipts/customer/{country-code} Response
{
 "status": "ok"  
 "data": {

        "merchantDetails": [
            {
                "label": null,
                "key": "MerchantDetailsPublicName",
                "value": "Company Name"
            },
            {
                "label": null,
                "key": "MerchantDetailsAddress",
                "value": "Street 42b"
            },
            {
                "label": null,
                "key": "MerchantDetailsZip",
                "value": "12345"
            },
            {
                "label": null,
                "key": "MerchantDetailsCity",
                "value": "City"
            },
            {
                "label": null,
                "key": "MerchantDetailsCountry",
                "value": "Germany"
            },
            {
                "label": null,
                "key": "MerchantDetailsContact",
                "value": "+49 (170) 1234567"
            },
            {
                "label": null,
                "key": "MerchantDetailsAdditionalInformation",
                "value": "Tax ID: 1234567890"
            }
        ],
        "receiptType": {
            "key": "ReceiptType",
            "label": "Receipt Type",
            "value": "Merchant Receipt"
        },
        "transactionType": {
            "key": "TransactionType",
            "label": "Type",
            "value": "Payment"
        },
        "date": {
            "key": "Date",
            "label": "Date",
            "value": "16.7.2013"
        },
        "time": {
            "key": "Time",
            "label": "Time",
            "value": "15:38:14"
        },
        "identifier": {
            "key": "Identifier",
            "label": "PWID",
            "value": "#{#transactionIdentifier}"
        },
        "statusText": {
            "key": "StatusText",
            "label": "Information",
            "value": "Please retain receipt!"
        },
        "amountAndCurrency": {
            "key": "AmountAndCurrency",
            "label": "Amount",
            "value": "5.20 €"
        },
        "subject": {
            "key": "Subject",
            "label": "Description",
            "value": "MyUsage"
        },
        "paymentDetails": [
            {
                "key": "PaymentDetailsSchemeOrLabel",
                "label": "Card",
                "value": "Visa Credit"
            }, {
                "key": "PaymentDetailsMaskedAccount",
                "label": "Account",
                "value": "1234"
            }, {
                "key": "PaymentDetailsEMVApplicationID",
                "label": "AID",
                "value": "A0000000041010"
             }, {
                "key": "PaymentDetailsSource",
                "label": "Entry Mode",
                "value": "Magstripe"
            }, {
                "key": "PaymentDetailsPanSequenceNumber",
                "label": "PAN Sequence Number",
                "value": "1"
            }
        ],
        "clearingDetails": [
            {
                "key": "ClearingDetailsTransactionIdentifier",
                "label": "Transaction",
                "value": "*"
            }, {
                "key": "ClearingDetailsAuthorizationCode",
                "label": "Authorization",
                "value": "*/*"
            }, {
                "key": "ClearingDetailsMerchantId",
                "label": "Merchant ID",
                "value": "*"
            }, {
                "key": "ClearingDetailsTerminalId",
                "label": "Terminal ID",
                "value": "*"
            }
        ],
        "signatureLineRequired" : false
 },
}

Adjusting timezone, language and number formatting of the receipt data

The receipt data provided by the API can easily be localized. Just pass the name of your time zone as defined in the tz database via the timezone parameter, e.g. Europe/Berlin, Europe/London, Europe/Lisbon or Africa/Johannesburg.

To adjust language and number formatting, pass your locale via the locale parameter. Currently, we support the locales listed in the table below. Should your required locale not be part of it, feel free to contact us!

Supported locale
en-* (e.g. en-US, en-GB)
de-* (e.g. de-DE, de-AT, de-CH)
fr-* (e.g. fr-FR, fr-CH, fr-BE)
it-* (e.g. it-IT, it-CH)
nl-* (e.g. nl-NL, nl-BE)
pt-* (e.g. pt-PT)
es-* (e.g. es-ES)

Can we help you?

If you cannot find your answer, contact us and we'll get in touch with you soon.

© Copyright 2017 Payworks GmbH. Legal.