Pay
Instant Payouts

Instant Payouts with Real-Time Payments

Learn how to send money instantly to recipients using RTP through synthetic accounts

Instant payouts enable you to send funds to recipients with immediate availability using Real-Time Payments (RTP). Unlike standard bank transfer payouts that settle in 1-3 business days, instant payouts transfer funds within seconds, providing recipients with immediate access to their money. This is achieved by funding a synthetic account and using it as the source for instant transfer transactions.

Prerequisites

Before setting up instant payouts, ensure you have the necessary infrastructure configured.

Payout enrollment with embedded form

Learn how to collect recipient payment methods using Payload's embeddable form components.

Payout enrollment via API

Learn how to create and manage recipient payment methods programmatically through the API.

When to Use Instant Payouts

Use instant payouts when recipients need immediate access to funds and there's available float to pre-fund your synthetic account. Instant payouts are ideal for time-sensitive disbursements where waiting 1-3 days for standard bank transfer settlement is not acceptable.

Real-Time Payments provide immediate fund availability, appearing in the recipient's account within seconds of transfer initiation. This enables use cases that require instant liquidity while maintaining the security and compliance of traditional payment rails.

Benefits of instant payouts

  • Improved Experience: Recipients access their money instantly without waiting for bank transfer clearing
  • Time-Critical Payments: Support emergency disbursements and urgent payment needs
  • Better Cash Flow: Recipients can use funds immediately for purchases or bill payments
  • 24/7 Operation: Send payouts any time, including weekends and holidays

Common use cases

  • Gig Economy Platforms: Instant driver or delivery worker payouts after shift completion
  • Freelance Marketplaces: Immediate payment to contractors upon project approval
  • Emergency Disbursements: Urgent payments for time-sensitive situations
  • Cashout Features: Allow users to instantly withdraw earnings or wallet balances
  • Commission Payments: Real-time affiliate or sales commission disbursements
  • Insurance Claims: Instant claim payouts for faster customer satisfaction
  • Customer Refunds: Immediate refund processing for urgent situations

How Instant Payouts Work

Instant payouts use a multi-step process involving synthetic accounts as intermediary funding sources.

The Instant Payout Flow

Setup Processing Infrastructure

Create a processing account for your organization and enroll payout recipients with verified payment methods.

Create Synthetic Account

Create a synthetic account linked to your processing account. This account serves as the funding source for instant payouts.

Fund the Synthetic Account

Transfer funds from your processing account to the synthetic account. Wait for funds to clear (typically next business day) and monitor clearing status via webhooks or balance queries.

Send Instant Payout

Create a payout transaction with clearing_timing: 'instant', reference the synthetic account as the sender, and specify the recipient's payment method. Funds transfer in real-time via RTP network.

Monitor Transfer Status

Track payout processing via webhooks, confirm successful delivery to recipient, and handle any transfer failures or rejections.

Creating and Funding Synthetic Accounts

Synthetic accounts serve as the intermediary funding source for instant payouts.

Create Synthetic Account

Create a synthetic account linked to your processing account:

create-synthetic-account.py
PythonRubyPHPNode.jsC#JavaShell
import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
synthetic_account = pl.PaymentMethod.create(
 
# Create a synthetic account for instant payouts
# Synthetic accounts always start with $0 balance
    type='synthetic',
    account_id='acct_processing123',
    transfer_type='two_way',
    description='Instant Payout Funding Account'
)
 
print(f"Synthetic Account ID: {synthetic_account.id}")
print("Initial Balance: $0.00")
print(f"Transfer Type: {synthetic_account.transfer_type}")
print("Use credit transaction to fund this account")

This example creates a synthetic account with:

  • Initial balance of $0 (balance will be added via funding transaction)
  • transfer_type: 'two_way' to allow both receiving funds and sending payouts
  • Description identifying the account purpose (optional)

Fund the Synthetic Account

Transfer funds into the synthetic account from your processing account:

fund-synthetic-account.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Fund the synthetic account from processing account
funding_transaction = pl.Transaction.create(
    type='payout',
    amount=10000.00,
    description='Fund instant payout account',
    sender={'account_id': 'acct_processing123'},
    receiver={'method_id': 'pm_synthetic_abc'},
)
 
print(f"Funding Transaction ID: {funding_transaction.id}")
print(f"Status: {funding_transaction.status}")
print(f"Amount: ${funding_transaction.amount}")
print("Note: Funds will clear by next business day")

