Updating Payment Methods via API

Learn how to update existing payment methods programmatically through the Payment Method API

The Payment Method API allows you to update non-sensitive details of existing payment methods. While you cannot change the actual payment credentials (card numbers, account numbers), you can update billing information, default settings, descriptions, and other metadata. This enables you to maintain accurate customer payment information without requiring customers to re-enter their payment details.

Prerequisites

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

When to Update Payment Methods

Use the Payment Method API to update payment methods when you need to modify non-sensitive details without requiring customers to re-enter their full payment information. Common scenarios include address changes, updating default payment method settings, or correcting customer information.

Common use cases

• Address Updates: Customer moves or needs to update billing address
• Default Payment Method Changes: Set or change which payment method is used by default
• Metadata Management: Update custom attributes or tags for internal tracking
• Account Holder Name Corrections: Fix typos or update names without re-entering card details

Updating Billing Address

Update the billing address associated with a payment method.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Update payment method billing address
payment_method = pl.PaymentMethod.get('pm_1234567890')
 
payment_method.update(
    billing_address={
        'address_line_1': '456 New St',
        'address_line_2': 'Suite 200',
        'city': 'Los Angeles',
        'state_province': 'CA',
        'postal_code': '90001',
        'country_code': 'US'
    }
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Updated Address: {payment_method.billing_address.address_line_1}")
print(f"Postal Code: {payment_method.billing_address.postal_code}")

This example updates:

1. billing_address.address_line_1 - Street address
2. billing_address.city - City name
3. billing_address.state_province - State or province
4. billing_address.postal_code - ZIP or postal code
5. billing_address.country_code - Country code (US, CA, etc.)

Updating billing addresses is useful when customers move or need to correct address information for Address Verification System (AVS) checks.

Updating Account Defaults

Configure or change which payment method is used as the default for an account.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Set payment method as default for payments
payment_method = pl.PaymentMethod.get('pm_1234567890')
 
payment_method.update(
    account_defaults={
        'paying': 'payments'  # Set as default for payment transactions
    }
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Default for: {payment_method.account_defaults['paying']}")
 
# Update to be default for both payments and payouts
updated = pl.PaymentMethod.get('pm_1234567890')
 
updated.update(
    account_defaults={
        'paying': 'all'  # Default for both
    }
)
 
print(f"Now default for: {updated.account_defaults['paying']}")
 
# Remove default status
removed = pl.PaymentMethod.get('pm_1234567890')
 
removed.update(
    account_defaults={
        'paying': None  # Remove default status
    }
)
 
print(f"Default status removed: {removed.account_defaults['paying'] is None}")

This example configures:

1. account_defaults.paying: 'payments' - Set as default for collecting payments
2. account_defaults.paying: 'payouts' - Set as default for sending payouts
3. account_defaults.paying: 'all' - Set as default for both payments and payouts
4. account_defaults.paying: null - Remove default status

When you set a payment method as the default, any previously set default for that transaction type is automatically removed.

Updating Description and Metadata

Add or modify descriptive information and custom metadata.

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Update payment method description and metadata
payment_method = pl.PaymentMethod.get("pm_1234567890")
 
payment_method.update(
    description="Primary Work Card",
    attrs={
        "category": "business",
        "department": "sales",
        "expense_code": "EXP-2024-001",
    },
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Description: {payment_method.description}")
print(f"Metadata: {payment_method.attrs}")

This example updates:

1. description - Human-readable label for the payment method
2. metadata - Custom key-value pairs for internal tracking

Descriptions help customers identify payment methods in your interface (e.g., "Work Visa", "Personal Checking"). Metadata enables you to store additional context like customer preferences or internal identifiers.

Updating Account Holder Name

Correct or update the account holder name without re-entering payment credentials.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Update account holder name
payment_method = pl.PaymentMethod.get('pm_1234567890')
 
payment_method.update(
    account_holder='Jane Smith-Doe'
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Account Holder: {payment_method.account_holder}")

This is useful for:

• Correcting typos in customer names
• Updating names after marriage or legal name changes
• Standardizing name formats across payment methods

Updating Multiple Fields

Update multiple payment method fields in a single API call.

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Update multiple payment method fields in one API call
payment_method = pl.PaymentMethod.get("pm_1234567890")
 
payment_method.update(
    # Update billing address
    billing_address={
        "address_line_1": "456 New St",
        "city": "Los Angeles",
        "state_province": "CA",
        "postal_code": "90001",
        "country_code": "US",
    },
    # Set as default payment method
    account_defaults={"paying": "all"},
    # Update description
    description="Primary payment method",
    # Update account holder
    account_holder="Jane Smith",
    # Add metadata
    attrs={"preferred": True, "category": "business"},
)
 
print(f"Payment Method ID: {payment_method.id}")
print(f"Updated Address: {payment_method.billing_address.postal_code}")
print(f"Default for: {payment_method.account_defaults['paying']}")
print(f"Description: {payment_method.description}")
print(f"Account Holder: {payment_method.account_holder}")

You can update any combination of non-sensitive fields in a single request:

• Billing address
• Account defaults
• Description
• Metadata
• Account holder name
• Transfer type

Handling Update Errors

Handle validation errors and conflicts when updating payment methods.

try:
    payment_method = pl.PaymentMethod.get("pm_1234567890")
 
    payment_method.update(
        billing_address={
            "postal_code": "94102",
            "country_code": "US"
        }
    )
 
    print("Payment method updated:", payment_method.id)
except Exception as error:
    print("Error type:", getattr(error, "error_type", None))
    print("Error description:", getattr(error, "error_description", None))
    print("Error details:", getattr(error, "details", None))
 
    if getattr(error, "error_type", None) == "InvalidAttributes":
        print("Validation failed:", error.details)
    else:
        print("Update failed:", getattr(error, "error_description", str(error)))

Common error responses:

For more information on error handling, see Errors API Reference.

Schema Reference

The following fields can be updated for existing payment methods:

Updatable Fields

Fields that can be modified after payment method creation:

Billing Address Fields

All billing address fields can be updated:

Account Defaults Fields

Configure default payment method behavior:

For complete field documentation, see:

• Payment Methods API Reference - All payment method fields and update operations

Next Steps

Enhance payment processing and payment method management

Process Transactions

Use Payment API to process payments with updated payment methods, send Payouts using updated bank accounts, and set up Recurring Payments with updated defaults for subscriptions.

Manage Payment Methods

Create new payment methods with Payment Method API, implement Payment Method Verification to verify updated bank accounts, and explore Payment Methods for overview of management options.

Build User Interfaces

Create Payment Method Form to let customers update their own payment methods, build Payment Form for processing immediate payments, and integrate Checkout Plugin for complete checkout experiences.

Related articles

• Payment Methods - Overview of payment methods
• Creating Payment Methods - Create new payment methods via API
• Payment Method Verification - Verify payment methods
• Payment Methods API Reference - Complete API reference