Creating Payment Methods via API

Learn how to create and manage payment methods programmatically through the Payment Method API

The Payment Method API allows you to create, update, and manage payment methods directly through your backend. This provides full control over payment method creation and enables you to build custom payment flows, batch operations, and integrations with your application logic. Use the Payment Method API when you need programmatic control over payment method management or server-to-server payment flows.

Prerequisites

Before creating payment methods through the API, it's helpful to learn about the following topics.

When to Use Payment Method API

Use the Payment Method API when you need direct, programmatic control over payment method creation and management from your backend. The API enables server-side payment method flows where you manage the entire payment method lifecycle through API calls.

The Payment Method API receives raw payment data through your backend and immediately tokenizes it for secure storage. While your server temporarily handles sensitive data during API calls, you must maintain PCI DSS compliance, use HTTPS, and never log or store raw payment information. Payload handles tokenization, validation, and secure storage after creation. You maintain complete control over payment method creation timing, account association, and integration with your business logic.

Common use cases

• Backend Payment Method Management: Create and manage payment methods server-side
• Batch Operations: Create multiple payment methods programmatically
• Migration from Other Systems: Import existing payment methods
• Custom Payment Flows: Build payment method experiences tailored to your needs

Creating Payment Methods

Create payment methods by providing card or bank account details.

• Card
• Bank Account

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a card payment method
payment_method = pl.PaymentMethod.create(
    type='card',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    account_id='acct_customer123'
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Description: {payment_method.description}")
print(f"Status: {payment_method.status}")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a bank account payment method
payment_method = pl.PaymentMethod.create(
    type='bank_account',
    account_holder='John Doe',
    bank_account={
        'account_number': '123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_id='acct_customer123'
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Bank Name: {payment_method.bank_name}")
print(f"Account Type: {payment_method.bank_account['account_type']}")
print(f"Status: {payment_method.status}")

Adding Account Holder Information

Include account holder name and details when creating payment methods.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a card payment method with account holder name
payment_method = pl.PaymentMethod.create(
    type='card',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    account_holder='John Doe',
    account_id='acct_customer123'
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Account Holder: {payment_method.account_holder}")

This example includes:

1. account_holder sets the name on the payment method
2. For cards, this is the cardholder name
3. For bank accounts, this is the account holder name
4. Helps with validation and record-keeping

Including account holder information improves payment processing success rates and provides better context for customer support and reconciliation.

Adding Billing Address

Include billing address information for address verification (AVS) and validation.

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a card payment method with billing address
payment_method = pl.PaymentMethod.create(
    type='card',
    card={'card_number': '4111111111111111', 'expiry': '12/25', 'card_code': '123'},
    account_holder='John Doe',
    billing_address={
        'address_line_1': '123 Main St',
        'address_line_2': 'Apt 4B',
        'city': 'San Francisco',
        'state_province': 'CA',
        'postal_code': '94102',
        'country_code': 'US',
    },
    account_id='acct_customer123',
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Billing Postal Code: {payment_method.billing_address['postal_code']}")

This example includes:

1. billing_address.postal_code is required for AVS verification
2. billing_address.address_line_1 provides the street address
3. billing_address.city, state_province, and country_code complete the address
4. Address verification helps reduce fraud and improve authorization rates

Billing addresses are used during payment processing to verify the cardholder's identity and reduce fraudulent transactions.

Setting Account Defaults

Configure payment methods as defaults for specific transaction types.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment method and set it as default for payments
payment_method = pl.PaymentMethod.create(
    type='card',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    account_id='acct_customer123',
    account_defaults={
        'paying': 'payments'  # Set as default for payment transactions
    }
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Default for Payments: {payment_method.account_defaults['paying']}")
 
# Create another payment method as default for payouts
payout_method = pl.PaymentMethod.create(
    type='bank_account',
    account_holder='John Doe',
    bank_account={
        'account_number': '123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_id='acct_customer123',
    account_defaults={
        'paying': 'payouts'  # Set as default for payout transactions
    }
)
 
print(f"Payout Method ID: {payout_method.id}")
print(f"Default for Payouts: {payout_method.account_defaults['paying']}")

This example configures:

1. account_defaults.paying sets defaults for payment and payout transactions
2. Use 'payments' for default payment method
3. Use 'payouts' for default payout method
4. Use 'all' to set as default for both payment types

When a payment method is set as a default, transactions can reference only the account ID without specifying a payment method ID, simplifying API calls.

Controlling Payment Method Reuse

Control whether payment methods can be reused for future transactions.

• Reusable (Default)
• Single-Use

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a reusable payment method (keep_active defaults to true)
payment_method = pl.PaymentMethod.create(
    type='card',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    account_id='acct_customer123'
    # keep_active: true is the default - payment method remains active
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Status: {payment_method.status}")
print("Can be reused: Yes (keep_active defaults to true)")

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a single-use payment method
payment_method = pl.PaymentMethod.create(
    type='card',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    account_id='acct_customer123',
    keep_active=False  # Payment method will be deactivated after first use
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Status: {payment_method.status}")
print("Single-use: Yes (keep_active: false)")

Specifying Transfer Type

Control the allowed transfer directions for payment methods.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a payment method for payouts only
payout_method = pl.PaymentMethod.create(
    type='bank_account',
    account_holder='John Doe',
    bank_account={
        'account_number': '123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_id='acct_customer123',
    transfer_type='receive_only'  # Can only receive payouts, not make payments
)
 
print(f"Payment Method ID: {payout_method.id}")
print(f"Transfer Type: {payout_method.transfer_type}")
 
# Create a payment method for payments only
payment_method = pl.PaymentMethod.create(
    type='card',
    card={
        'card_number': '4111111111111111',
        'expiry': '12/25',
        'card_code': '123'
    },
    account_id='acct_customer123',
    transfer_type='send_only'  # Can only make payments, not receive payouts
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Transfer Type: {payment_method.transfer_type}")

This example configures:

1. transfer_type='two_way' allows both sending and receiving funds (default)
2. transfer_type='send_only' only allows payments from this method
3. transfer_type='receive_only' only allows payouts to this method

Transfer type restrictions help manage payment method usage and enforce business rules about which payment methods can be used for specific transaction types.

Schema Reference

The following fields are available when creating and managing payment methods:

Payment Method Configuration

Core fields used when creating payment methods:

Card Payment Method

Fields required for card payment methods:

Bank Account Payment Method

Fields required for bank account payment methods:

Billing Address

Fields for billing address information:

Account Defaults

Fields for configuring default payment methods:

For complete field documentation, see:

• Payment Methods API Reference - All payment method fields, properties, and methods

Next Steps

Enhance payment processing and payment method management

Process Transactions

Use Payment API to process payments with saved payment methods, send Payouts to payment methods, and create Inline Payment Methods during transactions.

Verify and Manage Payment Methods

Implement Payment Method Verification to verify bank accounts and cards, use Updating Payment Methods to modify existing payment methods, and explore Payment Method Types to understand different payment method options.

Build User Interfaces

Create Payment Method Form for embedded payment method collection, integrate Checkout Plugin for complete checkout experiences, and build Payment Form interfaces for custom payment flows.

Related articles

• Payment Methods - Overview of payment methods
• Payment Method Types - Card payment methods
• Payment Method Types - Bank account payment methods
• Payment Methods API Reference - Complete API reference