Receipts

Learn how to provide receipts for In-Person payments.

Printing and Emailing Receipts

While processing In-Person Payments, Finix enables you to provide receipts to buyers upon request.

Card networks require receipts to have certain data elements for the buyer’s convenience.

Manage Your Own Receipts

When using the Finix API, the response body to the Authorization will have 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:

Copy
Copied
{
  "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",
  "other fields" : null
}

Here's an example of the information (not the layout) available in receipts and where to find the information in the Finix response.

Sample Receipt:

Sample Receipt

Receipt Data:

No. Name ReceiptProtocol Field
1 Merchant Name & Address merchantName, merchantAddress
2 Date & Time date
3 Application Label applicationLabel
4 Application Identifier applicationIdentifier
5 Merchant Id merchantId
6 Reference Number referenceNumber
7 Account Number accountNumber
8 Card brand cardBrand
9 Entry Mode entryMode
10 Transaction Id transactionId
11 Approval Code approvalCode
12 Response Code responseCode
13 Response Message responseMessage
14 Amount amount
15 Cryptogram cryptogram
16 Transaction Type transactionType

Prompting Users for Preferred Receipts

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: "PRINT", "EMAIL", and "SMS".

When the user selects an option and submits the relevant contact information, a receipt webhook will be created that you can listen to in order to initiate the printing on your side. 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.

Additional Requirements

Merchant processing agreements require that a separate receipt document must be able to be printed in addition to the POS receipt.

  1. One for the cardholder (a separate receipt from the usual receipt). “Cardholder Copy” must be printed as the last line.
  2. One for the seller. “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 https://socket.io/ to send the message to the receipt. You can also use network-based printers to send receipt information over the network.

Alternatively, you can provide digital receipts instead of paper receipts, but you must be able to provide a paper receipt at the customer's request.

  • The receipt doesn't need to be on receipt paper, but it's the recommended since they don't require ink and are more economical.

Payment Terminals with Receipt Printers

Receipt printing is currently only available for the following payment terminals. All of these terminals include an on-device printer and print compliant receipts:

Printing Receipts with the Finix API

Use the following request to print a receipt for an Authorization or Transfer.

  • Available values for type include MERCHANT or BUYER .
  • Be sure to include true for send_receipt_to_buyer for the action to be taken.
  • If the original transaction included a tip or surcharge, use the breakdown to specify for the receipt how it should be broken down. It will not automatically pull these values from the original transaction.
Copy
Copied
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"
    }'

A successful response returns the receipt resource. The receipt will print from the Device used in the request.

Copy
Copied
{
    "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"
        }
    }
}