This transaction:

  • Credits the synthetic account with the specified amount
  • Uses type: 'payment' to fund the synthetic account
  • Funds are pulled from the processing account's default payment method
  • Funds clear by the next business day

Monitoring Synthetic Account Balance

Before sending instant payouts, verify the synthetic account has sufficient cleared funds.

Check Available Balance

Query the synthetic account to check available funds:

check-balance.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
synthetic_account = pl.PaymentMethod.get('pm_synthetic_abc')
 
# Check synthetic account balance
 
print(f"Synthetic Account ID: {synthetic_account.id}")
print(f"Available Balance: ${synthetic_account.synthetic['balance']['available']}")
print(f"Transfer Type: {synthetic_account.transfer_type}")
 
if synthetic_account.synthetic.balance.available > 0:
    print("âś“ Funds are available for instant payouts")
else:
    print("âš  Waiting for funds to clear")

This retrieves:

  • Current available balance
  • Balance ready for instant payout transactions
  • Real-time balance reflecting all cleared transactions

Monitor Clearing with Webhooks

Subscribe to webhooks to get notified when funds clear. The transaction:operation:clear event fires when your funding transaction completes and the funds are available for instant payouts. See Webhook Integration below for complete webhook handler examples.

Sending Instant Payouts

Once the synthetic account has cleared funds, send instant payouts to recipients.

Create Instant Payout Transaction

Send an instant payout using the funded synthetic account:

send-instant-payout.py
PythonRubyPHPNode.jsC#JavaShell
import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Send instant payout from synthetic account to recipient
instant_payout = pl.Transaction.create(
    type='payout',
    clearing_timing='instant',
    amount=500.00,
    description='Commission payout - Week 23',
    sender={
        'method_id': 'pm_synthetic_abc'
    },
    receiver={
        'method_id': 'pm_recipient456'
    }
)
 
print(f"Transaction ID: {instant_payout.id}")
print(f"Status: {instant_payout.status}")
print(f"Amount: ${instant_payout.amount}")
print(f"Clearing: {instant_payout.clearing_timing}")
print("Funds will be available in recipient account within seconds")

This transaction:

  • Uses clearing_timing: 'instant' to trigger Real-Time Payment processing
  • References the synthetic account as the sender payment method
  • Specifies the recipient's payment method
  • Includes description for recipient bank statement
  • Funds appear in recipient account within seconds

Verification Before Payout

Always verify sufficient balance before attempting instant payouts:

verify-balance.py
PythonRubyPHPNode.jsC#JavaShell
import sys
 
import payload
 
# Placeholder account IDs for examples
pl = payload.Session('secret_key_3bW9...', api_version='v2')
synthetic_account = pl.PaymentMethod.get('pm_synth3bW9...')
recipient_payment_method_id = 'pm_recipt3bW9...'
 
# Verify sufficient balance before instant payout
available_balance = synthetic_account.synthetic.balance.available
payout_amount = 500.0
 
if available_balance >= payout_amount:
    # Sufficient balance - proceed with instant payout
    transaction = pl.Transaction.create(
        {
            'type': 'payout',
            'clearing_timing': 'instant',
            'amount': payout_amount,
            'sender': {'method_id': synthetic_account.id},
            'receiver': {'method_id': recipient_payment_method_id},
            'description': 'Instant payout',
        }
    )
 
    print(f"Instant payout created: {transaction.id}")
else:
    print(f"Insufficient balance: {available_balance} < {payout_amount}", file=sys.stderr)
    # Handle insufficient balance - refill account or use standard payout

Handling Instant Payout Results

Handle instant payout failures gracefully with automatic fallback to standard payouts:

error-handling.py
PythonRubyPHPNode.jsC#JavaShell
import payload
# Placeholder account IDs for examples
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
processing_account_id = 'acct_processing123'
synthetic_account_id = 'acct_synthetic123'
 
 
import sys
 
try:
    # Attempt instant payout
    transaction = pl.Transaction.create({
        'type': 'payout',
        'clearing_timing': 'instant',
        'amount': 500.0,
        'sender': {
            'method_id': synthetic_account_id
        },
        'receiver': {
            'method_id': recipient_payment_method_id
        },
        'description': 'Instant payout'
    })
 
    print(f"Instant payout successful: {transaction.id}")
