Setting Default Payment Methods

Learn when and how to configure payment methods as defaults for various transaction types

When creating or updating payment methods on an account, you can configure which transaction types should automatically use that payment method by setting the account_defaults property. This allows you to specify whether a payment method should be used for payments, payouts, deposits, withdrawals, or combinations of these operations.

Prerequisites

Before working with default payment methods, it's helpful to learn about the following topics.

When to use account_defaults

Use the account_defaults configuration when you need to designate which payment method should be automatically selected for specific transaction types. This is particularly important for:

Common use cases

• Enabling Autopay for recurring billing and invoice payments on customer accounts
• Setting up a default payout method for recipients (vendors, partners) to receive outbound payments
• Configuring separate payment methods for different transaction directions (e.g., one card for payments, one bank account for payouts)
• Configuring different funding methods for deposits versus withdrawals on processing accounts (useful for escrow situations where debits are not allowed on deposit accounts)
• Streamlining checkout flows by pre-selecting the appropriate payment method based on transaction type

Understanding account_defaults

The account_defaults object contains two properties that control which transaction types use the payment method as the default:

Paying Operations

The paying property specifies which types of paying transactions should use this payment method by default. Paying transactions are the initiating transactions that can use either cards or bank accounts, and work with any account type (customer, processing, or generic).

• payments - Use this payment method for collecting payments from the account holder (money flowing to you)
• payouts - Use this payment method for sending credits to the account holder (money flowing to them)
• all - Use this payment method for both payments and payouts

When a payment method is set as the default for payments, it will be automatically used for any automatic invoice payments and Autopay operations.

Funding Operations (Processing Accounts Only)

The funding property specifies which types of funding transactions should use this payment method by default. Funding transactions are restricted to processing accounts only and represent the result of paying transactions from opposing accounts.

• deposits - Use this payment method for receiving funds into the processing account (when payments are collected)
• withdraws - Use this payment method for pulling funds from the processing account (when payouts are sent)
• all - Use this payment method for both deposits and withdrawals

Configuring Default Payment Methods

Below are examples of setting payment methods as defaults for different transaction types.

• Autopay Default
• Payout Default
• Bidirectional Default
• Funding Default

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a card payment method and set as default for payments
payment_method = pl.PaymentMethod.create(
    type='card',
    account_id='acct_1a2b3c4d5e6f',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    billing_address={
        'postal_code': '12345'
    },
    account_defaults={
        'paying': 'payments'
    }
)
 
print(f"Created payment method: {payment_method.id}")
print(f"Default for payments: {payment_method.account_defaults['paying']}")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a bank account and set as default for payouts
payment_method = pl.PaymentMethod.create(
    type='bank_account',
    account_id='acct_processing123',
    bank_account={
        'account_number': '000123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_holder='Merchant Business Inc',
    account_defaults={
        'paying': 'payouts'
    }
)
 
print(f"Created payment method: {payment_method.id}")
print(f"Default for payouts: {payment_method.account_defaults['paying']}")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a bank account for both payments and payouts
payment_method = pl.PaymentMethod.create(
    type='bank_account',
    account_id='acct_1a2b3c4d5e6f',
    bank_account={
        'account_number': '000123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_holder='John Doe',
    account_defaults={
        'paying': 'all'
    }
)
 
print(f"Created payment method: {payment_method.id}")
print(f"Default for: {payment_method.account_defaults['paying']}")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a bank account for funding operations on a processing account
payment_method = pl.PaymentMethod.create(
    type='bank_account',
    account_id='acct_processing123',
    bank_account={
        'account_number': '000123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_holder='Merchant Business Inc',
    account_defaults={
        'funding': 'all'
    }
)
 
print(f"Created payment method: {payment_method.id}")
print(f"Default for funding: {payment_method.account_defaults['funding']}")

Updating Default Payment Methods

You can change which payment method is the default for specific transaction types by updating the account_defaults property on payment methods.

Replacing a default payment method

When you set a payment method as the default for a transaction type, any other payment method that was previously the default will be automatically updated to no longer be the default for that type.

For example:

1. Payment Method A is set with account_defaults.paying='payments'
2. You create or update Payment Method B with account_defaults.paying='payments'
3. Payment Method A's account_defaults.paying is automatically set to null
4. Payment Method B is now the default for payments

This ensures that only one payment method is the default for each transaction type at any time.

Removing default status

To remove default status from a payment method without setting a new default, set the relevant account_defaults properties to null:

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Remove default status from a payment method
payment_method = pl.PaymentMethod.get('pm_1a2b3c4d5e6f')
 
payment_method.update(account_defaults={'paying': None, 'funding': None})
 
print(f"Updated payment method: {payment_method.id}")
print(f"No longer a default for any operations")

account_defaults Schema

The schema below defines the structure of the account_defaults object on payment methods.

Next Steps

Enable automated billing, set up payment routing, and build comprehensive payment flows

Configure Autopay and Recurring Billing

Learn how default payment methods enable automatic invoice payments with Autopay Overview, guide customers through setting up autopay using Autopay Enrollment, create Billing Schedules for recurring charges, and generate Invoices that use default payment methods.

Manage Payment Methods

Add new payment methods to accounts with Creating Payment Methods, modify existing configurations using Updating Payment Methods, and explore all supported options with Payment Method Types.

Build Payment and Payout Flows

Process one-time or recurring payments with Creating Payment Intents, send outbound payouts to recipients using Creating Transfers with their configured default payout methods, and understand the complete Payment Processing lifecycle and status handling.

Configure Automated Funding

Set up Automated Funding to automatically transfer funds when paying transactions occur on processing accounts, use Dynamic Funding to split payment funds across multiple processing accounts, and configure funding strategies for marketplace commission splitting.

Related articles

• Payment Methods API Reference
• Accounts API Reference
• Accounts Overview
• Autopay Webhooks - Monitor Autopay events