Mutual SSL Integration Guide

DOCS

Last updated: Aug 15th, 5:50am

Important: Mutual SSL is a limited-release solution available only to select partners at this time. For more information, reach out to your PayPal Account Manager.

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 field	Description
`CN`	Client name as (Client Name) (Environment) (Application) Client
`O`	Owner of generated key pair
`OU`	Organizational unit
`L`	City or locality of entity in O
`ST`	State or province, fully spelled out, of entity in O
`C`	Country 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.

Note: A request to obtain a bearer token without a certificate will fail. This ensures the secure issue of the bearer token, and secure subsequent 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.

Reference