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.
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 . . . . . . . . . . . .
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 . . .
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.
Documentation Feedback 6 April 2012 Sandbox User Guide
1 Overview to the PayPal Sandbox 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.
1 8 Overview to the PayPal Sandbox 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 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. Real companies’ and people’s names and postal addresses.
2 Accessing the PayPal Sandbox 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.
2 Accessing the PayPal Sandbox Signing Up for Sandbox Access 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.
Accessing the PayPal Sandbox Welcome to the PayPal Sandbox 2 Welcome to the PayPal Sandbox When you log in to the Sandbox, the Sandbox Test Environment home page appears, as follows: 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.
2 Accessing the PayPal Sandbox 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.
3 Setting Up Test Accounts 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.
3 Setting Up Test Accounts 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.
Setting Up Test Accounts Managing Test Accounts 3 3. Specify the Account Type and make other selections or accept the defaults. IM PORT AN T : Sandbox User Guide 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.
3 Setting Up Test Accounts Managing Test Accounts 4. Click Create Account. The result is shown below.
Setting Up Test Accounts Managing Test Accounts NOT E : Sandbox User Guide 3 The Login Email is a pseudo-randomized address, which is based on the address you specified.
3 Setting Up Test Accounts 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.
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
3 Setting Up Test Accounts Managing Test Accounts After you reset the account, the information to rerun your test is preserved: Creating a Test Account Manually You can create a test account manually by clicking the Create Manually link for Create Account.
Setting Up Test Accounts Creating a PayPal Payments Pro Account 3 Creating a PayPal Payments Pro Account You can use a wizard to create a PayPal Payments Pro business account by clicking the PayPal Payments Pro link for Create Account.
3 Setting Up Test Accounts Creating a PayPal Payments Pro Account To complete the application for PayPal Payments Pro, you must enter a Social Security Number. You can enter a Social Security Number in the following format: 111xxxxxx where x is any digit. NOT E : 22 The SSN you enter must not have already been recorded for some other account in the Sandbox.
Setting Up Test Accounts Adding a Funding Source 3 Adding a Funding Source To test transactions, you must add a source of funds to your buyer test account. The following sections describe your choices: 1. “Changing or Adding Additional Bank Accounts” on page 23. You can add bank accounts, but they will not contain funds unless you use Send Money to send the bank account holder money. 2. “Adding Credit Cards” on page 24. For testing, this is the most efficient way to add funds.
3 Setting Up Test Accounts Adding a Funding Source 3. Under the Financial Information header, click the Bank Accounts link. 4. In the Bank Account window, click Add. 5. In the Add Bank Account window: – Enter a fictitious bank name. Using the automatically generated bank account number as the name of the bank will make that account number visible to you for use in testing later. – Except for UK or German test bank accounts, leave all other automatically generated information as is.
Setting Up Test Accounts Adding a Funding Source 3 2. Navigate to My Account > Profile. 3. Under the Financial Information header, click the Credit Cards link. Make a note of the credit card number for your use in later testing.
3 26 Setting Up Test Accounts Adding a Funding Source April 2012 Sandbox User Guide
4 Testing PayPal Website Features This chapter describes PayPal products features you can test in the Sandbox without PayPal APIs: Website Payments with Buy Now Buttons: Use the Sandbox to test accepting PayPal as a payment mechanism on a website. Shopping Cart Purchases: Use the Sandbox to test the purchase of multiple items in a single transaction using a single payment. Instant Payment Notification (IPN). Use the Sandbox to test IPN for updates and payment notifications.
4 Testing PayPal Website Features Website Payments with Buy Now Button You must change the form action to redirect to the Sandbox, using the following URL: https://www.sandbox.paypal.com/cgibin/webscr" method="post" Use the PayPal Help link to answer related questions, such as “How do I make a Buy Now Button compatible with the Shopping Cart feature?” For general information, see https://www.paypal.com/pdn-item. For general information about shopping cart purchases, see https://www.paypal.
Testing PayPal Website Features Handling Pending Transactions 4 Handling Pending Transactions Transactions typically are credited to your PayPal account instantly after the buyer completes the transaction; however, a buyer might select a payment method that is not completed instantly. In these cases, the transaction goes into a pending state and the transaction is completed after a couple of days.
4 Testing PayPal Website Features Verifying a Test Refund Verifying a Test Refund 1. Log in to https://developer.paypal.com. 2. Click the Test Email tab. Your Sandbox inbox shows refund confirmation email messages for the seller and buyer. 3. To further verify that the refund was successful: – Check your Web server for IPN notifications related to the refund. – Launch the Sandbox as your test buyer or seller account and navigate to My Account > Overview to see the transaction in your Recent Activity.
Testing PayPal Website Features Transferring Funds to a Test Account 4 Transferring Funds to a Test Account To transfer funds to a test account:? 1. After logging into https://developer.paypal.com, select a test account and click Enter Sandbox Test Site 2. Navigate to My Account > Add Funds.? 3. Click the Transfer funds from a Bank Account link.? 4. On the Add Funds by Electronic Funds Transfer page:? – Select the bank account from which the funds are coming in the From drop-down list.
4 Testing PayPal Website Features Sending Funds to a Seller Sending Funds to a Seller To purchase goods or services, a PayPal user must send funds to a seller. In the PayPal Sandbox, you can simulate the actions of a buyer by manually initiating the payment of funds. You must use a Personal test account to represent the buyer. To send funds from one test account to another: 1. Log in to https://developer.paypal.com, click the Test Accounts tab, select a test account, and click Enter Sandbox Test Site. 2.
Testing PayPal Website Features Billing A Customer 4 1. Log in to https://developer.paypal.com, click the Test Accounts tab, select a test account for which funds are requested, and click Enter Sandbox Test Site. 2. Navigate to the Request Money tab. 3. On the Request Money page, enter the email address (PayPal login name) for the test account being billed in the Recipient’s Email box. 4. Enter the billed amount in the Amount box. 5. Select the currency for the funds in the Currency drop-down list. 6.
4 34 Testing PayPal Website Features Billing A Customer April 2012 Sandbox User Guide
5 Testing an Express Checkout Integration You can test your Express Checkout integration in the Sandbox. This example shows how to simulate your web pages using HTTP forms and supplying the values for API operations from these forms. You can use this strategy for your initial testing; however, for more complete testing, you will want to replace these forms with your web pages containing actual code. The following diagram shows the Express Checkout execution flow, which uses the Sandbox as the API server.
5 Testing an Express Checkout Integration Express Checkout Execution Flow The following steps match the circled numbers in the diagram. Perform the actions in each step to test Express Checkout. 1. Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox.
Testing an Express Checkout Integration 5 such as https://api-3t.sandbox.paypal.com/nvp, as shown in the following example:
5 Testing an Express Checkout Integration 5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation on the Sandbox:
Testing an Express Checkout Integration 5 7. Review the response string from the DoExpressCheckoutPayment API operation.
5 40 Testing an Express Checkout Integration April 2012 Sandbox User Guide
6 Sandbox Test Tools Instant Payment Notification Simulator You can use the Instant Payment Notification (IPN) Simulator to send IPNs to the URL that you set up to receive them. You can use this tool to verify that you are receiving IPNs correctly. To set up and send an IPN, select Instant Payment Notification (IPN) simulator from Test Tools.
6 42 Sandbox Test Tools Instant Payment Notification Simulator April 2012 Sandbox User Guide
Sandbox Test Tools Instant Payment Notification Simulator 6 You can modify the fields that you want to include in the IPN; however, the simulator does not check the validity of any field that you change. NOT E : By default, only populated fields are displayed. You can check the Show all fields box to view all fields. After you have viewed or modified the fields to be sent, click Send IPN. The results of the operation are displayed at the top of the page.
6 44 Sandbox Test Tools Instant Payment Notification Simulator April 2012 Sandbox User Guide
7 Testing Error Conditions In default operation, the Sandbox mimics the live PayPal site as closely as possible, which means that an error can be replicated only by creating the exact conditions and sequence of events to raise an error. This positive test environment is well-suited for testing logic that follows the typical error-free path; however, it can be difficult to raise error conditions and test logic to handle errors.
7 Testing Error Conditions API Testing cases, the error condition for positive testing is raised, regardless of whether the account was enabled for negative testing. API Testing For APIs, you trigger an error condition by setting a field to the value of the error you want to trigger. The value you specify depends on the kind of field: for amount-related fields, specify a value as a number with two digits to the right of the decimal point; for example, 107.
Testing Error Conditions API Testing API Name NVP Field Name SOAP Element Description DoExpressCheckoutP ayment TOKEN Token Specify the error code to trigger as all digits in the field; for example, a token value of 10755 triggers PP API error code 10755. DoExpressCheckoutP ayment November 2011 AMT (or) PAYMENTREQUEST_ n_AMT OrderTotal Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 106.
7 Testing Error Conditions API Testing API Name NVP Field Name SOAP Element Description BAUpdate Version 3.0 REFERENCEID ReferenceID Specify the error code to trigger as all digits in the field; for example, an ID of 10755 triggers PP API error code 10755. DoReferenceTransac tion AMT OrderTotal Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 107.55 triggers PP API error code 10755.
Testing Error Conditions API Testing 7 The request invokes the following response: Timestamp =2011-06-13T16:13:07Z& Ack =Failure& CorrelationID =bacbc41933f33& Errors ="urn:ebay:apis:eBLBaseComponents"& ShortMessage=Buyer cannot pay.& LongMessage=Transaction rejected, please contact the buyer.
7 Testing Error Conditions Testing Using AVS Codes TIMESTAMP=2007%2d04%2d04T03%3a10%3a23Z& CORRELATIONID=81ccc18eaec49& ACK=Failure& L_ERRORCODE0=10009& L_SHORTMESSAGE0=Transaction%20refused& L_LONGMESSAGE0=You%20can%20not%20refund%20this%20type%20of%20transaction& L_SEVERITYCODE0=Error& L_ERRORCODE1=10009& L_SHORTMESSAGE1=Transaction%20refused& L_LONGMESSAGE1=You%20are%20over%20the%20time%20limit%20to%20perform%20a%20r efund%20on%20this%20transaction& L_SEVERITYCODE1=Error& L_ERRORCODE2=10009& L_SHORTMES
Testing Error Conditions Testing Using AVS Codes AVS Code Trigger Description of Error Y AVS_Y Exact match (no error). The complete address and 5-digit zip code matches. Z AVS_Z The 5-digit zip code matches but no address is specified; results in an error if the “Partial Address Match” risk control is set. N AVS_N No address information; results in an error if the “No Address Match” risk control is set.
7 Testing Error Conditions Testing Using AVS Codes When you attempt to process the transaction, the following message appears: Testing an AVS Code Using DoDirectPayment Consider an example that sets up testing for AVS code A and error code 10755 in DoDirectPayment, for which AVS code A indicates no zip code is specified and results in an error if the “Partial Address Match” risk control is set, whether or not other errors occur: 52 April 2012 Sandbox User Guide
Testing Error Conditions Testing Using CVV Codes 7 METHOD=DoDirectPayment& CREDITCARDTYPE=VISA& ACCT=4683075410516684& EXPDATE=112007& CVV2=808& AMT=107.55& FIRSTNAME=Designer& LASTNAME=Fotos& IPADDRESS=255.55.167.002& STREET=1234%20AVS_A%20Street& CITY=San%20Jose& STATE=CA& COUNTRY=United%20States& ZIP=95110& COUNTRYCODE=US& SHIPTONAME=Louise%20P.
7 Testing Error Conditions Testing Using CVV Codes The following table identifies valid CVV codes, corresponding triggers, and a description of each error condition: CVV Code Trigger Description of Error M 115 CVV2 matches (no error). N 116 CVV2 does not match. U 125 Service unavailable. S 123 Service not supported. P 120 Transaction not processed. X 130 No response. NOT E : The specified CVV2 code is set, regardless of whether a PP API error code is set.
Testing Error Conditions Testing Using CVV Codes 7 When you attempt to process the transaction, the following message appears: NOT E : Other errors are also reported in addition to CVV code N. Testing a CVV Code Using DoDirectPayment Consider an example that sets up testing for CCV code N in DoDirectPayment, which indicates a mismatch in the card validation code: METHOD=DoDirectPayment& CREDITCARDTYPE=VISA& ACCT=4683075410516684& EXPDATE=112007& CVV2=116& AMT=1.
7 Testing Error Conditions Testing Using CVV Codes The request invokes the following response: TIMESTAMP=2007%2d04%2d04T03%3a35%3a12Z& CORRELATIONID=2499856319532& ACK=Failure& L_ERRORCODE0=15004& L_SHORTMESSAGE0=Gateway%20Decline& L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e%20Please%20e nter%20a%20valid%20Credit%20Card%20Verification%20Number%2e& L_SEVERITYCODE0=Error& VERSION=2%2e400000& BUILD=1%2e0006 56 April 2012 Sandbox User Guide
8 Testing Payment Review On the live site, payment review is always active, which means that PayPal reviews payments automatically for various risk factors. In the Sandbox, all transactions pass payment review by default.
8 58 Testing Payment Review April 2012 Sandbox User Guide
9 Technical Support Depending on the PayPal product you need assistance with, contact either Customer Service or Developer Technical Support. Contacting Customer Service for Live PayPal Website Help Use PayPal Help to find an answer to any problem you might encounter with live products such as Website Payments or Instant Payment Notification. To contact Customer Service about issues with the Live PayPal website: 1. Go to https://paypal.com/. 2. Click Help in the upper right corner of the page. 3.
9 Technical Support Contacting Developer Technical Support for API Help 3. Click Email PayPal Support. 4. Complete the form.
Revision History Revision history for PayPal Sandbox User Guide. Date Description April 2012 Removed obsolete chapter, “Linking Your Sandbox with Your X.com Account.” Updated references to Website Payments Standard and Website Payments Pro to PayPal Payments Standard and PayPal Payments Pro, respectively. December 2011 Added corrections concerning API testing and negative testing. October 2010 Added a chapter about linking Sandbox accounts of x.com accounts.
April 2012 Sandbox User Guide