Retrieving Your PayPal API Credentials

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.

PayPal Developer Portal - Home Page

Log in with your live PayPal email address and password.

Once you’re logged in, click Dashboard.

PayPal Developer Portal - Home Page (logged in)

Under the Sandbox heading, click Accounts.

PayPal Developer Portal - Dashboard

Next, click Create Account.

PayPal Developer Portal - Sandbox Accounts PageMake sure Account type is set to Business and that Bank verified account is set to Yes.  Password, First name, Last name, PayPal balanceCredit 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.

PayPal Developer Portal - Create Account Page

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.

PayPal Developer Portal - Account Created

Click the Profile link that appears immediately below the email address.

PayPal Developer Portal - Profile Link

Click API credentials.

PayPal Developer Portal - Account Details

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.

PayPal - Merchant Manager

If the page looks like the screenshot below (look for tabs across the top of the page that say MoneyTransactionsCustomersTools, and More), skip to Procedure G.

PayPal - HawkOtherwise, 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.

PayPal - Classic

Procedure F

PayPal Merchant Manager

Click on Profile.

PayPal Merchant Manager - Profile Link

Under Account information, click Request API credentials.

PayPal Merchant Manager - Profile PageIn the Option 1 box, click Set up PayPal API credentials and permissions.

PayPal Merchant Manager - 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.

PayPal Hawk - Business Profile Button

Click Profile and settings.

PayPal Hawk - Profile and Settings Link

Skip to Procedure I below.

Procedure H

Classic PayPal

Click Profile.

PayPal Classic - Profile LinkContinue 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 infoMy moneyMy settings, and My selling tools — don’t worry about what shows at the very top of the page), skip to Procedure J.

PayPal Hawk and Classic - Profile Page

Otherwise, if the profile page looks like the screenshot below (look for three columns titled Account InformationFinancial Information, and Selling Preferences — again, don’t worry about what shows at the very top of the page), skip to Procedure K.

PayPal Hawk and Classic - Old Profile Page

Procedure J

New profile page layout

Click My selling tools.

PayPal New Profile - My Selling Tools Link

Find API access and click the link to the right of it.

PayPal New Profile - API Access Link

Skip to Procedure L.

Procedure K

Old profile page layout

Under Account Information, click API Access.

PayPal Classic Profile - API Access Link

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.

PayPal - View API Signature Link

If the link in this box says View API Certificate, you have certificate credentials tied to your account.  Skip to Procedure O.

PayPal - View API Certificate Link

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.

PayPal - Request API Credentials Link

Procedure M

View signature credentials

Click View API Signature.  Your credentials will be shown.

PayPal - API Signature Page

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.

PayPal - API Signature Remove Button

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!)

PayPal - Remove API Signature Page

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.

PayPal - API Certificate Page

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.

PayPal - API Certificate Remove Button

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!)

PayPal - Remove API Certificate Page

Continue to Procedure Q.

Procedure Q

Request new API credentials

Click Request API credentials.

PayPal - Request API Credentials Link

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.

PayPal - Request API Signature Button

Click Agree and Submit.

PayPal - Request API Signature Agree and Submit Button

Your new API credentials will be displayed.

PayPal - API Signature Page

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.

PayPal - Request API Certificate Button

Click Agree and Submit.

PayPal - Request API Certificate Agree and Submit Button

Your new API credentials will be displayed.  Click the Download Certificate button to download your API certificate.

PayPal - API Certificate Page

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.

Leave a Reply

Your email address will not be published. Required fields are marked *