While processing in-person payments, Finix lets you provide receipts to buyers upon request. Card networks require receipts to have specific data elements for the buyer’s convenience.
This guide covers how to provide receipts for in-person payments via print or email.
When using the Finix API, the response body to the Authorization contains everything you need to print a receipt in the card_present_details object. Here's an example of the card_present_details object and the data that gets printed on the receipt:
{
"id": "AUarp7Pz21Low4u2Urw5Ub4W",
"amount": 150,
"other fields": null,
"card_present_details": {
"emv_data": {
"application_identifier": "A0000001523010",
"application_label": "DISCOVER",
"application_preferred_name": null,
"application_transaction_counter": "0005",
"cryptogram": "ARCQ F666F8891F870D33",
"issuer_code_table_index": null,
"pin_verified": false,
"tags": null
},
"masked_account_number": "************0059",
"name": "Test Card 05",
"brand": "DISCOVER",
"entry_mode": "CHIP_ENTRY",
"payment_type": "CREDIT",
"approval_code": "004839"
},
"merchant": "MU4LYrniAvqVKUBqcATb7Y7p",
"merchant_identity": "IDsbTBawhnLBAVeinRb84vFR",
"state": "SUCCEEDED",
"trace_id": "FNXsK76MxJWPkbGqpKymgkzK"
}Here's an example of the information (not the layout) available in receipts and where to find the information in the Finix response.
| No. | Name | ReceiptProtocol Field | Finix API Location |
|---|---|---|---|
| 1 | Merchant Name & Address | merchantName, merchantAddress | Create independently or pull from the merchant identity. |
| 2 | Date & Time | date | created_at from the transaction response, or create independently. |
| 3 | Application Label | applicationLabel | application_label in emv_data in card_present_details. |
| 4 | Application Identifier | applicationIdentifier | application_identifier in emv_data in card_present_details. |
| 5 | Merchant Id | merchantId | merchant_identity in the response. |
| 6 | Reference Number | referenceNumber | trace_id in the response. |
| 7 | Account Number | accountNumber | masked_account_number in card_present_details. |
| 8 | Card brand | cardBrand | brand in card_present_details. |
| 9 | Entry Mode | entryMode | entry_mode in card_present_details. |
| 10 | Transaction Id | transactionId | id of the transaction. |
| 11 | Approval Code | approvalCode | approval_code in card_present_details. |
| 12 | Response Code | responseCode | — |
| 13 | Response Message | responseMessage | state of the transaction. |
| 14 | Amount | amount | amount in $ format. |
| 15 | Cryptogram | cryptogram | cryptogram in emv_data in card_present_details. |
| 16 | Transaction Type | transactionType | either Sale or Authorization depending on the method used. |
If the prompt_receipt_confirmation value is set to true for the terminal, it will present a page to the cardholder that will prompt them to select from a variety of receipt preferences.
The values you include in available_receipt_methods are the ones that will appear in the prompt menu. Acceptable values are:
PRINTEMAILSMS
When the cardholder selects an option and submits contact information, Finix creates a receipt webhook that you can listen to and use to trigger printing. The webhook is entity: receipt and type: created. It will include all the relevant receipt information and the appropriate contact information to route the printing.
Merchant processing agreements require that a separate receipt document must be able to be printed in addition to the POS receipt.
- One for the cardholder (a separate receipt from the usual receipt). The Cardholder Copy must be printed as the last line.
- One for the seller. The Merchant Copy must be printed as the last line of the second receipt copy.
Depending on the transaction, many of the fields can return null. If they return null, you can either print an empty value (0, N/A, etc.) or remove the line.
Integrating to receipt printers: For serial connections, you'll need to encode the receipt data into the respective printer format (ESC/Star) and then use a variety of programs such as Socket.io to send the message to the printer. You can also use network-based printers to send receipt information over the network.
Alternatively, you can provide digital receipts, but you must be able to provide a paper receipt at the buyer's request.
The receipt does not need to be printed on receipt paper, but receipt paper is recommended because it does not require ink and is more economical.
Use the following request to print a receipt for an Authorization or Transfer.
- Available values for
typeincludeMERCHANTorBUYER. - Set
send_receipt_to_buyertotrueto trigger receipt delivery. - If the original transaction included a tip or surcharge. Use
amount_breakdownto specify individual charges/fees. Finix will not automatically pull these values from the original transaction.
curl https://finix.sandbox-payments-api.com/receipts \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
-X POST \
-d '{
"send_receipt_to_buyer": true,
"amount_breakdown": {
"subtotal_amount": 1700,
"additional_buyer_charges": {
"surcharge_amount": 100
},
"tip_amount": 100
},
"requested_delivery_methods": [
{
"type": "PRINT",
"destinations": [
"DV864n6gKbgGNgQg9LyHpnMR"
]
}
],
"entity_id": "TRrieLrWspuN3W72BP3nD6hh",
"type": "BUYER"
}'{
"id": "receipt_ccBeL2iWn3V1wWSfqjuaE",
"created_at": "2024-06-26T18:06:12.68Z",
"updated_at": "2024-06-26T18:06:12.68Z",
"amount": 500,
"currency": "USD",
"amount_breakdown": null,
"send_receipt_to_buyer": true,
"device_id": "DVmiLSwXdYxC7U3wtGCpF7iD",
"entity_details": {
"id": "TR3rNtUhV4dC82vNsVGLENVD",
"created_at": "2024-05-23T21:26:11.71Z",
"type": "TRANSFER"
},
"type": "BUYER",
"merchant_details": {
"id": "MUrcHDvsFUp4PjJzWo7WzF82",
"business_name": "Smith & Associates Consulting",
"doing_business_as": "Smith & Associates Consulting",
"business_address": {
"city": "Allen",
"country": "USA",
"line1": "1113 Shade Tree Ln",
"line2": null,
"postal_code": "75013",
"region": "TX"
}
},
"payment_instrument_details": {
"id": "PIkXm2YP4isGwpRpfjrDkEc8",
"type": "PAYMENT_CARD_PRESENT",
"bin": "476173",
"brand": "VISA",
"card_type": "CREDIT",
"last_four": "0010"
},
"network_details": {
"application_label": "VISA CREDIT",
"application_identifier": "A0000000031010",
"approval_code": "031475",
"cryptogram": "ARCQ A09FDACC9F024838"
},
"requested_delivery_methods": [
{
"type": "PRINT",
"destinations": ["DVmiLSwXdYxC7U3wtGCpF7iD"]
}
],
"receipt_url": "https://receipt.sb-payments-checkout.com/W3Qoh1",
"_links": {
"self": {
"href": "https://finix.sb-payments-api.com/receipts/receipt_ccBeL2iWn3V1wWSfqjuaE"
}
}
}