PayPal Website Payments Pro

In this Topic: Show

Overview

This topic covers the PayPal Website Payments Pro payment gateway API. Refer to PayPal Payflow Pro for information about the payment gateway formerly known as Verisign.

Note: If your shopping cart is not yet set up to use PayPal, contact your web administrator/host for help with this—it is beyond the scope of this document and Stone Edge Technologies tech support to set up PayPal on your Website.

This feature is available in versions 5.4 and higher.

About API Access Credentials

Before you can use the Order Manager with PayPal Website Payments Pro, you must set up "API Access" credentials with PayPal. If you already obtained the necessary credential when you set up your shopping cart, then skip to the third section of this document, Setting System Parameters.

 

The Order Manager will need your PayPal "API" User Name and Password to access your PayPal account information. This is NOT your PayPal login – this is a login specifically assigned by PayPal for access to the PayPal API (Application Programming Interface) used by third party applications such as the Order Manager. PayPal also requires the use of either a "Signature" or a "Client Certificate" for user validation to allow access to the API. The Order Manager supports either option, so it is your choice as to which method to use.

IMPORTANT NOTE: If you have already been using PayPal Website Payments Pro on your website for payment processing, you may need to verify which security method detailed below is used by your website. You MUST configure the Order Manager to use the same method that is used by your website!

 

The Signature is the fastest and simplest authentication method, which uses an encrypted string value that you include with your API calls to identify yourself. This method is similar to using an additional password to identify which account is to be used to process the transaction. It is a bit less secure than using a Client Certificate.

 

A Client Certificate is a document provided by PayPal that uses public key/private key encryption of your account credentials. This method is much more secure than the Signature method discussed above, however, this method requires that you:

  1. encrypt the client certificate document (.pem file) received from PayPal using OpenSSL AND

  2. install the client certificate in Window’s Certificate Store on each PC which needs to access the PayPal website.

Obtaining PayPal API Access Credentials

  1. To obtain PayPal API Access credentials or review your existing PayPal API Credentials, go to PayPal’s Integration Center Support Page at the following URL: https://www.paypal.com/IntegrationCenter/ic_certificate.html.

  2. On the API Credentials page, there are links to instructions for creating your own PayPal API credentials. Click one of the following options follow the instructions on the PayPal Integration Center web page to obtain your PayPal API credentials:

    1. API Signature - If you choose the Signature method, complete steps 1-7 on the PayPal Integration Center API Signature web page, then return to this document, and starting with Configure the Order Manager and complete the remaining sections [skip Installing the Client Certificate on Your Workstation(s) section].

    2. API Certificate - If you choose, or are required to use the Client Certificate security option, please complete:

Step 1: Generate Certificate

Step 2: Encrypt Your Certificate on the PayPal Integration Center API Certificate page. Download the OpenSSL software.

  1. Skip the section, Step 3: Install the certificate in Paypal's documentation and return to this document and continue with the next section, Installing the Client Certificate on Your Workstation(s). (The section, Step 3: Install the certificate, on PayPal’s Integration Center page assumes you are installing the client certificate on a web server rather than a local computer.)

 

Note: If you have difficulty with OpenSSL, the installation of your Client Certificate in Window’s Certificate Store, or do not understand the instructions provided on PayPal’s Integration Center Web site, contact PayPal technical support for help.

 

IMPORTANT NOTE: API Credentials for PayPal’s production site and the PayPal test site (SandBox) are NOT interchangeable!!! Please be aware that if you attempt to use Test API credentials on PayPal’s production site or Production API credentials on PayPal’s SandBox (test site), you will receive errors in the Order Manager. Make sure you know which set of credentials is being installed in the Order Manager and set the PayPalTestMode parameter appropriately.

Installing the Client Certificate on Your Workstation(s)

If you are using the Client Certificate method of user validation, you will need to install the certificate on each workstation that runs the Order Manager.

  1. Once you have the .p12 file created by following the steps in Requesting an API Certificate on PayPal’s website, open Internet Explorer and go to Tools> Internet Options> Content tab. Click the Certificates button.

  1. This will open the Certificates dialog box. Click on the Import button to start the Certificate Import Wizard, and then click Next.

 

  1. Browse to the location of your .p12 file. Select the file and click Open. Click Next.

 

  1. You will be prompted to enter the Private Key Password entered during the .p12 creation process. Enter the password and leave the two check box options unchecked then click Next.

 

  1. Accept the remaining defaults by clicking Next and Finish on the next two screens. You should receive a confirmation of a successful import.

 

  1. The certificate should now appear in the Certificates dialog box under the Personal tab. The name that appears in the Issued To column represents the "Certificate Name" used in the Order Manager’s System Parameters.

Configuring the Order Manager

Credit Card Parameter Group

