Mutual SSL Integration Guide

DOCS

Last updated: Aug 15th, 5:50am

This integration guide describes how to set up and invoke PayPal APIs with the Mutual SSL certificate.

Create the CSR

Begin by creating a Certificate Signing Request (CSR). The CSR identifies the organization to the PayPal servers.

Contact your integration team for help with creating the CSR.

CSR attributes identify the organization to the PayPal servers and must follow these guidelines defined by the PayPal Information Security Team:

  • Common name, CN, can't be a fully qualified domain name (FQDN).
  • Minimum key length must be 2048 bits.
  • Signature algorithm must be SHA-256.
  • Client certificate must be valid for a maximum 3 years.
  • Organization, O, must be the owner and generator of the key pair.
  • Organizational unit, OU, must be PayPal, Inc.
  • Server Authentication EKU can't be in the issued certificate.
  • Email addresses can't be in the CSR.
Required fieldDescription
CNClient name as (Client Name) (Environment) (Application) Client
OOwner of generated key pair
OUOrganizational unit
LCity or locality of entity in O
STState or province, fully spelled out, of entity in O
CCountry entity in O

Sample for Production

Subject: C=US, ST=Florida, L=Jacksonville, O=United National Banking Services, OU=PayPal, Inc., CN=UNB US Prod API Client

Sample for Sandbox

Subject: C=US, ST=Florida, L=Jacksonville, O=United National Banking Services, OU=PayPal, Inc., CN=UNB US Sandbox API Client

Sign the CSR

In most cases, PayPal requires one certificate per environment for REST app clients and partners. One certificate connects to production and one connects to sandbox.

After you create the CSR, send it securely to your PayPal integration team. PayPal signs the certificate and maps it to the client ID, then returns the signed CSR to you. Use the signed CSR as the certificate.

Use the certificate with PayPal applications

This code sample shows a cURL request for an access token with certificate (cert), cert password, and keys passed in.

    1curl –-cert client.pem:<password> --key key.pem https://api-m.paypal.com/v1/oauth2/token \
    2-H ‘Authorization:Basic <client_id:secret>’ \
    3-d "grant_type=client_credentials"

    Use the bearer token obtained from this request in subsequent PayPal API calls. After you obtain a token, you no longer need to pass certificates in API calls.

    Renew the certificate

    Mutual SSL certificates expire in three years. PayPal tracks certificate expiration, but PayPal recommends that you track when your certificate is due to expire so you can prepare to renew it.

    When a certificate nears expiration, PayPal sends notifications to the email attached to the CSR at intervals of 90, 60, 30, and 15 days, then daily under 15 days.

    To renew the certificate, repeat the process in this integration guide, but use a new organizational unit (OU) or common name (CN). Multiple certificates can have the same client ID attached as a SAN at the same time, but they need different OUs or CNs.

    Next

    Reference

    If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more