except Exception as error:
    print(f"Instant payout failed: {error}", file=sys.stderr)
 
    # Fallback to standard payout
    try:
        fallback_transaction = pl.Transaction.create({
            'type': 'payout',
            'clearing_timing': 'next_day',  # Standard bank transfer
            'amount': 500.0,
            'sender': {
                'account_id': processing_account_id
            },
            'receiver': {
                'method_id': recipient_payment_method_id
            },
            'description': 'Standard payout (instant fallback)'
        })
 
        print(f"Fallback payout created: {fallback_transaction.id}")
    except Exception as fallback_error:
        print(f"Fallback payout also failed: {fallback_error}", file=sys.stderr)
        # Alert support team

Common Rejection Reasons

Instant payouts may be rejected for various reasons:

  • Insufficient Balance: Synthetic account lacks sufficient funds
  • Invalid Account: Recipient payment method is invalid or closed
  • Limit Exceeded: Transaction exceeds instant transfer limits
  • Verification Required: Recipient account requires additional verification

Refilling Synthetic Accounts

Maintain synthetic account balances to ensure instant payout availability.

Monitoring Balance Thresholds

Implement automatic refilling when balance drops below threshold:

monitor-balance.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
# Placeholder account IDs for examples
pl = payload.Session('secret_key_3bW9...', api_version='v2')
synthetic_account = pl.PaymentMethod.get('pm_synth3bW9...')
 
processing_account_id = 'acct_processing123'
 
 
# Check synthetic account balance
available_balance = synthetic_account.synthetic['balance'].available
threshold = 1000.0  # Minimum balance threshold
 
if available_balance < threshold:
    # Refill synthetic account
    refill_amount = 10000.0 - available_balance
 
    pl.Transaction.create(
        {
            'type': 'payment',
            'amount': refill_amount,
            'description': 'Automatic synthetic account refill',
            'sender': {'account_id': processing_account_id},
            'receiver': {'method_id': synthetic_account.id},
        }
    )
 
    print(f"Synthetic account refilled with ${refill_amount}")

Scheduled Refills

Set up automated refills using billing schedules for reliable, recurring funding:

Refill synthetic account daily

Create a billing schedule that automatically funds the synthetic account every day:

daily-refill.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
# Placeholder account IDs for examples
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
processing_account_id = "acct_processing123"
synthetic_account_id = "acct_synthetic123"
 
 
# Create daily refill schedule
refill_schedule = pl.BillingSchedule.create(
    {
        "description": "Daily synthetic account refill",
        "payer": {
            "account_id": processing_account_id  # Your processing account that funds the synthetic
        },
        "biller": {"method_id": synthetic_account_id},  # Synthetic account receiving funds
        "recurring_schedule": {"type": "daily"},
        "items": [
            {
                "type": "line_item",
                "line_item": {"value": 5000.0},  # Refill with $5,000 daily
                "description": "Daily instant payout account funding",
            }
        ],
        "start_date": "2024-01-15",  # When to start refilling
    }
)
 
print(f"Daily refill schedule created: {refill_schedule.id}")

This creates a billing schedule that automatically credits $5,000 to the synthetic account every day, ensuring consistent funding for instant payouts.

Refill synthetic account weekly

Create a billing schedule that funds the synthetic account once per week:

weekly-refill.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
# Placeholder account IDs for examples
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
processing_account_id = "acct_processing123"
synthetic_account_id = "acct_synthetic123"
 
 
# Create weekly refill schedule
refill_schedule = pl.BillingSchedule.create(
    {
        "description": "Weekly synthetic account refill",
        "payer": {"account_id": processing_account_id},
        "biller": {"method_id": synthetic_account_id},
        "recurring_schedule": {"type": "weekly"},  # Repeats every 7 days from start_date
        "items": [
            {
                "type": "line_item",
                "line_item": {"value": 25000.0},  # Refill with $25,000 weekly
                "description": "Weekly instant payout account funding",
            }
        ],
        "start_date": "2024-01-15",  # First refill and weekly anchor date
    }
)
 
print(f"Weekly refill schedule created: {refill_schedule.id}")

This schedule credits $25,000 every week starting from the specified start date, providing consistent weekly funding aligned with your payout cycles.

Refill synthetic account monthly

Create a billing schedule that funds the synthetic account on a specific day each month:

