Sending Receipts

Managing Your Own Receipts

Learn how to provide receipts for In-Person or Online payments.

How to Manage Your Own Receipts

If you want to manage and print your own receipts using your own receipt printer, you can use the card_present_details object in the response body of the Authorization or Transfer resource. Here's an example of the card_present_details object and the data that should be 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"
}

The following example outlines the receipt data elements (not the visual layout) and maps each element to its corresponding field in the Finix API response.

Sample Receipt:

Receipt Data:

No.	Name	ReceiptProtocol Field	Finix API Location
1	Merchant Name & Address	`merchantName`, `merchantAddress`	Generate independently or pull from the merchant identity.
2	Date & Time	`date`	`created_at` from the transaction response or generate 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`	null
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.

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.

Create Receipt Request

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.

Create Receipt Response

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

Additional Requirements

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 how they want their receipt.

When enabled, the terminal will display a screen asking the customer how they'd like to receive their receipt. You control the available options by setting available_receipt_methods. Supported values include:

PRINT
EMAIL
SMS

Once the customer selects a method and submits relevant contact information, Finix will trigger a webhook:

entity: receipt
type: created

This webhook includes all receipt details, including the delivery method and destination (e.g., email address or phone number), so you can take the appropriate action—like printing or sending the receipt.

Receipt Requirements

To stay compliant with card networks and processing requirements, merchant must be able to print two copies of the receipt:

Cardholder Copy – A separate receipt for the buyer. "Cardholder Copy" must be printed on the last line of the receipt.
Merchant Copy
A second copy for your business records. "Merchant Copy" must be printed on the last line of the receipt.

Depending on the transaction, many of the fields can return null. You can either omit the line or display a placeholder value such as N/A or 0.

Integrating with Receipt Printers

Serial Printers: Encode the receipt data using the required printer command set (e.g., ESC/POS or Star commands). Use programs like Socket.IO to send the formatted data to the printer.
Network Printers: Send receipt data directly over the network to supported IP printers.

Digital vs. Paper Receipts

You may provide digital receipts (email or SMS), but you must always be able to provide a printed receipt if the customer requests one.

While the receipt doesn't have to be printed on thermal receipt paper, it's recommended, as thermal printers don't require ink and are more cost-effective over time.