# Configuring Receipts

Learn how to provide receipts for In-Person payments via print or email.

Receipts aren't just a formality—they're part of a great customer experience. With Finix, you can effortlessly deliver professional, network-compliant receipts with every in-person payment, whether printed, emailed, or sent via SMS.

Card brands have strict requirements, and we make it easy to meet them.

Standalone
### Configure Receipts Directly on the Standalone Terminal

#### Prerequisites

Before updating the receipt settings, ensure the following:

- The device supports receipt printing and has paper loaded.
- The terminal is powered on.
- The terminal is connected to the internet.
- The Finix Payment App is open on the terminal.


#### Steps to Configure Receipt Settings

1. Navigate to the **Settings** menu on your terminal.
2. Click on **Checkout**.
3. Find the **Receipts** section.
4. Choose your preferred **Receipt Settings**.
5. Click **Save** to apply your changes.


### Screenshots below show the configuration and receipt settings screens.

div
div
img
div
img
div
img
div
img
### Understanding the Receipt Settings:

When **Prompt Receipt Confirmation** is enabled, customers will be asked to choose their preferred receipt delivery method after each transaction.

Under **Receipt Delivery Method**, select which options you want to make available to customers:

- **Email** - Send digital receipts to customer email addresses
- **Print** - Print physical receipts from the terminal
- **SMS** - Send digital receipts via text message


For automatic receipt delivery, we recommend enabling all three options under **Supported Automatic Receipt Delivery Types** unless you are implementing custom receipt handling.

API
### Configure Receipt Settings with the Finix API

