PayPal Sandbox - 2012 User Guide
Sandbox User Guide
Last updated: April 2012
PayPal Sandbox User Guide
Document Number: 100008.en_US-201204
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Chapter 1 Overview to the PayPal Sandbox . . . . . . . . . . . . . . 7
At a Glance: Differences between the Sandbox and Live PayPal . . . . . . . . . . . . . . . 7
Chapter 2 Accessing the PayPal Sandbox . . . . . . . . . . . . . . . 9
Signing Up for Sandbox Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Welcome to the PayPal Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Test Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Chapter 3 Setting Up Test Accounts . . . . . . . . . . . . . . . . . . 13
Planning the Types of Test Accounts You Need . . . . . . . . . . . . . . . . . . . . . . . 13
Managing Test Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Creating a Preconfigured Account. . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Verified Account Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Resetting a Preconfigured Account . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Creating a Test Account Manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Creating a PayPal Payments Pro Account. . . . . . . . . . . . . . . . . . . . . . . . . . 21
Adding a Funding Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Changing or Adding Additional Bank Accounts . . . . . . . . . . . . . . . . . . . . . 23
Adding Credit Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Generating a Credit Card Number to Test PayPal Account Optional . . . . . . . . . . 24
Chapter 4 Testing PayPal Website Features . . . . . . . . . . . . . . 27
Website Payments with Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Encrypted Website Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Testing Payments with Buy Now Button . . . . . . . . . . . . . . . . . . . . . . . . . 28
Verifying a Test Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Handling Pending Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Sandbox User Guide April 2012 3
Contents
Creating a Pending Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Completing or Canceling a Pending Transaction . . . . . . . . . . . . . . . . . . . . 29
Verifying a Test Refund . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Transferring Funds to a Test Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Clearing or Failing Test eCheck Transactions . . . . . . . . . . . . . . . . . . . . . . . . 31
Sending Funds to a Seller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Billing A Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 5 Testing an Express Checkout Integration . . . . . . . . . . 35
Chapter 6 Sandbox Test Tools . . . . . . . . . . . . . . . . . . . . .41
Instant Payment Notification Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Testing IPN Messages in the Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 7 Testing Error Conditions . . . . . . . . . . . . . . . . . .45
API Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Negative Testing Using an Amount-Related Trigger Field . . . . . . . . . . . . . . . . 48
Negative Testing Using a Non-Amount Trigger Field . . . . . . . . . . . . . . . . . . 49
Negative Testing With Multiple Messages . . . . . . . . . . . . . . . . . . . . . . . . 49
Testing Using AVS Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Testing an AVS Code Using Virtual Terminal . . . . . . . . . . . . . . . . . . . . . . 51
Testing an AVS Code Using DoDirectPayment . . . . . . . . . . . . . . . . . . . . . 52
Testing Using CVV Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Testing a CVV Code Using Virtual Terminal . . . . . . . . . . . . . . . . . . . . . . . 54
Testing a CVV Code Using DoDirectPayment . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 8 Testing Payment Review . . . . . . . . . . . . . . . . . .57
Chapter 9 Technical Support . . . . . . . . . . . . . . . . . . . . . .59
Contacting Customer Service for Live PayPal Website Help . . . . . . . . . . . . . . . . 59
Contacting Developer Technical Support for API Help. . . . . . . . . . . . . . . . . . . . 59
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
4 April 2012 Sandbox User Guide
Preface
This document describes the PayPal test environment called the Sandbox.
Intended Audience
This document is written for merchants and developers who want to test their PayPal-based
applications before using them in production.
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
Sandbox User Guide April 2012 5
Documentation Feedback
6 April 2012 Sandbox User Guide
Overview to the PayPal Sandbox
1
The PayPal Sandbox is a self-contained environment within which you can prototype and test
PayPal features and APIs. The PayPal Sandbox is an almost identical copy of the live PayPal
website. Its purpose is to give developers a shielded environment for testing and integration
purposes and to help avoid problems that might occur while testing PayPal integration
solutions on the live site. Before moving any PayPal-based application into production, you
should test the application in the Sandbox .
At a Glance: Differences between the Sandbox and Live PayPal
The following table compares the Sandbox and Live PayPal. This is an at-a-glance view of the
differences from the perspective of an in-house or third-party developer for a business.
You can also use this table as a checklist.
PayPal Sandbox Live PayPal Website and API Service
Type of PayPal
Accounts
Site logos in
upper left
corner
NVP API
Servers
SOAP API
Servers
Business roles You fill all roles you need to test: merchant,
Depending on the feature you want to develop
and test, you need a Personal, Business, or
Premier account.
https://www.sandbox.paypal.com
https://api.sandbox.paypal.com/ nvp
/
https://api.sandbox.paypal.com/ 2.0
/
buyer, and seller.
Personal, Business, or Premier account
https://www.paypal.com
For API Certificate security:
https://api.paypal.com/nvp/
For API Signature security:
https://api-3t.paypal.com/nvp/
For API Certificate security:
https://api.paypal.com/2.0/
For API Signature security:
https://api-3t.paypal.com/2.0/
Real-world people fill these roles.
Sandbox User Guide April 2012 7
Overview to the PayPal Sandbox
1
At a Glance: Differences between the Sandbox and Live PayPal
PayPal Sandbox Live PayPal Website and API Service
Company and
people’s names
and postal
addresses
Email
addresses and
email inboxes
Bank account
and credit card
numbers
Social Security
Number for
Billing
Agreements
PayPal
transactions
Completely fictitious. Before you begin
working with the Sandbox, create the details
for all the business roles you must fulfill.
The Sandbox simulates verification of postal
addresses and names.
The Sandbox has a special-purpose email
inbox for your testing, contained in the
Sandbox itself.
The Sandbox creates bank accounts, credit
card numbers, and CVV2 numbers you need in
order to develop and test; all of which are
fictitious and only used within the Sandbox.
The Sandbox simulates the verification of
these numbers. Transactions do not affect real
accounts and actual money is never
exchanged.
nn-nnnn Real social security numbers
111-
The Sandbox creates all fictitious bank
accounts, credit card numbers, and CVV2
numbers you need for development and
testing. The Sandbox simulates the verification
of these numbers.
Real companies’ and people’s names and
postal addresses.
Real email address and inbox for each business
role
Actual verification of bank account numbers,
credit card numbers, and CVV2 numbers
Live transactions, cleared by live PayPal
processes
Fraud
detection
Digital
certificates
PayPal
Merchant
Features
supported
8 April 2012 Sandbox User Guide
Fraud detection is not enabled for the Sandbox. Full protection through PayPal’s fraud
detection
After you request digital certificates for use
with the PayPal Web Services API, the
Sandbox automatically generates them. They
are available for immediate downloading.
All features of the live PayPal website, except
closing an account, auction features, monthly
statements, shipping preferences, and PayPal
Shops.
To safeguard your and your customers’
security, requests for digital certificates for use
with the Live PayPal Web Services API must
be verified by PayPal before they are issued.
You are notified in email when your request
has been approved.
Accessing the PayPal Sandbox
2
To access the PayPal Sandbox, sign up for an account at https://developer.paypal.com. After
signing up, you access the Sandbox either programmatically or by logging in.
Depending on the PayPal feature you want to test with an application, you need to set up
different types of test accounts: PayPal Personal (or Premier) and Business accounts. See
“Planning the Types of Test Accounts You Need” on page 13.
Signing Up for Sandbox Access
To sign up for Sandbox access:
1. Go to
2. If you already have an account, enter your Log In Email and Password and click Log In.
3. If you do not already have an account, click Sign Up Now and provide the requested
https://developer.paypal.com. The log in screen is shown below:
information shown below:
Sandbox User Guide April 2012 9
Accessing the PayPal Sandbox
2
Signing Up for Sandbox Access
IMPORTANT: Do not use the same log in email address or password that you use for
logging into the live paypal.com site because later you may allow
someone to work in the Sandbox on your behalf but not want to allow
access to your regular PayPal account.
After you sign up, PayPal sends login instructions to the email address you used to sign-up.
If you have mail filtering enabled in your mail software, the email sent by PayPal might be
filtered out or stored in a folder where you are not expecting it to be. For instance, with
Microsoft Outlook mail software, your filtering might cause the email to be stored in
“Junk” or “Spam.”
4. Respond to the confirmation e-mail and log in.
10 April 2012 Sandbox User Guide
Welcome to the PayPal Sandbox
When you log in to the Sandbox, the Sandbox Test Environment home page appears, as
follows:
Accessing the PayPal Sandbox
Welcome to the PayPal Sandbox
2
On this page, you can perform the following actions:
Create test accounts. You can create and manage test accounts from the Test Accounts tab.
From this tab, you can also enter the Sandbox Test Site, which simulates the live
paypal.com site. For more information, see “Setting Up Test Accounts” on page 13.
Access email sent to test accounts from the Test Email tab. For more information, see
“Test Email” on page 12.
View API credentials for business test accounts from the API Credentials tab. An API
signature, which is the preferred kind of credential, is automatically created when you
create a Business test account. You need the information on this tab when you test APIs.
Obtain technical information about PayPal products and APIs using the Help link.
Simulate Instant Payment Notifications using a test tool. For more information, see
“Sandbox Test Tools” on page 41.
Change the log in password using the Profile link.
NOTE: You cannot change the Log In Email address.
Sandbox User Guide April 2012 11
Accessing the PayPal Sandbox
2
Test Email
Test Email
When certain kinds of transactions occur in the live PayPal system, PayPal sends email
messages to the real email addresses of the participants. From these email messages, the
recipient or initiator of an event or transaction can verify that the event took place and that the
monetary amounts associated with the event are correct.
PayPal test email, however, is a self-contained email system in the Sandbox itself. You see
email messages addressed only to the Sandbox test accounts you set up. Up to 30 of the latest
email messages are listed on the Test Email tab. The subject line of email messages you have
not read are in bold. Click a subject line to read the message.
12 April 2012 Sandbox User Guide
Setting Up Test Accounts
3
Depending on the business application you are developing and testing, you need different
types of test accounts. There are two types of test accounts: Personal (or Premier) and
Business.
Planning the Types of Test Accounts You Need
Determine the types of test accounts you need to test the applications you are developing. In
addition, determine the number of different accounts you need. Typically, you create at least
one seller (Business) account and one buyer (Personal or Premier) account. You might need
several different Personal or Business PayPal test accounts to test your application.
When you create a test account, the following information is generated for you:
Mailing address
Email address and password for the test PayPal account. You can specify the same
password (not email address) for all your test accounts so that you can more easily
remember it.
Security questions and answers. You can use the same security questions and answers for
all your test accounts so that you can more easily remember them.
IMPORTANT: Never use real email addresses or live paypal.com passwords for a test
account. Only use fictitious information in your answers to the security
questions. All of this data should be fictional.
Personal or Business account
Your agreement to the terms of using the Sandbox
For Business accounts, the following additional information is generated for you:
Business name and address
Customer service contact information
Business owner contact information
Business owner address
Social Security Number to sign up for PayPal Payments Pro (previously known as Website
Payments Pro)
Sandbox User Guide April 2012 13
Setting Up Test Accounts
3
Managing Test Accounts
Managing Test Accounts
You can view, work with, or launch the Sandbox Test Site for all your test accounts. You can
also create new accounts or remove test email addresses from your view.
To work with test accounts, log in to https://developer.paypal.com, and click the Test
Accounts tab.
To create a new account, click the Create Account link.
To work with the account, select the account by clicking the radio button associated with it
on the left.
You can simulate the live paypal.com site for the selected account by clicking Enter
Sandbox Test Site. When you logged in to
Log me in automatically checkbox to allow direct access to
in which case you do not have to launch the Sandbox to access it.
IMPORTANT: The Delete button does not delete the test account. It removes the test account
from your list of accounts, but the email address for the test account is still on
file for the Sandbox. You cannot reuse an email address that is still on file for
the Sandbox. If you want to rerun a test, do not delete the account; you can
use the Reset option instead.
https://developer.paypal.com, you might have set the
https://www.sandbox.paypal.com/,
The following sections describe how to create a preconfigured test account, which allows
merchants to create an account using a typical configuration that is useful for most testing.
You can also create a test account manually, which might be required if the preconfigured test
account is not adequate for your needs.
NOTE: The first test account that you create is always a preconfigured test account. After you
create the first account, you click Preconfigured to create a preconfigured test
account or Create Manually to create the test account manually. The following
sections assume that a test account has not yet been created.
Creating a Preconfigured Account
To create a preconfigured account:
1. After logging in, select Test Accounts and click the Create Test Account link.
2. Choose the country for which you want the account to be registered.
14 April 2012 Sandbox User Guide
Setting Up Test Accounts
Managing Test Accounts
3. Specify the Account Type and make other selections or accept the defaults.
3
IMPORTANT: When entering a value into the Login Email field, you do not enter a
complete email address, rather you enter a prefix of up to 6 characters,
which will appear at the beginning of the email address. PayPal creates an
email address for you using an internal algorithm. You cannot specify the
complete email address. For example, if you specified test01 in the Login
Email field, the email address, which is only used in the Sandbox, would be
something like test01_1279824359_per@adomain.com .
Sandbox User Guide April 2012 15
Setting Up Test Accounts
3
Managing Test Accounts
4. Click Create Account.
The result is shown below.
16 April 2012 Sandbox User Guide
Setting Up Test Accounts
Managing Test Accounts
3
NOTE: The Login Email is a pseudo-randomized address, which is based on the address
you specified. Credit card and bank account numbers are also generated randomly,
which are shown when you view details:
Sandbox User Guide April 2012 17
Setting Up Test Accounts
3
Managing Test Accounts
Verified Account Status
By default, a preconfigured test account has a confirmed bank account and email addresses.
To create an unverified account change the bank account to unconfirmed.
Resetting a Preconfigured Account
You can reset a preconfigured test account. This is useful when you want to rerun transactions
and need to start from the same point as the original test. Resetting a test account preserves
information required to rerun the test, such as the account email address, API credentials,
credit card and bank accounts, and starting balance. It does not, however, use the same bank
account or credit card numbers. Consider the following account information associated with a
test account:
18 April 2012 Sandbox User Guide
Setting Up Test Accounts
Managing Test Accounts
3
When you click Reset for the account from the Test Accounts tab, you are prompted to enter a
new password and a note to associate with the account:
Sandbox User Guide April 2012 19
Loading...