Secure your HTML payment buttons

DocsLegacy


Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

All PayPal Payments Standard buttons created using the Create a PayPal payment button page are protected automatically. Either all payment data is saved by PayPal and only a single button ID is shared between the merchant website and PayPal, or the payment button code is encrypted before it is displayed on the merchant website.

If your implementation allows it, PayPal recommends using the Create a PayPal payment button page to create all payment buttons.

The following table describes strategies to help you ensure that all your PayPal payment buttons are secure.

Strategy for Securing Payment ButtonsSee
Create all your payment buttons using the Create a PayPal payment button page on the PayPal website. All buttons created using this tool are secure by default, so there is no further security action required. Create a payment button
Use the Button Manager API to dynamically create secure buttons. Note that you must be comfortable programming in languages such as Java and PHP to use the Button Manager API.PayPal Payments Standard Button Manager API Overview
Manually create payment buttons, and then manually encrypt them using the Encrypted Website Payments (EWP) command line encryption utility. Note that you should only use this method if your implementation will not allow you to use the Create a PayPal payment button page.Using EWP to Protect Manually Created Payment Buttons
Edit your PayPal account profile to block unprotected and non-encrypted buttons. This adds security to your system by blocking payments made from unexpected sources.Blocking Unprotected and Non-encrypted Website Payments

Encrypted Website Payments (EWP)

EWP is a PayPal Payments Standard feature that uses public and private keys to encrypt the payment button code used on merchant websites. The encryption hides the payment details so they cannot be seen by anyone viewing the website source code in a browser.

Important: The EWP feature is only required to be used for manually created buttons.

If you manually create buttons without using EWP, the non-secured or non-encrypted HTML button code can be viewed by anyone. Because of this, a malicious third party can copy a page, change button HTML variables such as price, and make fraudulent payments. The EWP encryption combats malicious attacks on merchants where if the button were not encrypted, the HTML attributes of the button, such as price, invoice number, or even the return URL would be displayed in plain text and could easily be modified to spoof payments.

The following topics provide detailed information about securing manually created payment buttons the using the EWP feature:

How Encrypted Website Payments Work

The EWP feature relies on standard public key encryption for protection. With public and private keys, you can manually or programmatically encrypt payment button code to hide the payment details before the buttons are displayed on your website. The table below illustrates the sequence of actions that occur with payment buttons protected by using EWP.

The following table describes the EWP flow:

Website Actions Payer Actions PayPal Actions
Generate a public key for the website, upload it to PayPal, and download the PayPal public certificate to the website.

Note: Do this action only once, when you first integrate PayPal Payments Standard with your website.

Manually write the HTML code for a payment button.

Encrypt the payment button code by using the PayPal public key and then signing the encrypted code with the website's private key.

Publish the signed, encrypted HTML code for the payment button to the website.Click the published PayPal payment button.PayPal checks the authenticity of the data by using the website's public key, which was previously uploaded to PayPal.

PayPal decrypts the protected button code by using the PayPal private key.

PayPal redirects the payer's browser to the appropriate PayPal checkout experience, as specified in the HTML variables of the decrypted button code.

Public Key Encryption Used by Encrypted Website Payments

EWP uses public key encryption, or asymmetric cryptography, which provides security and convenience by allowing senders and receivers of encrypted communication to exchange public keys to unlock each others messages. The fundamental aspects of public key encryption are:

  • Public keys – Public keys are created by receivers and are given to senders before they encrypt and send information. Public certificates comprise a public key and identity information, such as the originator of the key and an expiry date. Public certificates can be signed by certificate authorities, who guarantee that public certificates and their public keys belong to the named entities.

    You and PayPal exchange each others' public certificates.

  • Private keys – Private keys created by receivers are kept to themselves.

    You create a private key and keep it in your system. PayPal keeps its private key on its system.

  • The encryption process – Senders use their private keys and receivers' public keys to encrypt information before sending it. Receivers use their private keys and senders' public keys to decrypt information after receiving it. This encryption process also uses digital signatures in public certificates to verify the sender of the information.

    You use your private key and PayPal's public key to encrypt your HTML button code. PayPal uses its private key and your public key to decrypt button code after people click your payment buttons.

Using EWP to Protect Manually Created Payment Buttons

Because manually created payment buttons are not saved on the PayPal website, you should use EWP to encrypt the button code before placing the code on your webpage. The following steps describe that process:

  1. Set Up Certificates before Using EWP
  2. Download and Configure EWP software for Manually Created Buttons
  3. Use the Downloaded Software to Manually Encrypt the Payment Button Code

Set Up Certificates

This section describes how to configure the public certificates and private keys on your server.

Important: The certificate security may already be set up on your server(s). To determine if you have a public certificate already installed, check your profile as described in the initial steps of the following procedure that details how to upload a certificate to your account.

To set up your certificates:

  1. Generate your private key
  2. Generate your public certificate
  3. Upload your public certificate to your PayPal account
  4. Download the PayPal public certificate from the PayPal website

PayPal uses only X.509 public certificates, not public keys. A public key can be used for decryption but contains no information identifying who provided the key. A public certificate includes a public key along with information about the key, such as when the key expires and who owns the key. PayPal accepts public certificates in OpenSSL PEM format from any established certificate authority, such as VeriSign.