monthly-refill.py
PythonRubyPHPNode.jsC#JavaShell
import payload
 
# Placeholder account IDs for examples
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
processing_account_id = "acct_processing123"
synthetic_account_id = "acct_synthetic123"
 
 
# Create monthly refill schedule (1st of each month)
refill_schedule = pl.BillingSchedule.create(
    {
        "description": "Monthly synthetic account refill",
        "payer": {"account_id": processing_account_id},
        "biller": {"method_id": synthetic_account_id},
        "recurring_schedule": {
            "type": "monthly",
            "monthly": {"billing_day": 1},  # Bill on the 1st of each month
        },
        "items": [
            {
                "type": "line_item",
                "line_item": {"value": 100000.0},  # Refill with $100,000 monthly
                "description": "Monthly instant payout account funding",
            }
        ],
        "start_date": "2024-01-01",
    }
)
 
print(f"Monthly refill schedule created: {refill_schedule.id}")

This schedule credits $100,000 on the 1st of each month, suitable for high-volume instant payout operations.

Benefits of billing schedule refills:

  • Automatic, hands-off funding without manual intervention
  • Predictable cash flow management
  • Consistent synthetic account balance
  • Integrates with existing billing infrastructure
  • Webhook notifications when refills process

Webhook Integration

Use webhooks to automate instant payout workflows and monitoring.

Detect when synthetic account funding completes

webhook-funding-cleared.py
PythonRubyPHPNode.jsC#JavaShell
import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
from flask import Flask, request
 
app = Flask(__name__)
 
synthetic_account_id = 'pm_synthetic_abc'
 
@app.route('/webhooks/payload', methods=['POST'])
def handle_webhook():
    # Parse webhook payload
    event = request.json
 
    if (
        event['trigger'] == 'transaction' and
        event['triggered_on']['value'] == 'cleared'
    ):
        # Fetch the full transaction details
        transaction = pl.Transaction.get(event['triggered_on']['id'])
 
        if (
            transaction.type == 'payment' and
            transaction.receiver.method_id == synthetic_account_id
        ):
            print(f"Synthetic account funded: {transaction.amount}")
 
            # Enable instant payouts
            enable_instant_payouts()
 
            # Process pending instant payout requests
            process_pending_payouts()
 
    return 'OK', 200
 
if __name__ == '__main__':
    app.run(port=5000)

Monitor instant payout completion

webhook-payout-completed.py
PythonRubyPHPNode.jsC#JavaShell
import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
from flask import Flask, request
 
app = Flask(__name__)
 
@app.route('/webhooks/payload', methods=['POST'])
def handle_webhook():
    # Parse webhook payload
    event = request.json
 
    if (
        event['trigger'] == 'transaction' and
        event['triggered_on']['value'] == 'cleared'
    ):
        # Fetch the full transaction details
        transaction = pl.Transaction.get(event['triggered_on']['id'])
 
        if (
            transaction.type == 'payout' and
            transaction.clearing_timing == 'instant'
        ):
            # Notify recipient
            notify_recipient(transaction.receiver.account_id, {
                'transaction_id': transaction.id,
                'amount': transaction.amount,
                'status': 'completed'
            })
 
            # Update internal records
            update_payout_status(transaction.id, 'completed')
 
    return 'OK', 200
 
if __name__ == '__main__':
    app.run(port=5000)

Handle instant payout failures

webhook-payout-failed.py
PythonRubyPHPNode.jsC#JavaShell
import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
from flask import Flask, request
import sys
 
app = Flask(__name__)
 
@app.route('/webhooks/payload', methods=['POST'])
def handle_webhook():
    # Parse webhook payload
    event = request.json
 
    if (
        event['trigger'] == 'transaction' and
        event['triggered_on']['value'] == 'rejected'
    ):
        # Fetch the full transaction details
        transaction = pl.Transaction.get(event['triggered_on']['id'])
 
        if transaction.clearing_timing == 'instant':
            print(f"Instant payout failed: {transaction.status_message}", file=sys.stderr)
 
            # Attempt fallback to standard payout
            fallback_to_standard_payout(transaction)
 
            # Notify support team
            alert_support({
                'transaction_id': transaction.id,
                'reason': transaction.status_message
            })
 
    return 'OK', 200
 
if __name__ == '__main__':
    app.run(port=5000)

Troubleshooting

