Invoice Payment Requests

Send secure payment links to customers for easy invoice payment collection

Invoice payment requests provide a simple way to collect invoice payments through secure, hosted payment pages. By generating a payment request link for an invoice, you can give customers an easy way to pay without building custom checkout UI. Share links via email, SMS, or any communication channel—customers complete payment on a Payload-hosted page and the invoice is automatically updated when payment is received.

Prerequisites

Before creating invoice payment requests, ensure you have:

When to Use Payment Requests

Use invoice payment requests when you want to provide customers with a simple, secure way to pay invoices without building custom checkout UI.

Benefits of payment requests

• No Custom Checkout: Skip building payment forms—use Payload-hosted pages
• PCI Compliance: Secure payment collection handled automatically
• Multiple Delivery Options: Send via email, SMS, or share URLs directly
• Mobile Optimized: Payment pages work seamlessly on all devices
• Payment Method Flexibility: Support cards, bank accounts, and digital wallets
• One-Click Sharing: Generate and share payment links instantly

Common use cases

• Invoice Payments: Send payment links when invoices are issued
• Payment Reminders: Share links in reminder emails for overdue invoices
• Customer Support: Generate payment links during support calls
• Partial Payments: Send links for installment or partial invoice payments
• Manual Billing: Create ad-hoc payment links for custom billing scenarios
• Account Receivables: Streamline collection workflow with shareable links

Creating Payment Requests

Create payment links for existing invoices or generate invoices and payment links together.

• Existing Invoice
• Inline Invoice
• Inline Payment Link

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment request link for an invoice
payment_link = pl.PaymentLink.create(
    type='one_time',
    invoice_id='inv_abc123'
    # amount, payer, and biller are inherited from invoice
)
 
print(f'Payment request created: {payment_link.id}')
print(f'Payment URL: {payment_link.url}')
print('Share this URL with the customer to collect payment')
 
# The link expires after 60 days or when payment is completed
print(f'Status: {payment_link.status}')

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment link with an inline invoice
payment_link = pl.PaymentLink.create(
    type='one_time',
    invoice={
        'due_date': '2024-03-01',
        'description': 'Consulting services - February 2024',
        'payer': {
            'account_id': 'acct_customer123'
        },
        'biller': {
            'account_id': 'acct_merchant456'
        },
        'items': [
            {
                'type': 'line_item',
                'description': 'Professional consulting (hourly)',
                'line_item': {
                    'value': 175.00,
                    'qty': 8
                }
            },
            {
                'type': 'line_item',
                'description': 'Project materials',
                'line_item': {
                    'value': 250.00,
                    'qty': 1
                }
            }
        ]
    }
)
 
print(f'Payment link created: {payment_link.id}')
print(f'Invoice created: {payment_link.invoice_id}')
print(f'Payment URL: {payment_link.url}')
print('Share this URL with the customer to collect payment')

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create an invoice with an inline payment link
invoice = pl.Invoice.create(
    due_date='2024-03-01',
    description='Q1 2024 Services',
    payer={'account_id': 'acct_customer123'},
    biller={'account_id': 'acct_merchant456'},
    items=[
        {
            'type': 'line_item',
            'description': 'Consulting services',
            'line_item': {'value': 1500.00, 'qty': 1},
        }
    ],
    payment_links=[
        {
            'type': 'one_time',
            'description': 'Payment for Q1 consulting services',
            'field_options': {
                'custom_fields': [
                    {
                        'section': 'Project Information',
                        'fields': [
                            {
                                'name': 'project_code',
                                'title': 'Project Code',
                                'type': 'text',
                                'optional': False,
                            },
                            {
                                'name': 'department',
                                'title': 'Department',
                                'type': 'text',
                                'optional': True,
                            },
                        ],
                    }
                ]
            },
        }
    ],
)
 
print(f'Invoice created: {invoice.id}')
print(f'Total amount: ${invoice.totals["total"]}')
print(f'\nPayment link created:')
print(f'  ID: {invoice.payment_links[0].id}')
print(f'  URL: {invoice.payment_links[0].url}')
print(f'  Status: {invoice.payment_links[0].status}')
print(
    f'  Custom fields: {len(invoice.payment_links[0].field_options["custom_fields"][0]["fields"])}'
)

Payment link details:

• Links expire after 60 days or when payment is completed
• Amount is set to the invoice's current balance_due
• Payer and biller information inherited from invoice
• Payment automatically allocated to the invoice
• Invoice status updates automatically on payment completion

Sending Payment Requests via Email

Automatically send payment request links to customers via email.

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create and automatically send a payment request via email
 
invoice = pl.Invoice.select(pl.Invoice, pl.Invoice.payer.account).get('inv_abc123')
 
# Create payment link - email is automatically sent to the payer from the invoice
payment_link = pl.PaymentLink.create(
    type='one_time',
    invoice_id=invoice.id,
    description='Payment request for Invoice #1234',
    # Payer info (including email) is derived from the invoice
    # To prevent automatic email, add: email_customer=False
)
 
