Sending Payouts via API

Learn how to send money securely to any person or account using the Transaction API

The Payout API enables you to send money directly to bank accounts, payment methods, or customer accounts. Send vendor payments, commission payouts, refunds, or account-to-account transfers programmatically through your backend. The API provides full control over payout flows.

Prerequisites

Before sending payouts through the API, it's helpful to learn about the following topics.

When to Use Payout API

Use the Payout API when you need to send money programmatically to recipients. The Transaction API enables server-side payout flows where you manage the entire disbursement lifecycle through API calls.

By using the Payout API, you handle recipient data securely on your backend while Payload manages compliance, banking network communication, and settlement processing. You have complete control over payout timing, amounts, and integration with your business logic.

Common use cases

• Vendor Payments: Pay suppliers, contractors, and service providers programmatically
• Commission Payouts: Disburse earnings to sales teams, affiliates, and partners
• Refund Processing: Send refunds directly to customer bank accounts
• Marketplace Disbursements: Pay sellers and service providers on multi-sided platforms
• Account-to-Account Transfers: Move funds between your own accounts or customer wallets
• Batch Payout Operations: Process multiple payouts programmatically
• Scheduled Disbursements: Send payouts triggered by scheduled jobs or business events

Sending a Payout

Send a payout by creating a transaction with type payout and referencing a saved payment method.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Send a payout using a saved payment method
transaction = pl.Transaction.create(
    type='payout',
    amount=1250.00,
    description='Commission payout for Q4 2024',
    notes='Internal: Processed via automated quarterly payout system',
    order_number='PAYOUT-2024-Q4-001',
    sender={
        'account_id': 'acct_processing123'
    },
    receiver={
        'method_id': 'pm_recipient456'
    }
)
 
print(f"Transaction ID: {transaction.id}")
print(f"Status: {transaction.status}")
print(f"Amount: ${transaction.amount}")
print(f"Description: {transaction.description}")

This example creates a payout transaction with:

1. type='payout' specifies this is a payout transaction
2. amount sets the payout amount in dollars
3. description provides context about the payout purpose (appears on recipient statements)
4. notes adds internal record-keeping details (not visible to recipient)
5. order_number links the payout to your internal order or reference ID
6. sender.account_id identifies your processing account sending funds
7. receiver.method_id references a saved payment method for the recipient

The response includes transaction details with status showing the payout processing state (processing, processed, or rejected). The recipient account is automatically determined from the payment method.

Optional Fields

• description: Context about the payout that may appear on bank statements (subject to bank formatting)
• notes: Internal notes for record-keeping, reporting, and customer support (not visible to recipient)
• order_number: Your internal reference ID for linking payouts to orders or invoices

Including these fields improves record-keeping, enables better reporting, and provides context for reconciliation and support inquiries.

Using Default Payment Methods

Send a payout to an account using its default payout payment method by referencing only the account ID.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Send a payout using the account's default payout method
transaction = pl.Transaction.create(
    type='payout',
    amount=750.00,
    sender={
        'account_id': 'acct_processing123'
    },
    receiver={
        'account_id': 'acct_recipient789'
    }
)
 
print(f"Transaction ID: {transaction.id}")
print(f"Status: {transaction.status}")
print(f"Amount: ${transaction.amount}")

This example:

1. Sets receiver.account_id to specify the recipient account
2. Does not specify receiver.method_id - the default payout method is used automatically
3. The account must have a payment method configured with account_defaults.paying='payouts' or 'all'
4. Simplifies payout flows when recipients have default methods configured

When a payment method is set as the default for payouts on an account, you can send payouts by referencing only the account ID. The system automatically uses the configured default payment method.

Retrieving Payout Details

Retrieve complete payout transaction details using the transaction ID.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Retrieve a payout transaction by ID
transaction = pl.Transaction.get('txn_payout123')
 
print(f"Transaction ID: {transaction.id}")
print(f"Type: {transaction.type}")
print(f"Status: {transaction.status}")
print(f"Amount: ${transaction.amount}")
print(f"Created: {transaction.created_at}")
print(f"Est. Clear Date: {transaction.est_cleared_date}")

This allows you to:

• Check the current payout status
• Retrieve recipient and payment method details
• View estimated clearing dates
• Access transaction timestamps and processing details
• Get sender and receiver account information

Listing Payouts

Query payout transactions by account, status, or other filters.

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# List payout transactions from your processing account
transactions = pl.Transaction.filter_by(
    sender={'account_id': 'acct_processing123'},
    type='payout',
    status={'value': 'processed'}
).all()
 
print(f"Found {len(transactions)} payout transactions")
for txn in transactions:
    print(f"  {txn.id}: ${txn.amount} - {txn.status}")

This example:

• Filters transactions by sender account ID (your processing account)
• Limits results to payout type transactions
• Only returns processed payouts
• Supports pagination for large result sets

Use payout listing to build reporting dashboards, reconcile disbursements, and analyze payout activity.

Schema Reference

The following fields are available when creating and configuring payout transactions. For complete API details, see the Transaction API Reference.

Payout Transaction Configuration

Core fields used when creating payout transactions:

Next Steps

Enhance your payout processing implementation

Enroll Payout Recipients

Set up recipients to receive payouts using Enrollment Link, Embedded Form, or Back-End API to collect and store bank account details.

Monitor Payout Events

Subscribe to webhook notifications to receive real-time updates about payout processing status, completions, and any rejections or issues.

Build Payout Reports

Use Transaction Reports and Payout Reports to track disbursement activity and reconcile payout data.

Related articles

• Payment API - Collect payments from customers
• Payment Methods - Manage payment methods
• Creating Accounts - Create recipient accounts
• Transactions API Reference