Once you have the PayPal API Access credentials, you must set up parameters in the Credit Cards Parameter Group.

  1. Go to Main Menu> Quick Clicks> System Parameters.

  2. In the Parameter Group, select Credit Cards.

  3. Set up the following system parameters:

 

CreditCardProcessor: If you will be processing new credit card payments at the Manual Orders and View Orders screens through the PayPal Direct Payment system, set this parameter (Credit Cards group) to "PayPal".

 

PayPalUserName: Enter the User Name issued to you by PayPal for access to the PayPal API.

 

PayPalPassword: Enter the Password issued to you by PayPal for access to the PayPal API.

 

If you chose the PayPal API Signature method of validation, then set the following:

PayPalSignature: Paste in the PayPal "signature" issued to you by PayPal for access to the PayPal API.

PayPalUseCertificate: Set this parameter to False

PayPalCertificateName: Leave this parameter empty

 

If you chose the PayPal API Certificate method of validation, then set the following:

PayPalUseCertificate: Set this parameter to True

PayPalCertificateName: Set this parameter to the Issued To name of the Certificate installed in your computer’s Certificate Store – typically the same as the API User Name.

PayPalSignature: Leave this parameter empty

 

PayPalTestMode: Set this parameter to True (default) to use the PayPal Sandbox for testing. Set this parameter to False to use the PayPal production site. Keep in mind that you will need separate API access credentials for the SandBox and the Production platform.

 

Check the settings of the main and/or cart-based system parameter, WebTransactionType to make sure it agrees with your workflow. The choices are Pre-Authorize or Sale. If payments will be captured via the Order Manager, it should be set to Pre-Authorize. If payment is captured at the web store, it should be set to Sale.

 

If you will also be processing credit card payments at the Point of Sale (POS) screen, you will need to set the corresponding Credit Card POS group system parameters.

 

Note: Keep in mind that PayPal’s Direct Payment system DOES NOT currently support "Card Present" transactions so is not recommended as a gateway for a high transaction POS.

Order Parameter Group

PayPalOrdersArePaidInFull: Starting with Order Manager Beta version 3.703, you can tell the program whether or not orders that are imported from a shopping cart and have PayPal as the payment method should be treated as "paid in full". To treat Web orders with the payment method "PayPal" as "paid in full", set the system parameter PayPalOrdersArePaidInFull in the Order group to True. It can also be set on a cart-by-cart basis by clicking the User, PC & Cart Based Parameters button on the Set System Parameters screen, selecting the Cart ID option, then the Order parameter group.

Create a Payment Method (only necessary for older versions of the Order Manager)

You must designate the Payment Method in the Order Manager called "PayPal" to properly integrate with PayPal Website Payments Pro.

  1. Go to Main Menu> Maintenance Menu> Maintenance tab.

  2. Select Payment Methods from the list.

  3. On the Payment Methods screen, type PayPal (with no space between "Pay" and "Pal") in the Payment Method Name field.

  4. Click Save and then Close.

Additional PayPal Payment Processing Information

The Order Manager cannot initiate payments through PayPal’s Express Checkout system since this depends on control of a customer’s browser (this cannot be done by the Order Manager), so if a customer places a manual order via telephone or at the POS, or if you are entering a new payment at the CCTerminal at View Orders, the customer CANNOT pay using their "PayPal account"; they must pay with a credit card, which the Order Manager will process through the PayPal Direct Payment system. The merchant can run either an authorization or a sale against the credit card. If the transaction is an authorization, the merchant can capture or void the transaction from the CCTerminal at View Orders, the Payment tab on Manual Orders, or at the POS screen. Captures can also be run from the Multi-Order Processor.

 

For orders imported from shopping carts, the Order Manager has the ability to perform Captures, Voids, or Reauthorizations against Authorized payments and can issue Credits against Sale or Captured payments regardless of whether the transaction was processed through the Direct Payment system or the Express Checkout system.

 

This set of actions is dependent on whether the shopping cart provides the Order Manager with the PayPal Transaction ID number. The following shopping cart systems currently provide the necessary information:

 

Should the Transaction ID number not be available from the shopping cart, the Order Manager will treat the order paid through PayPal as it has done in the past. If the PayPalOrdersArePaidInFull system parameter is set to True, the Order Manager will write a transaction against the order effectively "paying" it regardless of whether the payment has actually cleared your PayPal account.

 

Should the parameter be False, the Order Manager will not write a transaction against the order, leaving the order showing a balance due. It would be up to the merchant to verify with PayPal whether the payment was received. If payment is confirmed, the merchant can "Log a Payment" against the order.

 

