Creating and managing NVP/SOAP API credentials

When you call PayPal NVP/SOAP APIs, you must authenticate each request by using a set of API credentials. PayPal associates a set of API credentials with a specific PayPal account and you can generate credentials for any PayPal Business or Premier account.

This document describes how to create the credentials to make calls to the sandbox and live environments.

Contents

Credential types

The NVP/SOAP APIs support two different types of credentials:

  • Signature API credentials
  • Certificate API credentials

Each credential set contains these credential values:

Credential set Credential names
Signature
  • API Username
  • API Password
  • Signature
Certificate
  • API Username
  • API Password
  • Certificate

While you can use either set to authenticate requests to the NVP/SOAP API platform, for security reasons, PayPal recommends you use certificate credentials. For more on certificate credentials, see Create and manage certificate credentials.

Note: You authenticate calls to the Adaptive APIs (Adaptive Accounts, Adaptive Payments, the Invoicing service, and the Permissions service) using these same credentials. However, all Adaptive platform APIs require that you also supply an appID in addition to your signature or certificate credential values.

Create and manage certificate credentials

Important: All PayPal API certificate credentials created before February 4, 2016 are 1024-bit, SHA-1 certificates that expire after 10 years. As of February 4, 2016, all PayPal API certificate credentials issued are 2048-bit, SHA-256 certificates that expire every 3 years. As a result, PayPal is requiring all merchants to upgrade to the new 2048-bit certificates before January 1, 2018. If you currently connect to PayPal using API certificate credentials, you will need to generate a new API certificate via your account profile and use it for all API requests. For detailed information, refer to the PayPal Knowledge Base article that discusses the certificate upgrade.

Learn how to create and manage certificate credentials.

Note: If your API certificate is expiring, skip ahead to Renew an API certificate.

  1. For live credentials, log in to your PayPal business account at www.paypal.com. For test credentials, log in to the PayPal Sandbox at www.sandbox.paypal.com using a sandbox merchant account.

  2. Click the profile icon ( Profile menu ) on the top right side of the page. From the Business Profile menu, select Profile and Settings.

    Note: If you do not see the profile icon on the top right, select Profile which appears in the top menu when the My Account tab is selected.

  3. From the left menu, click My selling tools.

  4. In the Selling online section, click the Update link for the API access item.

  5. To generate the certificate set, on the API Access page in the NVP/SOAP API Integration section, click Request API Credentials.

    Note: If you've already generated an API certificate, a View API Certificate link is displayed on the API Access page. If you need to generate a new API certificate, you first need to delete the existing certificate. If the existing certificate is not being used by your live application, click the View API Certificate link, and then click the Remove Certificate button to delete the existing certificate.

  6. On the Manage API certificate page, select the Request API Certificate radio button, then click the Agree and Submit button.

    Access the Credentials management page

    The Manage API Certificate page displays.

  7. Click Download Certificate.

The certificate is downloaded to a file named cert_key_pem.txt. Make certain that you save the file to a secure location.

PayPal formats the API certificate file in PEM format. The file contains both your public certificate and the associated private key. Although the PEM certificate is not human readable, the file is not encrypted. See: Encrypt your certificate for details.

Renew an API certificate

All PayPal API certificate credentials created before February 4, 2016 are 1024-bit, SHA-1 certificates that expire after 10 years. As of February 4, 2016, all PayPal API certificate credentials issued are 2048-bit, SHA-256 certificates that expire every 3 years. As a result, PayPal is requiring all merchants to upgrade to the new 2048-bit certificates before January 1, 2018. Following that, to prevent an interruption in API services, you must renew your certificate before it expires. Note that certificate lifetime is now 3 years instead of 10 years.

The certificate renewal process generates a new certificate that you can install to replace any expiring certificate.

  1. For live credentials, log in to your PayPal business account at www.paypal.com. For test credentials, log in to the PayPal Sandbox at www.sandbox.paypal.com using a sandbox business account.

  2. Click the profile icon (Profile menu) on the top right side of the page. From the Business Profile menu, select Profile and Settings.

    Note: If you do not see the profile icon on the top right, select Profile which appears in the top menu when the My Account tab is selected.

  3. From the left menu, click My selling tools.

  4. In the Selling online section, click the Update link for the API access item, then click View API Certificate.

  5. On the Manage API certificate page, check the status of your API certificate to verify whether it is Active or Expires soon.

    Certificate is expiring

  6. If the status of your certificate is Expires soon, click the Renew certificate button.

    An additional certificate is generated and given an Active status. Both the new and old certificates appear in the Manage API certificate page.

    Renewed certificate plus expiring certificate

  7. On the certificate marked as Active, click Download Certificate and follow the steps to download a certificate.

After you've imported the new API certificate, test your integration to ensure it works with the new certificate. Distribute your new API certificate to all affected partners. Once the old certificate expires, remove it by clicking the Remove Certificate button associated with the certificate.

Encrypt your certificate

The PayPal SDKs for Java and ASP.NET require the additional step of encrypting the certificate into PKCS12 format before you can use it with the SDKs. (Note that the PayPal SDK for PHP does not require SSL encryption.)

Tip: If you do use encryption, make certain that you encrypt both your Sandbox and your live API certificates.

The steps to encrypt your certificate require the OpenSSL encryption tool. While Unix users likely have this tool installed with their operating system, Windows users need to download OpenSSL. Accept the defaults to install OpenSSL.

  1. Open a command prompt.

  2. Ensure that the OpenSSL bin directory is in your system path. If it is not, add it to your path.

  3. Change directories to the location of the certificate you want to encrypt (cert_key_pem.txt) and execute the following command:

    openssl pkcs12 -export -in cert_key_pem.txt -inkey cert_key_pem.txt -out paypal_cert.p12
    

Note: When encrypting a certificate, you are prompted for a password that is used when decrypting the file. Enter a password at the Enter Export Password prompt and make certain that you store it in a secure location.

The process listed above creates a file named paypal_cert.p12 which is your encrypted API certificate.

Install the certificate for ASP.NET

If you are developing with the PayPal SDK for ASP.NET, Windows requires that you:

See the PayPal Merchant Technical Support knowledge base article How do I import my certificate into the Windows key store? for more information.

Create an API signature

To create an API signature, complete these steps:

  1. For live credentials, log in to your PayPal business account at www.paypal.com. For test credentials, log in to the PayPal Sandbox at www.sandbox.paypal.com using a sandbox business account.

  2. Click the profile icon ( Profile menu ) on the top right side of the page. From the Business Profile menu, select Profile and Settings.

    Note: If you do not see the profile icon on the top right, select Profile, which appears in the top menu on the My Account tab.

  3. From the left menu, click My selling tools.

  4. In the Selling online section, click the Update link for the API access item.

  5. To generate the API signature, click Request API Credentials on the API Access page.

    Click Request API Credentials

    Note: If you've already generated an API signature, a View API Signature link is displayed on the API Access page. If you need to generate a new API signature, you first need to delete the existing API signature. If the existing API signature is not being used by your live application, click the View API Signature link, and then click the Remove button to delete the existing signature.

  6. Select Request API signature and click Agree and Submit to generate the API signature.

    The following figure shows this page with an example API signature credential.

    Signature API credential set