Enrolling Payout Recipients via Back-End API

Learn how to create payment methods directly through the Payment Methods API

The Payment Methods API allows you to create bank account payment methods directly from your backend for payout recipients. This gives you full programmatic control over the enrollment flow and enables you to build custom workflows integrated with your application logic. Use the Payment Methods API when you need server-side enrollment processing, batch operations, or automated recipient onboarding.

Prerequisites

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

When to Use Back-End API

Use the Payment Methods API when you need direct, programmatic control over payouts enrollment from your backend. The API enables server-side enrollment flows where you manage the entire process through API calls.

By using the Back-End API, you handle enrollment data securely on your backend while Payload manages bank verification, compliance checks, and payout processing. You have complete control over enrollment timing, error handling, and integration with your business logic.

Common use cases

• Batch Enrollment Operations: Enroll multiple recipients programmatically
• Automated Onboarding: Create payment methods triggered by scheduled jobs or automated processes
• Custom Enrollment Flows: Build enrollment experiences tailored to your business needs
• Data Migration: Import existing bank accounts from other systems

Creating a Payment Method

Create a bank account payment method for receiving payouts with an account.

• Existing Account
• Inline Account

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a bank account payment method for an existing payout recipient account
 
payment_method = pl.PaymentMethod.create(
    type='bank_account',
    transfer_type='receive_only',
    account_id='acct_recipient123',
    bank_account={
        'account_number': '000123456789',
        'routing_number': '110000000',
        'account_type': 'checking'
    },
    account_holder='Jane Smith',
    account_defaults={
        'paying': 'payouts'
    }
)
 
print('Payment Method ID:', payment_method.id)
print('Linked to Account:', payment_method.account_id)

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create a bank account payment method with inline account creation
 
payment_method = pl.PaymentMethod.create(
    type="bank_account",
    transfer_type="receive_only",
    account={
        "name": "Jane Smith",
        "type": "customer",
        "entity": {
            "type": "individual",
            "legal_name": "John Smith",
            "country": "US",
            "phone_number": "1231231234",
            "tax_id": {"value": "123121234"},
            "address": {
                "address_line_1": "123 Example St",
                "city": "New York",
                "state_province": "NY",
                "postal_code": "11111",
            },
        },
    },
    bank_account={
        "account_number": "000123456789",
        "routing_number": "110000000",
        "account_type": "checking",
    },
    account_holder="Jane Smith",
    account_defaults={"paying": "payouts"},
)
 
print("Payment Method ID:", payment_method.id)
print("Account ID:", payment_method.account_id)
print("Account Number (last 4):", payment_method.bank_account["account_number"][-4:])

Retrieving Payment Method Details

Retrieve complete payment method details using the payment method ID.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve payment method details
 
payment_method_id = 'pm_abc123def456'
 
payment_method = pl.PaymentMethod.get(payment_method_id)
 
print('Payment Method ID:', payment_method.id)
print('Type:', payment_method.type)
print('Transfer Type:', payment_method.transfer_type)
print('Account Holder:', payment_method.account_holder)
if payment_method.bank_account:
    print('Bank:', payment_method.bank_name)
    print('Account (last 4):', payment_method.bank_account['account_number'][-4:])

This allows you to:

• Check the payment method type and transfer type
• View account holder information
• Access masked bank account details
• Retrieve associated account ID
• View verification status

Listing Payment Methods

Query payment methods by account, type, transfer type, or other filters.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# List payment methods for a payout recipient account
 
payment_methods = pl.PaymentMethod.filter_by(
    account_id='acct_recipient123',
    type='bank_account',
    transfer_type='receive_only'
).all()
for pm in payment_methods:
    print(f"Payment Method ID: {pm.id}")
    print(f"Account Holder: {pm.account_holder}")
    if pm.bank_account:
        print(f"Account (last 4): {pm.bank_account['account_number'][-4:]}")
    print("---")

This example:

• Filters payment methods by account ID
• Limits results to bank account type
• Only returns receive-only payment methods
• Supports pagination for large result sets

Use payment method listing to build recipient dashboards, manage enrollment records, and audit payment method data.

Transfer Types

Payment methods support different transfer types that control how they can be used:

• receive_only - Can only receive funds (ideal for payout recipients)
• send_only - Can only send funds (ideal for payment sources)
• two_way - Can both send and receive funds

For payouts enrollment, either receive_only or two_way will work depending on your use case. If you only intend to send payouts and not collect funds from the recipient, it's recommended to specify transfer_type='receive_only'. This prevents the payment method from being used to collect payments from the account holder. Use transfer_type='two_way' only if you need the flexibility to both send payouts and collect payments from the same payment method.

Account Defaults

The account_defaults configuration determines when this payment method is automatically used:

• paying='payouts' - Use for receiving payouts
• paying='payments' - Use for sending payments
• paying='all' - Use for both payouts and payments

For payouts enrollment, setting account_defaults.paying='payouts' or account_defaults.paying='all' will work. Use 'payouts' if this payment method should only be the default for receiving payouts, or use 'all' if it should also be the default for sending payments.

Schema Reference

The following fields are available when creating and configuring payment methods for payouts. For complete API reference, see Payment Methods API Reference.

Payment Method Configuration

Core fields used when creating bank account payment methods:

Next Steps

Enhance your payout recipient enrollment implementation

Send Payouts to Recipients

Start sending payouts to enrolled recipients using their stored bank account payment methods for seamless fund disbursement.

Monitor Enrollment Events

Subscribe to webhook notifications to receive real-time updates when payout recipients are enrolled, payment methods are created, or verification status changes.

Manage Payment Methods

Use the Payment Methods API to retrieve, update, and manage enrolled payout recipient bank accounts and set default payment methods.

Related articles

• Enrollment Link - Hosted enrollment page alternative
• Enrollment Form - Embedded enrollment form alternative
• Payment Methods API Reference
• Accounts API Reference
• Creating Accounts