print(f'Payment request created and sent: {payment_link.id}')
print(f'Email sent to: {invoice.payer.account.contact_details.email}')
print(f'Payment URL: {payment_link.url}')
print(f'Status: {payment_link.status}')  # Will show 'sent' after email is delivered
 
# Customer will receive an email with the payment link

Email delivery behavior:

• Email is automatically sent to the payer from the invoice (payer info is derived)
• Payload sends a professional email with the payment link
• Email includes invoice details and payment instructions
• Link status changes to sent after email delivery
• Customer receives a "Click here to pay" button in the email
• To prevent automatic email sending, set email_customer: false

Email content includes:

• Subject line with invoice reference
• Payment amount and due date
• Business/merchant information
• Secure payment link button
• Invoice details and line items

Tracking email delivery:

# Check if email was delivered
payment_link = pl.PaymentLink.get("pay_xyz789")
 
print("Link status:", payment_link.status)

Sending Payment Requests via SMS

Send payment request links directly to customers' mobile phones via SMS.

SMS delivery

Include customer phone number to trigger SMS sending:

payment_link = pl.PaymentLink.create(
    type="one_time",
    invoice_id="inv_abc123",
    description="Invoice #1234 Payment"
)
 
print("Short URL:", payment_link.url)

SMS delivery behavior:

• Include notifications array with phone to trigger SMS
• Phone number must be in E.164 format (e.g., +15555551234)
• Message includes shortened payment link
• Customer receives text with tap-to-pay link
• Optimized for mobile device payment experience

SMS message format:

[Business Name]: You have an invoice for $149.00.
Pay securely here: https://pay.link/xyz123

Customizing Checkout Options

Configure which payment methods and features are available during checkout.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment request with custom checkout options
 
invoice = pl.Invoice.get('inv_abc123')
 
payment_link = pl.PaymentLink.create(
    type='one_time',
    invoice_id=invoice.id,
    description='Pay Invoice #1234',
    checkout_options={
        'card_payments': True,           # Enable card payments
        'bank_account_payments': True,   # Enable bank account payments
        'enable_mobile_wallets': True,   # Enable Apple Pay / Google Pay
        'enable_plaid': True,            # Enable Plaid bank verification
        'billing_address': True,         # Collect billing address
        'auto_billing_toggle': True      # Show autopay opt-in checkbox
    },
    field_options={
        'payer_fields': 'required',      # Require customer information
        'custom_fields': [
            {
                'section': 'Additional Information',
                'fields': [
                    {
                        'name': 'purchase_order',
                        'title': 'Purchase Order Number',
                        'type': 'text',
                        'optional': False
                    },
                    {
                        'name': 'notes',
                        'title': 'Payment Notes',
                        'type': 'textarea',
                        'optional': True
                    }
                ]
            }
        ]
    }
)
 
print(f'Payment request created: {payment_link.id}')
print(f'Payment URL: {payment_link.url}')
print('Checkout configured with custom options')

Checkout configuration options:

Payment Methods

Control which payment types customers can use:

checkout_options: {
    card_payments: true,           // Enable credit/debit cards
    bank_account_payments: true,   // Enable bank transfer bank accounts
    enable_mobile_wallets: true,   // Enable Apple Pay / Google Pay
    enable_plaid: true             // Enable Plaid bank linking
}

Payment method availability:

• card_payments - Credit and debit card processing
• bank_account_payments - bank transfer direct debit from bank accounts
• enable_mobile_wallets - Apple Pay, Google Pay for supported devices
• enable_plaid - Instant bank verification via Plaid integration

Field Options

Configure customer information collection:

field_options: {
    payer_fields: "required",      // Require customer name/email/phone
    // Options: "required", "optional", "disabled"
}

Payer field options:

• required - Customer must provide name, email, and phone
• optional - Fields shown but not required
• disabled - Fields hidden (use for known customers)

Additional Settings

checkout_options: {
    billing_address: true,         // Collect billing address
    auto_billing_toggle: true,     // Show autopay enrollment checkbox
    payment_method_preview: true,  // Show payment method review step
    show_disclosure: true          // Display payment terms
}

Additional checkout features:

• billing_address - Require full billing address for AVS verification
• auto_billing_toggle - Let customers opt into automatic payments
• payment_method_preview - Show confirmation step before payment
• show_disclosure - Display legal terms and processing disclosures

Collecting Custom Information

Add custom fields to collect additional information during payment.

Custom Field Configuration

field_options: {
  custom_fields: [
    {
      section: "Order Information",
      fields: [
        {
          name: "purchase_order",
          title: "PO Number",
          type: "text",
          optional: false,
          placeholder: "Enter your PO number"
        },
        {
          name: "department",
          title: "Department",
          type: "text",
          optional: true
        }
      ]
    },
    {
      section: "Delivery Instructions",
      fields: [
        {
          name: "delivery_notes",
          title: "Special Instructions",
          type: "textarea",
          optional: true,
          placeholder: "Any special delivery instructions..."
        }
      ]
    }
  ];
}