You can generate your own private key and public certificate using open source software such as OpenSSL (https://www.openssl.org), which is detailed in the following section.

Generating Your Private Key Using OpenSSL

Using the openssl program, enter the following command to generate your private key. The command generates a 1024-bit ASRSA private key that is stored in the file my-prvkey.pem:

openssl genrsa -out my-prvkey.pem 1024

Generating Your Public Certificate Using OpenSSL

The public certificate must be in PEM format. To generate your certificate, enter the following openssl command, which generates a public certificate in the file my-pubcert.pem:

openssl req -new -key my-prvkey.pem -x509 -days 365 -out my-pubcert.pem

Uploading Your Public Certificate to Your PayPal Account

To upload your public certificate to your PayPal account:

  1. Log in to your PayPal business account at www.paypal.com.

  2. Click your profile name in the top right corner of your account and then click Account Settings.

  3. Click Website payments on the left side of the page, then in the middle click Update across from Encrypted payment settings. The Website Payment Certificates page opens.

  4. Scroll down the page to the Your Public Certificates section, and click the Add button at the bottom of the page. The Add Certificate page opens.

  5. Click the Browse button, and select the public certificate that you want to upload to PayPal from your local computer.

    Note: The file you upload must be in PEM format.

  6. Click the Add button. After your public certificate uploads successfully, it appears in the Your Public Certificates section of the Website Payment Certificates page.

  7. Store the certificate ID that PayPal assigned to your public certificate in a secure place. You need the certificate ID that PayPal assigned to encrypt your payment buttons by using the Encrypted Website Payments software provided by PayPal.

Downloading the PayPal Public Certificate From the PayPal Website

To download the PayPal public certificate:

  1. Log in to your PayPal business account at www.paypal.com.

  2. Click your profile name in the top right corner of your account and then click Account Settings.

  3. Click Website payments on the left side of the page, then in the middle click Update across from Encrypted payment settings. The Website Payment Certificates page opens.

  4. Scroll down the page to the PayPal Public Certificates section.

  5. Click the Download button, and save the file in a secure location on your web server which can be accessed from your website code.

Removing a Public Certificate

Important: If you remove your public certificate, its associated certificate ID is no longer valid for encrypting buttons, and any buttons that you generated or wrote manually for your website that use the ID will not function correctly.

To remove one or more of your public certificates:

  1. Log in to your PayPal business account at www.paypal.com.
  2. Click your profile name in the top right corner of your account and then click Account Settings.

  3. Click Website payments on the left side of the page, then in the middle click Update across from Encrypted payment settings. The Website Payment Certificates page opens.
  4. Scroll down the page to the Your Public Certificates section.
  5. Select the radio button next to the certificate you want to remove, and click the Remove button. The Remove Certificate page opens.
  6. Click the Remove button to confirm the removal of the public certificate that you selected.

Download and Configure EWP software for Manually Created Buttons

EWP includes both Java and Microsoft Windows versions of the software that needs to be downloaded and installed on your web server if you use manually created buttons. To use EWP to protect manually created payment buttons on your website, follow the procedure below to set up and configure EWP to work on your web server.

  1. Download either the Java or Windows software from the following location after logging in to PayPal: https://www.paypal.com/us/cgi-bin/webscr?cmd=p/xcl/rec/ewp-code
  2. Extract and store the software in a folder on your web server that can be accessed by your website code.
  3. Copy your private key, public certificate, p12 file and the PayPal public certificate to the same folder on your web server where the software is located.
  4. Update your PayPal account profile to block unprotected and non-encrypted payments. See Blocking Unprotected and Non-encrypted Website Payments for detailed instructions.

Use the Downloaded Software to Manually Encrypt the Payment Button Code

To use the downloaded software to manually encrypt the payment button code:

  1. Create a separate input file that contains PayPal Payments Standard variables and values for each encrypted button that you need to generate manually. Save the file(s) to a location on local system. Each variable and value must be on a separate line, as shown in the following example.

    Note: The cert_id variable identifies the public certificate you uploaded to PayPal website.

        cert_id=Z24MFU6DSHBXQ
        cmd=_xclick
        business=sales@company.com
        item_name=Handheld Computer
        item_number=1234
        custom=sc-id-789
        amount=500.00
        currency_code=USD
        tax=41.25
        shipping=20.00
        address_override=1
        address1=123 Main St
        city=Austin
        state=TX
        zip=94085
        country=USA
        cancel_return=https://example.com/cancel
    
    
  2. From the command line, run the encryption software using the appropriate syntax, as shown in the table below:

    SoftwareCommand Line
    Java
    java ButtonEncryption CertFile PKCS12File PPCertFile Password InputFile OutputFile [Sandbox]
    Microsoft Windows
    PPEncrypt CertFile PrivKeyFile PPCertFile InputFile OutputFile [Sandbox]

    The following are definitions for the properties used in the table above:

    PropertyDescription
    CertFileThe pathname to your own public certificate
    PKCS12FileThe pathname to the PKCS12-format of your own public certificate
    PPCertFileThe pathname to a copy of the PayPal public certificate
    PasswordThe passphrase to the PKCS12-format of your own public certificate
    InputFileThe pathname to file containing the non-encrypted Website Payments HTML Form variables
    OutputFileA file name for the encrypted output
    [Sandbox]The optional word Sandbox that lets you test payment buttons in the PayPal sandbox that you protected with Encrypted Website Payments
  3. Copy the code from the output file specified in the command run in the previous step, for each button. Then copy the encrypted button code for each button to the location you want to place the button on your website.

Blocking Unprotected and Non-Encrypted Website Payments

For extra security of your non-hosted encrypted payment buttons, update your PayPal account profile to block all non-encrypted payments. To block payments from unprotected and non-encrypted PayPal Payments Standard buttons:

  1. Log in to your PayPal business account at www.paypal.com .

  2. Click your profile name in the top right corner of your account and then click Account Settings.

  3. Click Website payments on the left side of the page, then in the middle click Update across from Website preferences. The Website Payment Preferences page opens.

  4. Scroll down the page to the Encrypted Website Payments section.

  5. Next to the Block Non-encrypted Website Payment label, select the On radio button.

  6. Scroll to the bottom of the page, and click the Save button.