Skip to main content

Set up PayPal accounts

PayPal's sandbox environment provides developers with testing accounts to simulate real payment scenarios without processing actual transactions. PayPal sandbox provides testing environments with two main account types:

Personal accounts​

Personal accounts are for customers or buyers in transactions. Use these to simulate different customer behaviors, payment methods, and verification statuses.

Business accounts​

Business accounts are for merchants or sellers and include API credentials for payment processing. These accounts handle transaction settlement and provide access to merchant tools.

When you register as a PayPal developer, the PayPal sandbox automatically creates:

  • A business account: For example, pp.merch01-facilitator@example.com (with API credentials)
  • A personal account: For example, pp.merch01-buyer@example.com (for buyer testing)

Some PayPal transactions involve multiple buyer-seller pairs. For example, Parallel payments and Adaptive payments require two separate business accounts, each for different purposes. In such cases, you'll need to create additional sandbox business accounts to represent each party involved in the transaction.

Additionally, there is a provision for bulk account management.

Individual account setup​

Create Personal Account​

Use personal accounts to simulate different types of customers in your payment flows.

Setup steps:

  1. Log in to the Developer Dashboard
  2. Navigate to PayPal sandbox → Accounts
  3. Select Create Account
  4. Set Account Type to Personal
  5. Select your target Country
  6. Select Create Account

Create Business Account​

Business accounts provide API credentials and merchant functionality for processing payments.

Setup steps:

  1. Navigate to PayPal sandbox → Accounts in the Developer Dashboard
  2. Select Create Account
  3. Set Account Type to Business
  4. Select your business Country
  5. Select Create Account

Duplicate Existing Accounts​

Clone accounts when you need similar configurations with minor variations.

Duplication process:

  1. Locate the account you want to duplicate
  2. Select the Manage Accounts (⚙️) next to the account you want to manage
  3. Select Duplicate Account
  4. Modify any fields you want to change
  5. Select Create Account

Bulk account upload​

Bulk account upload is used to create up to 40 accounts at once, which is useful for testing complex scenarios or creating multiple accounts efficiently.

When to Use Bulk Upload​

  • Testing payment flows with multiple customer types
  • Simulating verified and unverified users
  • Setting up international payment testing
  • Creating comprehensive test suites
  • Configuring various merchant scenarios

File Preparation for Bulk Upload​

Step 1: Download the template

Download the official sandbox-bulk-headers.csv template to ensure proper formatting.

Step 2: Configure account data

Fill in the required fields for each account:

FieldDescriptionExamples
country_codeTwo-letter country codeUS, GB, CA, DE
account_typeAccount typeBusiness, Personal
primary_email_aliasUnique email addressbuyer1@test.com
passwordAccount passwordTestBuy123!
first_nameAccount holder first nameJohn, Maria, Alex
last_nameAccount holder last nameSmith, Garcia, Chen
ppBalancePayPal balance (0-100000)1000, 5000, 25000
addBankBank verification statusY, N
ccTypeCredit card typeVisa, Mastercard, Amex
payment_cardPayment methodPayPal, Discover

