Transaction Receipts

Generate and download professional receipts for payments and payouts

Transaction receipts provide customers with detailed records of their payments and payouts. Payload automatically generates professional receipts for every transaction, including all relevant transaction details, custom attributes, and branding. Receipts can be downloaded as PDFs programmatically or accessed through the Payload dashboard.

Prerequisites

Before working with receipts, it's helpful to learn about the following topics.

When to Use Receipts

Use receipts to provide customers with proof of payment and detailed transaction records. Receipts help with:

• Customer Record-Keeping: Provide customers with downloadable payment records
• Expense Tracking: Enable customers to track spending and categorize expenses
• Accounting & Reconciliation: Support bookkeeping with detailed transaction breakdowns
• Compliance & Auditing: Maintain transaction records for regulatory requirements
• Customer Support: Resolve payment inquiries with detailed receipt information
• Transparency: Build trust by providing clear transaction documentation

Receipts include transaction amounts, dates, payment methods, descriptions, reference numbers, and any custom attributes you've added to the transaction.

Downloading Receipt PDFs

Retrieve a PDF receipt for any transaction by making a request to the receipts endpoint.

import os
 
import requests
 
# Download a PDF receipt for a transaction
response = requests.get(
    'https://app.payload.com/receipts/txn_transaction123.pdf',
    auth=(os.getenv('PAYLOAD_API_KEY'), ''),
)
 
with open('receipt.pdf', 'wb') as f:
    f.write(response.content)
 
print('Receipt downloaded to receipt.pdf')

This example demonstrates downloading a receipt:

1. Make a GET request to the receipts endpoint with the transaction ID
2. Include your API key for authentication
3. Save the response data as a PDF file
4. The PDF includes complete transaction details, branding, and custom attributes

Receipt PDFs are generated on-demand and include:

• Transaction amount and date
• Payment method details (last 4 digits of card/account)
• Transaction description and reference number
• Sender and receiver account information
• Custom transaction attributes
• Your account branding (if configured)

Retrieving Receipt Data

Access receipt information by retrieving the transaction object with receipt details.

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Retrieve transaction details including receipt data
transaction = pl.Transaction.get("txn_transaction123")
 
print(f"Transaction ID: {transaction.id}")
print(f"Reference Number: {transaction.ref_number}")
print(f"Description: {transaction.description}")
print(f"Amount: ${transaction.amount}")
print(f"Date: {transaction.created_at}")
 
# Access custom attributes that appear on receipts
if transaction.attrs:
    print(f"Receipt Attributes: {transaction.attrs}")

This allows you to:

• Build custom receipt views in your application
• Extract specific receipt data for reporting
• Display receipt information to customers
• Generate custom receipt formats

The transaction object includes all data that appears on the receipt, including descriptions, amounts, reference numbers, and custom attributes.

Adding Custom Receipt Attributes

Include custom information on receipts by adding attributes to transactions.

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create a payment with custom attributes for receipts
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 150.00,
        "description": "Premium Subscription - Monthly",
        "receiver": {"account_id": "acct_processing123"},
        "sender": {"method_id": "pm_customer456"},
        "attrs": {
            # Public attributes - will appear on receipt
            "Order Number": "ORD-2024-001",
            "Account Number": "ACCT-12345",
            "Subscription Period": "January 2024",
            # Private attribute - hidden from receipt (starts with underscore)
            "_internal_reference": "ref_hidden123",
        },
    }
)
 
print(f"Transaction ID: {transaction.id}")
print("Public attributes will appear on receipt")
print("Private attributes (_prefixed) are hidden from receipt")

This example demonstrates custom attributes:

1. Add custom attributes using the attrs field when creating transactions
2. Public attributes (not starting with underscore) appear on receipts
3. Private attributes (starting with underscore) are hidden from receipts
4. Use custom attributes for order numbers, account numbers, or other reference data

Custom attributes help customers identify transactions and provide additional context on receipts. Only public attributes appear on receipts - private attributes remain accessible via API but hidden from customer-facing receipts.

Sending Receipts Programmatically

Automatically email receipts to customers when creating transactions by including receipt recipient details in the transaction payload.