Below is an example of how to configure receipt settings via the Finix API.[View full API Reference](https://finix.com/docs/api/tag/Devices/#tag/Devices/operation/updateDevice).

#### Sample request:


```shell Configure Receipt Settings
curl https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
    -X PUT \
    -d '{   "configuration": {
        "automatic_receipt_delivery_methods": [
            "PRINT",
            "EMAIL",
            "SMS"
        ],
        "available_receipt_methods": [
            "PRINT",
            "EMAIL",
            "SMS"
        ]
    }
}'
```

#### Sample response:


```json Configure Receipt Settings Response
{
    "id": "DVc9sV7fddxiJQqjqNEKrETg",
    "created_at": "2025-04-20T23:33:55.600925Z",
    "updated_at": "2025-04-20T23:33:55.600925Z",
    "configuration_details": {
        "allow_debit": true,
        "check_for_duplicate_transactions": true,
        "prompt_amount_confirmation": true,
        "prompt_manual_entry": false,
        "signature_threshold_amount": 10000,
        "bypass_device_on_capture": true,
        "prompt_receipt_confirmation": true,
        "display_tip_on_receipt": false,
        "prompt_tip_on_screen": false,
        "allow_standalone_authorizations": false,
        "allow_standalone_sales": false,
        "allow_standalone_refunds": false,
        "tipping_details": {
            "percent_tipping_threshold": 0,
            "percent_options": [18, 20, 22],
            "fixed_options": [100, 150, 200]
        },
        "idle_message": null,
        "idle_image_file_id": null,
        "automatic_receipt_delivery_methods": ["PRINT", "EMAIL", "SMS"],
        "available_receipt_methods": ["PRINT", "EMAIL", "SMS"],
        "prompt_for_signature": "NEVER",
        "surcharge_basis_points": null
    },
    "description": "Cashier One",
    "enabled": false,
    "idle_message": null,
    "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
    "model": "PAX_A800",
    "name": "My PAX_A800 Finix Device",
    "serial_number": "19046260945",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVc9sV7fddxiJQqjqNEKrETg"
        },
        "merchant": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MU7noQ1wdgdAeAfymw2rfBMq"
        },
        "transfers": {
            "href": "https://finix.sandbox-payments-api.com/transfers"
        },
        "authorizations": {
            "href": "https://finix.sandbox-payments-api.com/authorizations"
        }
    }
}
```

### Printing Receipts with the Finix API

Below is a sample request that you can use to print receipts for any `Authorization` or `Transfer`. The receipt will print to the Device specified under `destinations`.

When creating a Receipt request, keep the following parameters in mind:

- `type`: Specify who the receipt is for (`MERCHANT` or `BUYER`)
- `send_receipt_to_buyer`: Set to `true` to send the receipt to the customer
- `amount_breakdown`: Include tip and surcharge details if applicable (these won't automatically carry over from the original transaction)


#### Sample request:


```shell 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"
    }'
```

#### Sample response:


```json 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", // [!code highlight]
    "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"
        }
    }
}
```

### Adding Custom Fields to Receipts

If you want to add custom fields to receipts, you can use the `receipt_options` object in the request body. API Reference: [Custom Fields in Receipts](https://finix.com/docs/api/tag/Receipts/#tag/Receipts/operation/createReceipt).

Below is a sample request that shows how to add custom fields to a receipt.

#### Sample Request


```shell Create Receipt Request with Custom Fields
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
    -X POST \
    -d '{
        "amount": 2000,
        "currency": "USD",
        "device": "DVcg7T4QtjaMqrUrvW4wN9ZK",
        "operation_key": "CARD_PRESENT_DEBIT",
        "tags": {
            "order_number": "Test Transaction"
        },
        "receipt_options": {
            "additional_details": [
                {
                    "name": "Invoice Number",
                    "value": "123123123123"
                }
            ]
        }
    }'
```

#### Sample Response


```json Create Receipt Response with Custom Fields
{
    "id": "TRweNhbvaAFtp9ufhkfNhVJq",
    "created_at": "2025-06-04T04:54:11.74Z",
    "updated_at": "2025-06-04T04:54:11.74Z",
    "additional_buyer_charges": {
        "convenience_amount": 0,
        "surcharge_amount": 0,
        "rent_surcharge_amount": 0
    },
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 1800,
    "amount_requested": 2000,
    "application": "AP6SikwRjvG2pibYPqsauUfp",
    "card_present_details": {
        "emv_data": {
            "application_identifier": "A0000000031010",
            "application_label": "VISA CREDIT",
            "application_preferred_name": null,
            "application_transaction_counter": "004E",
            "cryptogram": "ARQC AF834FFFF6439655",
            "issuer_code_table_index": null,
            "network_emv_response": null,
            "pin_verified": false,
            "tags": null
        },
        "masked_account_number": "476173******0010",
        "name": null,
        "brand": "VISA",
        "entry_mode": "CONTACTLESS",
        "payment_type": "CREDIT",
        "approval_code": "046299",
        "digital_signature_file_id": null
    },
    "currency": "USD",
    "destination": null,
    "device": "DVcg7T4QtjaMqrUrvW4wN9ZK",
    "externally_funded": "UNKNOWN",
    "failure_code": null,
    "failure_message": null,
    "fee": 0,
    "fee_profile": "FP7TWCCKnEXLrY8R5Z6FYwXy",
    "idempotency_id": null,
    "merchant": "MUvnJCJShHXdCNeYGZfeaGz5",
    "merchant_identity": "IDkkrwinknP5yijVCHrEWz9t",
    "messages": [],
    "operation_key": "CARD_PRESENT_SALE",
    "parent_transfer": null,
    "parent_transfer_trace_id": null,
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": "PIdQuhTX6SgzguYPHmrTB1gg",
    "split_transfers": [],
    "state": "SUCCEEDED",
    "statement_descriptor": "ACME Anchors",
    "subtype": "API",
    "supplemental_fee": null,
    "tags": {
        "order_number": "Test Transaction"
    },
    "tip_amount": null,
    "trace_id": "FNXbSQMzDLYE7gM79Dn1q5o36",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP6SikwRjvG2pibYPqsauUfp"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDkkrwinknP5yijVCHrEWz9t"
        },
        "device": {
            "href": "https://finix.sandbox-payments-api.com/devices/DVcg7T4QtjaMqrUrvW4wN9ZK"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRweNhbvaAFtp9ufhkfNhVJq/disputes"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FP7TWCCKnEXLrY8R5Z6FYwXy"
        }
    }
}
```

## Manage Your Own Receipts

If you want to manage and print your own receipts on your own receipt printer, you can use the `card_present_details` object in the response body to 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:


```json Authorization Resource Example
{
    "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"
}
```

### Sample Receipt

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](/assets/sample-receipt.e3989e6a06a8b12d332eb60fcdbc288d37fa3d63cf440a3dd12c7f1cd16c2400.28b10c14.svg)

### 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` | — |
| 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. |


### Prompting Customers for Receipt Delivery

To let customers choose how they want their receipt, enable `prompt_receipt_confirmation: true` on the terminal.

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 (if needed) enters their contact info, Finix will trigger a webhook:

- `entity: receipt`
- `type: created`


This webhook includes all receipt details, along with 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.

### Additional Receipt Requirements

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

- **Cardholder Copy** – A separate receipt for the buyer. Include "Cardholder Copy" as the final line.
- **Merchant Copy** – A second copy for your business records. Include "Merchant Copy" as the final line.


If certain fields return `null` (e.g., `approval_code`, `cryptogram`), you can either omit the line or display a placeholder 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](https://socket.io/) to send the formatted data to the printer.
- **Network Printers:** Alternatively, 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—thermal printers don't require ink and are more cost-effective over time.

Dashboard
### Configure Receipts on the Dashboard

#### Prerequisites

Before updating the receipt settings, ensure the following:

- The device supports receipt printing and has paper loaded.
- The terminal is powered on.
- The terminal is connected to the internet.
- The Finix Payment App is open on the terminal.


#### Steps to Configure Receipt Settings

1. Log in to the [Finix Dashboard](https://finix.payments-dashboard.com/).
2. Navigate to **Device Management**.
3. Select the device you want to configure.
4. Go to the **Configuration** section.
5. Choose your preferred **Receipt Settings**.
6. Click **Save** to apply your changes.


### Screenshots below show the configuration and receipt settings screens.

img
img
### Understanding the Receipt Settings:

When **Prompt Receipt Confirmation** is enabled, customers will be asked to choose their preferred receipt delivery method after each transaction.

Under **Receipt Delivery Method**, select which options you want to make available to customers:

- **Email** - Send digital receipts to customer email addresses
- **Print** - Print physical receipts from the terminal
- **SMS** - Send digital receipts via text message


For automatic receipt delivery, we recommend enabling all three options under **Supported Automatic Receipt Delivery Types** unless you are implementing custom receipt handling.