Step 3: File format requirements

  • Encoding: UTF-16 Little Endian (Excel's "Unicode Text" format)
  • Extension: .txt or .csv
  • Size: Maximum 1 MB
  • Accounts: 1-40 account rows
  • Separator: Comma-separated values

Sample Configuration​

country_code,account_type,primary_email_alias,password,first_name,last_name,ppBalance,addBank,ccType,payment_card
US,PERSONAL,verified-buyer@test.com,BuyTest1!,John,Smith,5000,Y,VISA,PAYPAL
US,PERSONAL,unverified-buyer@test.com,BuyTest2!,Jane,Doe,1000,N,MASTERCARD,PAYPAL
US,BUSINESS,merchant1@test.com,MerchTest1!,Business,Owner,10000,Y,VISA,DISCOVER
GB,PERSONAL,uk-buyer@test.com,UKTest1!,David,Wilson,2000,Y,MAESTRO,PAYPAL

Upload Process​

Upload steps:

  1. Navigate to Developer Dashboard → PayPal sandbox → Bulk Accounts
  2. Select "Upload File" or "Choose File"
  3. Select your prepared CSV file
  4. Select "Upload"
  5. Review validation results
  6. Fix any errors and re-upload if needed

Account and password management​

Change account password​

  1. Go to PayPal sandbox → Accounts
  2. Select the manage icon ⚙️ for your target account
  3. Select "View/Edit Account"
  4. Select "Change password" in the Profile tab
  5. Enter a new password following the security requirements
  6. Select "Save"

Password requirements​

  • 8-10 characters long
  • Mixed uppercase and lowercase letters
  • At least one number or symbol (!, @, #, $, %, ^)
  • No four or more repeated characters (avoid 1111, abcd)

Account linking​

Connect pre-existing PayPal sandbox accounts to your developer account:

  1. Navigate to the PayPal sandbox → Accounts page
  2. Select the authentication link for the account type
  3. Enter your existing PayPal sandbox account credentials
  4. Confirm successful account linking

Note: Accounts already linked to another developer account cannot be re-linked.

Account deletion​

Remove unwanted test accounts:

  1. Locate the account in your accounts list
  2. Select the manage icon (⚙️)
  3. Select Delete
  4. Confirm the deletion

Protected Accounts: You cannot delete the default -facilitator and -buyer accounts created during registration.

Validation and requirements​

File validation rules​

PayPal validates bulk upload files using these criteria:

Data integrity:

  • All required fields must be completed
  • Field values must match expected data types
  • Country codes must be valid 2-letter formats
  • Card types must be compatible with the selected countries

Uniqueness:

  • Each email address must be unique within the file
  • Email addresses must be available in the PayPal sandbox environment

Dependencies:

  • Credit card types must be valid for the specified country
  • All contextual relationships must be correct

Common validation errors​

File format issues:

  • Incorrect encoding (must be UTF-16LE)
  • Not a valid file extension
  • File size exceeds 1 MB
  • More than 40 account rows

Data issues:

  • Duplicate email addresses
  • Not valid country codes
  • Passwords not meeting security requirements
  • Incompatible card types for countries

Testing scenarios setup​

Basic payment flow testing​

Create account pairs:

  • 1 verified personal account (buyer)
  • 1 business account (merchant)
  • Test successful payment transactions

Configuration example:

Buyer: verified-customer@test.com (Personal, US, $5000 balance, Bank: Y, Card: VISA)
Merchant: test-merchant@test.com (Business, US, $10000 balance, API credentials)

Error scenario testing​

Insufficient funds testing:

  • Personal account with low balance ($50)
  • Attempt transactions exceeding the balance

Unverified account testing:

  • Personal account with addBank: N
  • Test verification prompts and limitations

International testing​

Multi-Country setup:

  • US accounts for domestic testing
  • GB accounts for international scenarios
  • CA accounts for cross-border transactions
  • Test currency conversion and regional payment methods

Best practices​

Account planning strategy​

Start simple:

  1. Use default accounts for initial integration testing
  2. Create 2-3 additional accounts for basic scenarios
  3. Expand to bulk upload for comprehensive testing

Organize by purpose:

  • Name accounts clearly: verified-buyer-us, unverified-buyer-gb
  • Document account purposes and test scenarios
  • Group accounts by testing phase or feature

Security considerations​

Credential management:

  • Store account credentials securely
  • Use unique passwords for each account
  • Regularly rotate passwords for long-term projects

Environment separation:

  • Keep PayPal sandbox credentials separate from production
  • Use different email patterns for easy identification
  • Document which accounts are for which testing phases

Documentation maintenance​

Account documentation:

  • Record account purposes and configurations
  • Track which accounts are used for which test scenarios
  • Maintain a mapping of accounts to test cases

Quick start actions​

Next steps​

  1. Verify default accounts: Log into your auto-generated accounts at sandbox.paypal.com
  2. Test basic flow: Execute a simple payment between your default buyer and merchant accounts
  3. Create additional account: Set up one custom account for your specific testing needs
  4. Document credentials: Save all account emails and passwords securely

Ready for advanced testing​

After your accounts are set up, you're ready to:

  • Configure webhooks for real-time event handling
  • Test various payment methods and currencies
  • Integrate with third-party platforms and plugins
  • Develop comprehensive automated test suites

Your PayPal sandbox accounts provide the foundation for thorough PayPal integration testing across all scenarios your application will encounter in production.