Common issues and solutions when implementing instant payouts.

Insufficient Balance Error

Symptoms: Instant payout fails with insufficient balance error.

Solutions:

  • Verify synthetic account balance before creating transaction
  • Implement automatic refilling when balance drops below threshold
  • Add buffer amount to account for pending transactions

Synthetic Account Funding Rejected

Symptoms: Transaction to fund synthetic account is rejected.

Solutions:

  • Verify processing account has sufficient balance
  • Check payment method attached to processing account is valid and active
  • Ensure funding amount is within transaction limits
  • Review rejection reason in transaction status for specific error
  • Verify processing account is in good standing

Schema Reference

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

Instant Payout Transaction Configuration

type
enum[string]Immutable
The type of transaction being processed. This determines the direction and nature of funds movement, such as payment collection, refund issuance, credit disbursement, or account funding operations.
Values: payment, deposit, withdraw, refund, payout
clearing_timing
enum[string]Immutable
The clearing speed for this transaction, determining how quickly funds are made available to the recipient. Instant clearing makes funds available immediately, same_day within the same business day, and next_day by the following business day. Defaults to next_day if not specified. Same-day and instant are only available in certain circumstances.
Values: instant, same_day, next_day
amount
number (double)
The monetary amount for this transaction in the currency of the processing account. This value is always positive and represents the total value being transferred, collected, or refunded. The amount is rounded to two decimal places for display.
description
string
A human-readable description of what this transaction is for. This text provides context about the purchase, service, or payment purpose and may be displayed to customers on receipts and in transaction histories.
Max length: 128
sender
object
Information about the sender party in this transaction, including the account and payment method from which funds are being sent or debited. For payment transactions, this is the account being charged. For payout transactions, this is the processing account sending funds.
accountAccount
object
The expanded account object for the sender. When included, this provides the full details of the account sending funds in this transaction.
Visibility: explicit
account_id ID of Account
stringImmutable
The unique identifier of the account sending or providing funds for this transaction. This is an optional field that references the account object that owns the sender payment method. (ID prefix: acct)
Pattern: ^acct_[A-Za-z0-9]+$
methodPaymentMethod
object
The expanded payment method object used by the sender. When included, this provides the full details of the payment method from which funds are being debited.
method_id ID of PaymentMethod
stringImmutable
The unique identifier of the payment method used by the sender. This references the payment method objectfrom which funds are being pulled or debited for this transaction. If not provided the account default will be used. (ID prefix: pm)
Pattern: ^pm_[A-Za-z0-9]+$
receiver
object
Information about the receiver party in this transaction, including the account and payment method to which funds are being sent or credited. For payment transactions, this is the processing account receiving funds. For payout transactions, this is the account receiving funds.
accountAccount
object
The expanded account object for the receiver. When included, this provides the full details of the account receiving funds in this transaction.
Visibility: explicit
account_id ID of Account
stringImmutable
The unique identifier of the account receiving funds for this transaction. This is an optional field that references the account object that owns the receiver payment method. (ID prefix: acct)
Pattern: ^acct_[A-Za-z0-9]+$
methodPaymentMethod
object
The expanded payment method object used by the receiver. When included, this provides the full details of the payment method to which funds are being credited.
method_id ID of PaymentMethod
stringImmutable
The unique identifier of the payment method used by the receiver. This references the payment method object to which funds are being sent or credited for this transaction. If not provided the account default will be used. (ID prefix: pm)
Pattern: ^pm_[A-Za-z0-9]+$
notes
string
Internal notes or comments about this transaction. This field is for record-keeping purposes and can contain any additional information that may be useful for reference, customer service, or accounting purposes.
Max length: 2048
order_number
string
Custom order or transaction number for this payment. Use this to link the payment to an order in your system or to provide a customer-facing transaction reference. Providing this value ensures duplicate protection is applied per order; .otherwise, duplicate protection applies across payments without an order reference. For check transactions this field contains the check number.
Max length: 64

Next Steps

Enhance your instant payout implementation

Enroll Payout Recipients

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

Monitor Instant Payout Events

Subscribe to webhook notifications to receive real-time updates when synthetic account funding clears and instant payouts complete or fail.

Understand Synthetic Accounts

Learn more about Synthetic Account Payment Methods to optimize your instant payout infrastructure and balance management strategies.

Related articles

Sending PayoutsDeclines