Accepting Payments via Checkout Link

Learn when and how to accept payments using hosted checkout links

Payload checkout links provide a secure, hosted payment experience for your customers. By generating a link, you can redirect customers to complete payment without embedding checkout UI in your application. Customers complete payment on a Payload-hosted page and are redirected back to your application upon completion with payment status.

Prerequisites

Before integrating checkout links, it's helpful to learn about the following topics.

When to Use Checkout Links

Use checkout links when you need a simple way to accept payments without embedding checkout UI directly in your application. Checkout links are ideal for programmatic flows where you redirect customers to complete payment on a secure, Payload-hosted page, then receive them back in your application with payment status.

By using checkout links, 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

• Multi-Step Workflows: Send users to payment page as part of onboarding or purchase flows
• No-Code Payment Collection: Accept payments without building custom checkout UI
• Programmatic Payment Initiation: Generate payment links dynamically based on business logic
• Third-Party Integrations: Enable payment collection from systems with limited extensibility that support redirects

Generating a Checkout Link

Creating a checkout link is a two-step process: create an intent with the checkout_link type, then redirect your customer to the returned URL to complete payment.

• Basic Link
• With Customer

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
from flask import Flask, redirect, jsonify
 
app = Flask(__name__)
 
@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    # Create a checkout link intent
    intent = pl.Intent.create(
        type='checkout_link',
        checkout_link={
            'payment_template': {
                'amount': 100.00,
                'description': 'Order #12345',
                'receiver': {
                    'account_id': 'acct_receiver123'
                }
            },
            'redirects': {
                'completed_url': 'https://yourapp.com/payment-complete',
                'return_url': 'https://yourapp.com/cart'
            }
        }
    )
 
    # Redirect customer to checkout
    return redirect(intent.url)

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
from flask import Flask, redirect, request
 
app = Flask(__name__)
 
@app.route('/create-checkout/<account_id>', methods=['POST'])
def create_checkout(account_id):
    # Create a checkout link for an existing customer
    intent = pl.Intent.create(
        type='checkout_link',
        checkout_link={
            'payment_template': {
                'amount': 100.00,
                'description': 'Order #12345',
                'receiver': {
                    'account_id': 'acct_receiver123'
                },
                'sender': {
                    'account_id': account_id
                }
            },
            'redirects': {
                'completed_url': 'https://yourapp.com/payment-complete',
                'return_url': 'https://yourapp.com/cart'
            }
        }
    )
 
    # Redirect customer to checkout
    return redirect(intent.url)

Configuring Checkout Options

Checkout links support the same configuration options as the Checkout Plugin, allowing you to control payment methods, fees, billing 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')
 
# Configure allowed payment methods
intent = pl.Intent.create(
    type='checkout_link',
    checkout_link={
        'checkout_options': {
            'allowed_methods': {
                'card': 'enabled',
                'bank_account': 'disabled',
                'apple_pay': 'enabled',
                'google_pay': 'enabled'
            }
        },
        'payment_template': {
            'amount': 100.00,
            'description': 'Order #12345',
            'receiver': {
                'account_id': 'acct_receiver123'
            }
        },
        'redirects': {
            'completed_url': 'https://yourapp.com/payment-complete',
            'return_url': 'https://yourapp.com/cart'
        }
    }
)
 
checkout_url = intent.url

This configuration:

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

Convenience Fees

Add a convenience fee to offset payment processing costs:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Add a convenience fee
intent = pl.Intent.create(
    type='checkout_link',
    checkout_link={
        'checkout_options': {
            'enable_sender_fee': 'enabled'
        },
        'payment_template': {
            'amount': 100.00,
            'description': 'Order #12345',
            'receiver': {
                'account_id': 'acct_receiver123'
            }
        },
        'redirects': {
            'completed_url': 'https://yourapp.com/payment-complete',
            'return_url': 'https://yourapp.com/cart'
        }
    }
)
 
checkout_url = intent.url

This adds a convenience fee based on your processing account's fee configuration. The fee is calculated and displayed to the customer before they complete the payment.

