I originally posted this article to x.com on August 10, 2010. Since that time, x.com has been repurposed, and my posts have been taken down. I have reposted this here for informational and historical purposes.
Update 9/16/2014: I’ve tried to update this information to reflect the myriad of different account layouts that are available as of today.
One of the very first things that you must do when implementing Website Payments Pro, Express Checkout, Mobile Checkout, Adaptive Payments, or Adaptive Accounts is to get your API credentials. For someone like me, who has done this a hundred times, this is pretty simple; but I get calls almost every day from new merchants and developers who just don’t know what API credentials are, and where to go to get them. Further, in all my browsing through paypal.com and x.com, I don’t think I’ve ever seen a clear, concise guide on how to retrieve your API credentials. So, here’s the answer.
What are API credentials?
First off, what is an API? An API is the way two programs communicate with each other. The particulars will vary depending on what program is talking to what, but essentially, the API is generally going to be a very structured, very specific message that asks one program to do something for the other. In the case of the PayPal APIs, scripts on your web server send an API “call” to the PayPal servers, asking PayPal to do something for your site. PayPal answers back with information about whether or not the request could be completed, as well as any information requested by that API call.
Think of it like a phone call to your friend. To start off, you dial a specific phone number. Someone on the other end picks up the phone. (If no one picks up after a certain amount of time, the call “times out”, and you either hang up the phone, or the answering machine/voice mail picks up.) When a person on the other end picks up, you expect to hear them say “Hello?”. You then ask for your friend. The person on the other end puts your friend on the phone, and you begin your conversation. When you are finished, you both say “goodbye”, and hang up the phone.
This phone call scenario resembles an API call, because it’s very structured, it includes the exchange of application-specific data (in the form of a conversation that is relevant to both of you), and it even includes error checking. If the person on the other end doesn’t say “Hello?” when they pick up the phone, or if you don’t recognize the voice, you might get confused, hang up, and call back. When you do get an answer, you make a request for a specific service (your friend). If the call ends before you both say “goodbye”, you’ll call them back and attempt to continue your conversation.
If all else fails, just think of an API call as a phone call between two computers in a language you don’t understand.
So, what are API credentials? Well, in our “phone call” scenario, suppose that, when the person on the other end of the phone answers, they don’t recognize your voice. Or, they don’t recognize the number that came up on the caller ID. They’ll ask, “who is this?”, and you’ll answer with your name. If they still don’t recognize you, you can include something like “It’s me, Billy! I was your best friend in high school!” In a nutshell, that’s what API credentials are — they tell PayPal who it is that’s making the request, and it includes information that should only be known to a person or program that has been authorized to make the API call.
PayPal’s API credentials consist of an API username and password (these are not the same as the username and password you use to log in to paypal.com), as well as a third piece of information — either a signature or a certificate. A certificate is a file that contains cryptographic information about how your systems should communicate with PayPal (those more familiar with SSL may be familiar with the term “client-side SSL certificate”). A signature is simply a piece of text that your scripts send, along with the username and password, when communicating a request to PayPal.
Before you start, you’ll need to figure out which one you need. If you’re using a third-party shopping cart, the shopping cart will determine which one you need — check with them. Most shopping carts use the signature. If you’re a programmer just starting out, we recommend the signature, because it’s a lot easier to implement. If you choose the wrong one, don’t worry — you can switch back and forth at any time. Just keep in mind that you can only have one or the other on your account at one time, not both — e.g., if you choose a certificate, and it turns out later that you need a signature, you’ll have to delete the certificate in order to get a signature.
How do I get my API credentials?
The procedures will be slightly different depending on a number of factors, such as whether you are on the live site or the Sandbox, and what type of account you have, etc.
If you need credentials for your live PayPal account, start with Procedure A below.
If you need credentials for your Sandbox PayPal account, skip to Procedure B below.
Procedure A
Log in to your PayPal account
Go to https://www.paypal.com and log in. Once you are signed in to your PayPal account, skip to Procedure E below.
Procedure B
Sign into the PayPal Developer Portal and create a Sandbox account
You will need a PayPal account on the live site before you begin. If you do not have one, go to https://www.paypal.com and sign up. Verify your email address before continuing.
Once you have created a PayPal account, go to https://developer.paypal.com and click Log In.
Log in with your live PayPal email address and password.
Once you’re logged in, click Dashboard.
Under the Sandbox heading, click Accounts.
Next, click Create Account.
Make sure Account type is set to Business and that Bank verified account is set to Yes. Password, First name, Last name, PayPal balance, Credit card type, and I want to add Log In with PayPal to my site can all be set to values of your own choosing. (Note that the email address you enter here doesn’t need to be a real email address — it’s not used outside of the Sandbox.) When you’re finished, click Create Account.
If you need an API signature, continue to Procedure C.
If you need an API certificate, skip to Procedure D.
Procedure C
Retrieve API signature credentials through the PayPal Developer Portal
Click on the email address of the Sandbox account you created in Procedure B.
Click the Profile link that appears immediately below the email address.
Click API credentials.
Your API credentials will be shown.
If you were able to successfully retrieve your API credentials, stop here.
If you were not able to successfully retrieve your API credentials, if you need to remove your credentials and request a new set, or if you need an API certificate, continue to Procedure D.
Procedure D
Log in to your Sandbox account
Go to https://www.sandbox.paypal.com. Log in with the email address and password you created in Procedure B.
Once you are logged in, continue to Procedure E.
Procedure E
Determine your account layout
If you are sent to PayPal Merchant Manager after logging in — e.g., the page looks like the screenshot below, and the first part of the URL in your address bar says “https://paypalmanager.paypal.com”, skip to Procedure F.
If the page looks like the screenshot below (look for tabs across the top of the page that say Money, Transactions, Customers, Tools, and More), skip to Procedure G.
Otherwise, if the page looks like the screenshot below, and the first part of the URL in your address bar does not say “https://paypalmanager.paypal.com”, skip to Procedure H.
Procedure F
PayPal Merchant Manager
Click on Profile.
Under Account information, click Request API credentials.
In the Option 1 box, click Set up PayPal API credentials and permissions.
Skip to Procedure L below.
Procedure G
New PayPal for Business
Click on the Business Profile button in the upper-right corner of the page.
Click Profile and settings.
Skip to Procedure I below.
Procedure H
Classic PayPal
Click Profile.
Continue to Procedure I.
Procedure I
Determine profile page layout
If the profile page looks like the screenshot below (look for the tabs on the left side of the page that say My business info, My money, My settings, and My selling tools — don’t worry about what shows at the very top of the page), skip to Procedure J.
Otherwise, if the profile page looks like the screenshot below (look for three columns titled Account Information, Financial Information, and Selling Preferences — again, don’t worry about what shows at the very top of the page), skip to Procedure K.
Procedure J
New profile page layout
Click My selling tools.
Find API access and click the link to the right of it.
Skip to Procedure L.
Procedure K
Old profile page layout
Under Account Information, click API Access.
Continue to Procedure L.
Procedure L
Determine whether credentials are present
Look at the Option 2 box.
If the link in this box says View API Signature, you have signature credentials tied to your account. Skip to Procedure M.
If the link in this box says View API Certificate, you have certificate credentials tied to your account. Skip to Procedure O.
If the link in this box says Request API credentials, you do not have any API credentials attached to your account. Skip to Procedure Q.
Procedure M
View signature credentials
Click View API Signature. Your credentials will be shown.
If you need a set of signature credentials, stop here.
If you need to request a new set of credentials, or if you need an API certificate, continue to Procedure N below.
Procedure N
Remove signature credentials
Click Remove.
Click Remove again to confirm that you want to remove the API signature. (Warning: the credentials will be deactivated immediately upon clicking Remove. If you have any applications that are using these credentials, they will stop working until you update them with a new set of credentials!)
Skip to Procedure Q below.
Procedure O
View certificate credentials
Click View API Certificate. Your username and password will be shown. Click the Download Certificate button to download your API certificate.
Note: API certificates are good for ten years from the time they are issued. PayPal will allow you to request a second API certificate if your current certificate is about to expire. The procedure for requesting the second certificate is not covered by this guide.
If you need a set of certificate credentials, stop here.
If you need to request a new set of credentials, or if you need an API signature, continue to Procedure P.
Procedure P
Remove certificate credentials
Click Remove Certificate.
Click Remove again to confirm that you want to remove the API certificate. (Warning: the credentials will be deactivated immediately upon clicking Remove. If you have any applications that are using these credentials, they will stop working until you update them with a new set of credentials!)
Continue to Procedure Q.
Procedure Q
Request new API credentials
Click Request API credentials.
If you need an API signature, skip to Procedure R below.
If you need an API certificate, skip to Procedure S below.
Procedure R
Request new signature credentials
Click Request API signature.
Click Agree and Submit.
Your new API credentials will be displayed.
If you needed an API signature, stop here.
If you need to request a new set of credentials, or if you need an API certificate, skip to Procedure N.
Procedure S
Request new certificate credentials
Click Request API certificate.
Click Agree and Submit.
Your new API credentials will be displayed. Click the Download Certificate button to download your API certificate.
If you needed an API certificate, stop here.
If you need a new set of credentials, or if you needed an API signature, skip to Procedure P.