Custom field types:

• text - Single-line text input
• textarea - Multi-line text area
• email - Email address with validation
• phone - Phone number input
• date - Date picker
• checkbox - Boolean checkbox
• select - Dropdown menu

Field properties:

• name - Field identifier (used in transaction attrs)
• title - Label displayed to customer
• type - Field input type
• optional - Whether field is required (default: false)
• placeholder - Hint text shown in empty field
• value - Pre-filled default value
• readonly - Display-only field (cannot be edited)

Accessing Custom Field Data

After payment is completed, custom field values are stored in the transaction attrs:

transaction = pl.Transaction.get("txn_abc123")
 
print("Custom field values:", transaction.attrs)
# {
#   "purchase_order": "PO-2024-001",
#   "department": "Accounting",
#   "delivery_notes": "Deliver to back entrance"
# }

Handling Payment Completion

Process and verify payments after customers complete payment requests.

Webhook Notifications

Configure webhooks to receive reliable payment notifications:

# Webhook handler for payment completion
from flask import Flask, request
 
app = Flask(__name__)
 
@app.route("/webhooks/payload", methods=["POST"])
def handle_webhook():
    event = request.json
 
    if event["trigger"] == "processed" and event["triggered_on"]["type"] == "payment":
        transaction_id = event["triggered_on"]["id"]
 
        transaction = pl.Transaction.get(transaction_id)
 
        if transaction.invoice_allocations and len(transaction.invoice_allocations) > 0:
            invoice_id = transaction.invoice_allocations[0]["invoice_id"]
 
            invoice = pl.Invoice.get(invoice_id)
 
            print("Invoice payment received!")
            print("Transaction:", transaction.id)
            print("Invoice:", invoice.id)
            print("Invoice status:", invoice.status)
            print("Remaining balance:", invoice.totals["balance_due"])
 
    return "OK", 200

Webhook setup:

1. Create a webhook with trigger: 'processed'
2. Set reference_object: 'transaction'
3. Point to your webhook handler URL
4. Process payment events in real-time

Managing Payment Request Links

Update, cancel, or resend payment request links.

Resend Payment Requests

# Resend an existing payment link via email
def resend_payment_request(link_id, email):
    link = pl.PaymentLink.get(link_id)
 
    if link.status == "completed":
        print("Payment already completed")
        return
 
    if link.status == "expired":
        print("Link expired - create a new one")
        new_link = pl.PaymentLink.create(
            type="one_time",
            invoice_id=link.invoice_id
        )
        print("New payment link sent:", new_link.url)
        return
 
    pl.Notification.create(
        payment_link_id=link.id,
        email=email
    )
 
    print("Payment reminder email sent to:", email)

Cancel Payment Links

# Delete a payment link to prevent use
link = pl.PaymentLink.get("pay_xyz789")
link.delete()
 
print("Payment link canceled and cannot be used")
 
# Or update to inactive status
deactivated = pl.PaymentLink.get("pay_xyz789")
deactivated.update(
    status="inactive"
)
 
print("Payment link deactivated")

When to cancel links:

• Invoice was paid through another method
• Customer requested cancellation
• Invoice was voided or canceled
• Link was sent to wrong email address
• Creating a replacement link with different settings

Handle Expired Links

# Find expired payment links
expired_links = pl.PaymentLink.filter_by(
    q='status == "expired" && invoice_id != null'
).all()
 
print(f"Found {len(expired_links)} expired payment links")
 
# Create new links for unpaid invoices
for link in expired_links:
    invoice = pl.Invoice.get(link.invoice_id)
 
    if invoice.status in ("unpaid", "partially_paid"):
        new_link = pl.PaymentLink.create(
            type="one_time",
            invoice_id=invoice.id
        )
 
        print(f"New link created for invoice {invoice.id}:", new_link.url)

Schema Reference

Fields relevant to invoice payment requests:

Payment Link Configuration

Checkout Options

Invoice Association

Next Steps

Enhance invoice payment collection with automated workflows

Optimize Payment Collection

Enable autopay for recurring invoices with Automatic Payments to automatically charge customers on due dates, process invoice payments programmatically with Payment API for automated billing workflows, and provide customer self-service payment management with Payment Portal for hosted payment experiences.

Manage Invoice Workflows

Generate invoices with line items using Creating Invoices for professional billing, track the invoice lifecycle with Invoice Statuses from draft through paid status, and automate recurring invoice creation with Billing Schedules for subscription-based billing.

Monitor Payment Events

Receive real-time notifications for payment completion with Webhook Events to automate post-payment workflows, track payment processing status with Transaction Status to monitor payment completion and failures, and explore general payment link features with Payment Links Overview for advanced payment collection.

Related articles

• Payment Links Overview - Complete payment link documentation
• Payment Request Links - General payment request guide
• Creating Invoices - Build invoices for customers
• Payment API - Programmatic invoice payments
• Webhook Events - Automate payment workflows
• Payment Links API Reference - Complete API documentation