Editable Amount

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

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Allow customers to change the payment amount
intent = pl.Intent.create(
    type='checkout_link',
    checkout_link={
        'checkout_options': {
            'allow_editable_amount': True
        },
        'payment_template': {
            'amount': 50.00,
            'description': 'Donation',
            'receiver': {
                'account_id': 'acct_receiver123'
            }
        },
        'redirects': {
            'completed_url': 'https://yourapp.com/payment-complete',
            'return_url': 'https://yourapp.com/donate'
        }
    }
)
 
checkout_url = intent.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

Autopay Enrollment

Enable the Autopay toggle to let customers enroll in automatic billing:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Enable Autopay enrollment
intent = pl.Intent.create(
    type='checkout_link',
    checkout_link={
        'checkout_options': {
            'show_autopay_toggle': True
        },
        'payment_template': {
            'amount': 100.00,
            'description': 'Order #12345',
            'receiver': {
                'account_id': 'acct_receiver123'
            },
            'sender': {
                'account_id': 'acct_customer456',
                'method': {
                    'account_defaults': {
                        'paying': 'payments'
                    }
                }
            }
        },
        'redirects': {
            'completed_url': 'https://yourapp.com/payment-complete',
            'return_url': 'https://yourapp.com/cart'
        }
    }
)
 
checkout_url = intent.url

This configuration:

• Shows an Autopay enrollment checkbox in the checkout form
• Automatically saves the payment method and links it to the customer account
• Sets the payment method as the default for future automatic payments

Handling Payment Completion

After a customer completes payment via a checkout link, they are redirected to the completed_url you specified when creating the intent. The URL includes a pl_transaction_id query parameter containing the transaction ID.

Redirect URL Structure

When a customer completes payment, they are redirected to:

https://yourapp.com/payment-complete?pl_transaction_id=txn_abc123def456

Processing the Transaction ID

Handle the redirect and retrieve transaction details:

import payload
from flask import Flask, request, render_template
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
app = Flask(__name__)
 
 
@app.route('/payment-complete')
def payment_complete():
    # Extract transaction ID from query parameter
    transaction_id = request.args.get('pl_transaction_id')
 
    # Fetch the transaction details
    transaction = pl.Transaction.get(transaction_id)
 
    # Verify the payment status
    if transaction.status == 'processed':
        # Payment successful
        # Update your database, fulfill the order, send confirmation email
        print(f'Payment successful: {transaction.id}')
        print(f'Amount: ${transaction.amount}')
 
        return render_template('success.html', transaction=transaction)
    else:
        # Payment not completed
        return render_template('payment_pending.html')

This example:

1. Extracts the pl_transaction_id from the query parameters
2. Fetches the transaction details from the Payload API
3. Verifies the payment status
4. Updates your database and fulfills the order

Tracking Payment Status

After sharing a checkout link, if needed 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 Intent Status

You can also retrieve the intent to check its status:

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Query the intent status
intent = pl.Intent.get('intent_abc123')
 
print(f'Intent ID: {intent.id}')
print(f'Intent Type: {intent.type}')
print(f'Checkout URL: {intent.url}')
 
# Check if payment was completed
if hasattr(intent, 'transaction_id') and intent.transaction_id:
    print(f'Payment completed: {intent.transaction_id}')
 
    # Fetch transaction details
    transaction = pl.Transaction.get(intent.transaction_id)
    print(f'Transaction status: {transaction.status}')
else:
    print('Payment not yet completed')

Schema Reference

The following fields are available when configuring the Checkout Link intent. For complete API reference documentation, see Intent API Reference.

Intent Configuration

Configuration options passed when creating the checkout link intent on your backend:

Next Steps

Enhance your checkout implementation

Create Customer Accounts

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

Handle Refunds

Process refunds and voids for cancellations and returns after payments complete.

Monitor Payment Events

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

Related articles

• Checkout Plugin - Embedded checkout form alternative
• Intents API Reference
• Transactions API Reference
• Payment Methods API Reference