In either case, PayPal transactions that do not have a Transaction ID will NOT be visible on the CCTerminal of the View Orders screen. These transactions cannot be managed using the new PayPal integration unless the merchant Edits the transaction and directly enters the PayPal Transaction ID number as shown below. Should the Edit button not appear on your View Orders screen, you must set the AllowEditTransactions (Security group) to True.

Once the PayPal Transaction ID is entered, the transaction will be visible on the CCTerminal and can be managed through the Order Manager.

Getting Details From PayPal Regarding a Payment

If an order has a PayPal transaction containing the PayPal Transaction ID, you will be able to view this transaction on the CCTerminal. Depending on the Status of the payment, the transaction’s State may show as "Approved" which represents a Pending transaction or will show as Captured representing a received payment. For payments made using the Direct Payment system, merchants may also see credit card information assuming this information is available from the shopping cart. Card data is not required to manage PayPal payments in the Order Manager.

 

IMPORTANT: Should the State column show as "n/a", the status of the transaction could not be verified by the Order Manager. This may occur if the order is being imported from a website that does not provide the transaction’s status and the Order Manager was unable to request the status from PayPal (parameters incorrectly set, no internet access, etc.). If this is the case, the Amount column will show as zero if the PayPalOrdersArePaidInFull system parameter is set to False or will show an amount equal to the Grand Total of the order if the PayPalOrdersArePaidInFull system parameter is set to True. These types of transaction should be verified through PayPal once the situation that prevented verification is resolved. Verification is discussed below.

 

The Payment below is a sale transaction run from Manual Orders:

The Payment below is a pending authorization imported from a shopping cart

The Payment Below could not be verified

Note the Amount column. Approved transactions show as being unpaid and the order should show as having a balance due. Captured Payments will reflect a dollar amount representing the amount you have been paid.

 

A transaction can be "pending" for a variety of reasons. Transaction may be an authorization or may be held back while awaiting clearance such as eChecks or currency conversion issues (Intl). Some of these types of transactions must be handled directly in the PayPal interface, not from the Order Manager. In situations such as these, the transaction may clear at PayPal but still show as pending in the Order Manager. The payment verification system is designed to compare the status between PayPal and the Order Manager to see if the Order Manager’s information should be updated.

 

You can verify a transaction’s status on PayPal by clicking on the Transaction in the CCTerminal. The Order Manager will recognize the payment as a PayPal transaction and will display the PayPal Details button next to the Transmit button. By clicking this, the Order Manager will request all details from PayPal regarding the transaction.

 

A pop-up will display the results of the request. Depending on the type of transaction, you may see different results.

 

Should the transaction’s status between PayPal and the Order Manager agree (or there is a major issue that cannot be resolved by the Order Manager), you will only see an OK button to close the pop-up. If the status between PayPal and the Order Manager does not agree, you may be asked to update the information in the Order Manager with the data from PayPal. This is recommended for transaction with a status of "n/a".

 

The following is a situation where the transaction in the Order Manager is showing as an authorization, however, the payment was manually captured in PayPal. Notice the information on the pop-up. By clicking OK, the transaction in the Order Manager is updated to reflect changes at PayPal. Clicking Cancel does not make any changes.

 

How to Process a Payment

All processing actions against PayPal payments are very similar to processing credit card transactions. If you want to capture an Authorized transaction, select the transaction in the CCTerminal, set the Transaction Type to Delayed Capture then click the Transmit button. While PayPal allows multiple captures against a payment, the Order Manager will only support one capture per transaction. This is true for all gateways we support.

 

If you want to Void an Authorization to release the customer’s funds, select the transaction in the CCTerminal, set the Transaction Type to Void then click Transmit. Remember that you cannot void a sale or captured transaction. These must be Credited instead.

 

To Credit a Sale or Captured transaction, select the transaction, set the transaction type to Credit, set the credit amount (if not already set) then click Transmit. You may issue multiple credits against a single transaction. The sum of the credits issued cannot exceed the amount of the original transaction.

 

QuickBooks Considerations

Due to the inconsistencies between all of the shopping cart systems we support, transactions run through PayPal’s Direct Payment system cannot be written into the Order Manager as Credit Card payments. Most of the carts supporting this interface do not maintain the credit card number or type. PayPal’s interface for retrieving payment details also does not report either detail, so in many instances the Order Manager would not know which card was used, so all transactions run through a PayPal interface will be marked as "PayPal" payments. When exporting deposit data to QuickBooks, all of these payments will feed into the account defined for PayPal deposits. There is further breakdown into Direct Payment vs. Express Checkout vs. Visa or MasterCard, etc.

Troubleshooting

Users of all versions of the Order Manager should check the value of the Internet Explorer Security setting "Submit Nonencrypted form data" on each workstation that import orders, as described in the Knowledge Base article, Error -214702489 Access Denied.

 

Created: 1/30/12

Go to Top