• Single Recipient
• Multiple Recipients

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create a payment and automatically send receipt to customer
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 150.00,
        "description": "Premium Subscription - Monthly",
        "receiver": {"account_id": "acct_processing123"},
        "sender": {"method_id": "pm_customer456"},
        "receipts": [{"name": "John Doe", "email": "[email protected]"}],
    }
)
 
print(f"Transaction ID: {transaction.id}")
print("Receipt will be automatically emailed to [email protected]")

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Send receipts to multiple recipients
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 250.00,
        "description": "Corporate Invoice #12345",
        "receiver": {"account_id": "acct_processing123"},
        "sender": {"method_id": "pm_customer456"},
        "receipts": [
            {"name": "John Doe", "email": "[email protected]"},
            {"name": "Jane Smith - Accounting", "email": "[email protected]"},
            {"name": "Finance Department", "email": "[email protected]"},
        ],
    }
)
 
print(f"Transaction ID: {transaction.id}")
print("Receipts will be emailed to all 3 recipients")

Receipt Fields and Transaction Data

Receipts automatically include key transaction fields that provide complete transaction context.

Automatic Receipt Fields

These fields are automatically populated on receipts:

• ref_number: Human-readable transaction reference for customer inquiries
• description: Payment purpose shown prominently on receipt
• amount: Transaction amount in processing account currency
• order_number: Your custom order/transaction identifier
• created_at: Transaction timestamp in customer timezone

Email Receipt Delivery

Configure automatic email delivery of receipts to customers for every transaction.

Enabling Email Receipts

Enable automatic receipt emails from the Payload dashboard:

1. Navigate to Settings > Emails and Notifications
2. Enable Automatic Customer Receipts
3. Customize receipt email branding at the account and profile levels

When enabled, Payload automatically emails professional, branded receipts to customers after successful transactions.

Testing Receipts

Test receipt generation and formatting in test mode before production deployment.

Testing Receipt PDFs

Create test transactions with custom attributes and download receipts to verify all functionality:

import os
 
import payload
import requests
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create a test payment with custom attributes
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 25.00,
        "description": "Test Receipt - Order #TEST123",
        "receiver": {"account_id": "acct_processing123"},
        "sender": {"method_id": "pm_test456"},
        "attrs": {
            # Public attributes (will appear on receipt)
            "Order Number": "TEST123",
            "Customer Name": "John Doe",
            "Service Level": "Premium",
            # Private attributes (hidden from receipt, start with underscore)
            "_internal_id": "internal_12345",
            "_debug_flag": "true",
        },
    }
)
 
print(f"Created test transaction: {transaction.id}")
 
# Download the receipt PDF
response = requests.get(
    f"https://app.payload.com/receipts/{transaction.id}.pdf",
    auth=(os.getenv("PAYLOAD_API_KEY"), ""),
)
 
with open("test_receipt.pdf", "wb") as f:
    f.write(response.content)
 
print("Test receipt downloaded to test_receipt.pdf")
print("\nVerify on the receipt PDF:")
print("✓ Public attributes appear (Order Number, Customer Name, Service Level)")
print("✓ Private attributes are hidden (_internal_id, _debug_flag)")
print("✓ Branding and logo display correctly")
print("✓ All transaction details are accurate")

This example creates a transaction with both public and private attributes, downloads the receipt PDF, and verifies:

• Receipt PDF downloads successfully
• All transaction details appear correctly
• Public custom attributes are displayed on the receipt
• Private attributes (starting with underscore) are hidden from the receipt
• Branding and logo display correctly
• Attribute formatting is customer-friendly

Schema Reference

The following fields are relevant for receipt generation and customization:

Transaction Receipt Fields

For complete transaction field documentation, see the Transaction API Reference.

Next Steps

Enhance receipt functionality and transaction management

Process Transactions

Use Payment API to process payments with complete transaction data, send Payouts with receipt generation, and monitor Transaction Status to track completion and receipt availability.

Customize Customer Experience

Configure Custom Attributes to add custom data to transactions and receipts, set up Branding to customize receipt appearance with your logo and colors, and enable Email Notifications to configure automatic receipt delivery.

Build Reporting and Reconciliation

Use Reporting Overview to track receipt generation metrics, create Transaction Reports for transaction summaries, and set up Accounting Integration to sync receipts to accounting systems.

Related articles

• Payment API - Process payments
• Transactions API Reference - Transaction object reference
• Custom Attributes - Add data to receipts
• Webhooks - Monitor receipt events