Synthetic Account Payment Methods

Learn about synthetic account payment methods for embedded banking, virtual balances, and internal fund management

Synthetic account payment methods represent virtual balance accounts maintained within the Payload system rather than linked to external bank accounts or cards. These accounts enable embedded banking functionality including wallet systems, store credits, escrow balances, and instant payouts to external bank accounts. Synthetic accounts provide fast, fee-free transfers between accounts on your platform and instant transfers to external bank accounts while maintaining accurate balance tracking and transaction history.

What Are Synthetic Accounts?

Synthetic accounts are virtual payment methods that enable embedded banking within your platform, with balances stored entirely within Payload's system.

Unlike traditional payment methods that link to external financial institutions:

• No External Link: Balances exist only within your platform, not tied to banks or card networks
• Virtual Funds: Track internal credits, wallet balances, or escrow funds
• Instant Transfers: Move funds between synthetic accounts instantly, and send instant payouts to external bank accounts in seconds
• Zero Processing Fees: Internal transfers incur no card or bank transfer fees
• Platform Control: You manage funding, withdrawals, and balance adjustments

Synthetic accounts act as internal ledgers, enabling you to build embedded banking features like wallet systems, marketplace escrow, loyalty programs, and other closed-loop payment ecosystems.

Key Characteristics

• Balance Tracking: Maintains available balance for transactions
• Two-Way Transfers: Support for both sending and receiving funds
• Instant Settlement: Instant internal transfers and instant payouts to external bank accounts
• No Verification: No external validation required
• Transaction History: Complete audit trail of all balance changes

Common Use Cases

Customer Wallets

Enable customers to maintain balances for fast checkout and instant withdrawals. Customers fund wallets via card or bank transfer, use balance for fee-free purchases, and withdraw instantly to their bank account.

Marketplace Escrow

Hold buyer payments in escrow and release funds to sellers instantly when transactions complete. Control fund release, deduct platform fees, and handle refunds automatically.

Store Credits and Gift Cards

Issue refunds as store credits, sell gift cards, award promotional credits, and manage loyalty points. Retain revenue by keeping funds within your platform.

Instant Payouts

Fund synthetic accounts to send instant payouts to external bank accounts. See Instant Payouts for complete implementation guide.

Balance Management

Understanding how synthetic account balances work is essential for implementation.

Available Balance

The available balance represents funds ready for use:

• Current Funds: Amount available for transactions right now
• Real-Time Updates: Balance updates immediately when transactions process
• Transaction-Based: Balance changes through credit and debit transactions
• Read-Only Property: Balance cannot be set directly, only modified through transactions

Modifying Balances

Synthetic account balances are modified by funding it via transactions.

• Increase Balance
• Decrease Balance

import payload
# Placeholder account IDs for examples
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
synthetic_account_id = 'acct_synthetic123'
source_account_id = 'acct_source123'
 
 
# Add funds to synthetic account
pl.Transaction.create(
    type='payment',
    amount=100.0,
    description='Customer wallet deposit',
    sender={
        'account_id': source_account_id  # Account providing funds
    },
    receiver={
        'method_id': synthetic_account_id  # Synthetic account receiving funds
    }
)

import payload
 
# Placeholder account IDs for examples
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
synthetic_account_id = "acct_synthetic123"
destination_account_id = "acct_receiver123"
 
 
# Remove funds from synthetic account
pl.Transaction.create(
    type="payout",
    amount=50.0,
    description="Administrative fee",
    sender={"method_id": synthetic_account_id},  # Synthetic account being debited
    receiver={"account_id": destination_account_id},  # Account receiving funds
)

Clearing Timeline:

• Credit transactions to synthetic accounts typically follows your configured funding speed
• Monitor clearing with webhooks or by checking the synthetic account's available balance
• Plan funding in advance to ensure balance availability for time-sensitive operations
• Consider automated refill schedules for predictable funding

Withdrawals to External Destinations

Transfer synthetic account balance to external bank accounts instantly or via standard processing:

Transaction flow:

1. Verify sufficient synthetic account balance
2. Initiate payout to external bank account
3. Debit synthetic account
4. Process external transfer (instantly with clearing_timing: 'instant' or 1-3 days standard)
5. Recipient receives funds in their bank account

Creating Synthetic Accounts

Create synthetic accounts programmatically via the Payment Method API.

• Basic Account
• Customer Wallet
• Promotional Credit

synthetic_account = pl.PaymentMethod.create(
    type="synthetic",
    account_id="acct_1234567890",
    transfer_type="two_way",
    description="Customer Wallet"
)
 
print(synthetic_account.id)
# Output: pm_abc123xyz

# Step 1: Create the wallet (starts with $0 balance)
wallet = pl.PaymentMethod.create(
    type="synthetic",
    account_id="acct_1234567890",
    transfer_type="two_way",
    account_holder="John Doe",
    description="Customer Wallet - John Doe"
)
 
# Step 2: Fund the wallet via payment transaction
pl.Transaction.create(
    type="payment",
    amount=100.0,
    description="Initial wallet funding",
    sender={
        "account_id": "acct_processing123"  # Your processing account
    },
    receiver={
        "method_id": wallet.id  # The newly created wallet
    }
)

# Step 1: Create promotional credit account
promo_credit = pl.PaymentMethod.create(
    type="synthetic",
    account_id="acct_1234567890",
    transfer_type="two_way",
    description="New Customer Promotion",
    keep_active=False  # Deactivate after first use
)
 
# Step 2: Credit the promotional amount
pl.Transaction.create(
    type="payment",
    amount=25.0,
    description="Welcome promotion credit",
    sender={
        "account_id": "acct_processing123"
    },
    receiver={
        "method_id": promo_credit.id
    }
)

Limitations and Considerations

Understand synthetic account limitations before implementation.

Technical Limitations

• Platform-Only: Balances only exist within your platform, can't be used elsewhere
• No External Network: Not linked to card networks or banking systems
• Manual Reconciliation: You're responsible for reconciling platform and bank balances
• No External Verification: No bank/card verification process available

Business Considerations

• Customer Expectations: Customers may expect FDIC insurance or other protections
• Liquidity Management: Must maintain sufficient bank balance to cover synthetic liabilities
• Fraud Exposure: Internal fraud harder to detect than external payment fraud

Operational Considerations

• Refund Handling: Decide policy for refunding to wallet vs original payment method
• Account Closure: Handle remaining balances when accounts close

Schema Reference

Complete synthetic payment method schema:

For complete field documentation, see:

• Payment Methods API Reference - Payment method API details
• Transactions API Reference - Transaction API for balance operations

Next Steps

Enhance your platform with embedded banking functionality and internal payment systems

Build Embedded Banking Features

Create Payment Method API synthetic accounts programmatically, implement Instant Payouts using synthetic accounts as funding sources, and send Payouts to recipients with standard bank transfers.

Manage Payment Methods

Learn about Payment Methods to understand all payment method types, explore Cards for card payment methods, and review Bank Accounts for bank account payment methods.

Process Transactions

Use Transaction API to process payments and manage balances, implement Recurring Payments for subscription billing, and handle Refunds to return funds to customers.

Related Articles

• Instant Payouts - Send instant payouts using synthetic accounts as funding sources
• Creating Synthetic Accounts - Create synthetic accounts via API
• Sending Payouts - Send standard bank transfer payouts to recipients
• Payment Methods - Overview of all payment method types
• Cards - Learn about card payment methods
• Bank Accounts - Learn about bank account payment methods
• Transactions API Reference - Transaction API for modifying synthetic account balances