Accepting Payments via Payment Requests

Learn when and how to accept one-time payments using payment request links

Payment requests provide a simple way to collect one-time payments through secure, hosted payment pages. By generating a payment request link, you can accept payments without building custom checkout UI. Share links via email, SMS, or any communication channel—customers complete payment on a Payload-hosted page and you're notified when payment is received.

Prerequisites

Before creating payment requests, it's helpful to learn about the following topics.

When to Use Payment Requests

Use payment requests when you need a simple way to collect one-time payments from existing customers without building custom checkout UI. Payment requests are single-use links that expire after 60 days or upon successful payment completion.

Payment requests require a customer account to link the payment to a specific customer. This enables saved payment methods and pre-populates customer information for faster checkout.

By using payment requests, PCI compliance and sensitive payment data handling are managed automatically. The hosted page ensures secure collection of card and bank account details in a compliant environment—removing that responsibility from your application.

Common use cases

• Invoice Payments: Generate payment links for invoices and billing statements
• Email Payment Requests: Send payment links via email for one-time purchases
• SMS Payment Collection: Share payment links via text message for mobile payments
• Ad-hoc Payments: Create instant payment links for services or products
• Payment Reminders: Send payment request links for overdue balances

Creating a Payment Request

Creating a payment request requires linking it to a customer account. Create a payment link with the one_time type, then share the returned URL with your customer.

• Basic Request
• For Invoice

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a one-time payment request link
payment_link = pl.PaymentLink.create(
    type='one_time',
    description='Payment Request',
    amount=100.00,
    biller={'account_id': 'acct_receiver123'},
    payer={'account_id': 'acct_customer456'}
)
 
# Share the URL with your customer
print(f"Payment link: {payment_link.url}")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment request for an invoice
payment_link = pl.PaymentLink.create(
    invoice_id='inv_abc123def456'
)
 
# Amount and biller are automatically taken from the invoice
print(f"Payment link: {payment_link.url}")

Configuring Payment Options

Payment requests support checkout configuration options, allowing you to control payment methods, fees, custom fields, and UI behavior.

Payment Methods

Control which payment types are available during checkout:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment request with specific payment methods
payment_link = pl.PaymentLink.create(
    type='one_time',
    description='Payment Request',
    amount=100.00,
    biller={'account_id': 'acct_receiver123'},
    checkout_options={
        'card_payments': True,
        'bank_account_payments': False,
        'enable_mobile_wallets': True
    }
)
 
print(f"Payment link: {payment_link.url}")

This configuration:

• Enables card payments (Visa, Mastercard, American Express, Discover)
• Disables bank account payments
• Enables Apple Pay and Google Pay for customers on compatible devices

Editable Amount

Allow customers to change the payment amount, useful for donations or variable payments:

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create a payment request with editable amount
payment_link = pl.PaymentLink.create(
    type="one_time",
    description="Donation",
    amount=50.00,
    biller={"account_id": "acct_receiver123"},
    field_options={"amount_field": "editable"},
)
 
print(f"Payment link: {payment_link.url}")

This configuration:

• Displays the initial amount as $50
• Allows customers to change the amount to any value they choose
• Useful for donation forms, tips, or customer-determined payments

Custom Fields

Collect additional information from customers during checkout:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment request with custom fields
payment_link = pl.PaymentLink.create(
    type='one_time',
    description='Service Payment',
    amount=200.00,
    biller={'account_id': 'acct_receiver123'},
    field_options={
        'custom_fields': [{
            'section': 'Service Details',
            'fields': [
                {
                    'title': 'Service Type',
                    'name': 'service_type',
                    'type': 'text',
                    'optional': False
                },
                {
                    'title': 'Additional Notes',
                    'name': 'notes',
                    'type': 'text',
                    'optional': True
                }
            ]
        }]
    }
)
 
print(f"Payment link: {payment_link.url}")

This configuration:

• Adds custom form fields grouped by section
• Collects service type and additional notes
• Field values are stored in the transaction attrs object
• Supports text, email, phone, date, and other field types

Sending Payment Requests

You can automatically send payment requests to customers via email or SMS by including payer information when creating the link.

• Send via Email
• Send via SMS

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create and send payment request via email
payment_link = pl.PaymentLink.create(
    type='one_time',
    description='Payment Request',
    amount=100.00,
    biller={'account_id': 'acct_receiver123'},
    payer={
        'account': {
            'name': 'John Doe',
            'email': '[email protected]'
        }
    },
    notifications=[{
        'email': '[email protected]'
    }]
)
 
# Payment link is automatically sent to the customer's email
print("Payment link sent to: [email protected]")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create and send payment request via SMS
payment_link = pl.PaymentLink.create(
    type='one_time',
    description='Payment Request',
    amount=100.00,
    biller={'account_id': 'acct_receiver123'},
    payer={
        'account': {
            'name': 'John Doe',
            'phone': '+15555551234'
        }
    },
    notifications=[{
        'phone': '+15555551234'
    }]
)
 
# Payment link is automatically sent to the customer's phone
print("Payment link sent to: +15555551234")

Tracking Payment Status

After creating a payment request, you can monitor its status and completion through webhooks and API queries.

Webhook Events

Subscribe to the processed webhook trigger to track successful payments. Configure a webhook with:

• trigger: processed - Monitors successful payment completion
• reference_object: transaction - Specifies the object type being monitored
• url: Your endpoint URL to receive webhook notifications

Example webhook handler:

from flask import Flask, request
 
app = Flask(__name__)
 
@app.route("/webhooks/payload", methods=["POST"])
def handle_webhook():
    webhook = request.json
 
    if webhook["trigger"] == "processed" and webhook["triggered_on"]["type"] == "payment":
        transaction = webhook["triggered_on"]
 
        print("Payment successful:", transaction["id"])
        # Update order status in your database
        # Send confirmation email
 
    return "OK", 200

Query Link Status

You can also retrieve the payment link to check its status:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve payment link status
payment_link_id = 'pay_abc123def456'
 
payment_link = pl.PaymentLink.get(payment_link_id)
 
print(f"Status: {payment_link.status}")
print(f"Amount: {payment_link.amount}")
 
if payment_link.status == 'completed':
    print("Payment completed!")
    print(f"Transaction ID: {payment_link.transaction_id}")

When the payment is completed, the transaction_id field will be populated with the ID of the completed transaction, allowing you to retrieve full transaction details.

Payment link statuses:

• active - Link is ready to use
• sent - Link has been sent to customer
• delivered - Link delivery confirmed
• completed - Payment has been received
• expired - Link has expired (60 days)

Schema Reference

The following fields are available when configuring payment request links:

Payment Link Configuration

Configuration options passed when creating the payment link. For complete API reference, see Payment Links API Reference.

Next Steps

Enhance your payment request implementation

Create Customer Accounts

Create customer accounts to enable saved payment methods and faster checkout for payment requests.

Link to Invoices

Create invoices and generate payment requests automatically linked to invoice details.

Monitor Payment Events

Subscribe to webhook notifications to track payment status and automate order fulfillment.

Related articles

• Payment Pages - Multi-use payment links
• Checkout Plugin - Embedded checkout form alternative
• Payment Links API Reference
• Transactions API Reference