Inline Payment Methods in Transactions

Create payment methods inline during transaction processing

Payment methods can be provided inline in transaction creation requests, allowing you to process payments without separately creating and managing payment method objects. This approach simplifies one-time transactions while optionally allowing you to save the payment method for future use.

When to Use Inline Payment Methods

Use inline payment methods when customers don't need to save their payment details for future transactions:

• Guest checkout flows
• Single invoice payments
• One-time service payment
• Initial subscription purchases

Prerequisites

Before inline payment methods in transactions, familiarize yourself with these topics.

Why use Inline Payment Methods

Payment details provided directly in transaction creation:

transaction = pl.Transaction.create(
    type="payment",
    amount=100.0,
    sender={
        "method": {
            "type": "card",
            "card": {
                "card_number": "4111111111111111",
                "expiry": "12/25",
                "card_code": "123"
            }
        }
    },
    receiver={
        "account_id": "acct_processing123"
    }
)

Benefits:

• Single API call for payment processing
• No orphaned payment method objects
• Simpler error handling
• Faster checkout for one-time payments

Limitations:

• Payment details must be collected for each transaction
• No payment method reuse without additional configuration

Inline Payment Methods

Create transactions with inline payment method details.

• Card Payment
• Bank Account Payment

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Process payment with inline card payment method
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 100.00,
        "sender": {
            "method": {
                "type": "card",
                "card": {
                    "card_number": "4111111111111111",
                    "expiry": "12/25",
                    "card_code": "123",
                },
                "billing_address": {"postal_code": "12345"},
            }
        },
        "receiver": {"account_id": "acct_processing123"},
    }
)
 
print(f"Transaction ID: {transaction.id}")
print(f"Status: {transaction.status}")
print(f"Payment Method: {transaction.sender.method.description}")

print(transaction.sender.method.description)  # "Visa x-1111"
print(transaction.sender.method.id)  # "pm_abc123"

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Process payment with inline bank payment method
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 100.00,
        "sender": {
            "method": {
                "type": "bank_account",
                "bank_account": {
                    "account_number": "123456789",
                    "routing_number": "110000000",
                    "account_type": "checking",
                },
            }
        },
        "receiver": {"account_id": "acct_processing123"},
    }
)
 
print(f"Transaction ID: {transaction.id}")
print(f"Status: {transaction.status}")
print(f"Payment Method: {transaction.sender.method.description}")

print(transaction.status.value)  # "pending"
print(transaction.sender.method.description)  # "Checking x-6789"

Reusing Inline Payment Methods

Inline payment methods are automatically saved for future use by default.

Using Saved Payment Methods

By default, inline payment methods remain active and can be reused (keep_active: true):

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Process payment with inline card
# Payment method is automatically saved for reuse (keep_active: True by default)
transaction = pl.Transaction.create(
    {
        "type": "payment",
        "amount": 100.00,
        "sender": {
            "method": {
                "type": "card",
                "card": {
                    "card_number": "4111111111111111",
                    "expiry": "12/25",
                    "card_code": "123",
                },
                "billing_address": {"postal_code": "12345"},
                "account_holder": "John Doe",
                # keep_active: True is the default - payment method will be saved
            }
        },
        "receiver": {"account_id": "acct_processing123"},
    }
)
print(transaction.sender["method"])
print(f"Transaction ID: {transaction.id}")
print(f"Payment Method ID: {transaction.sender['method'].id}")
print(f"Saved for Reuse: {transaction.sender['method'].keep_active}")

When payment methods are kept active (default behavior):

1. Transaction processes with the inline payment method
2. Payment method is automatically saved and assigned a unique ID
3. Future transactions can reference the saved payment method ID

Schema Reference

Payment method fields used when inline in transactions:

Card Payment Method

Bank Account Payment Method

Account Holder Information

For complete field documentation, see:

• Transaction API Reference - All transaction fields, properties, and methods
• Payment Method API Reference - All payment method fields and properties

Next Steps

Enhance payment processing and payment method management

Process Transactions

Use Payment API to process payments with inline payment methods, monitor Transaction Status to track processing, and set up Transaction Webhooks to receive real-time transaction updates for asynchronous bank payments.

Manage Payment Methods

Learn about Payment Methods for full payment method management, implement Payment Method Verification to validate bank accounts and cards, and use Testing Payment Methods to test payment flows with test data.

Handle Payment Scenarios

Handle Payment Declines to recover from declined payments, process Voids and Refunds to reverse and refund transactions, and set up Recurring Payments to implement automatic billing with saved payment methods.

Related articles

• Payment API - Transaction processing with payment methods
• Payment Methods - Payment method management
• Transaction Webhooks - Real-time transaction updates
• Transaction Status - Transaction lifecycle
• Transactions API Reference - Transaction API details
• Payment Methods API Reference - Payment method API details