PayPal Website Payments Pro

Contents of this Topic: Show

Overview

This topic discusses the steps required to use the PayPal Website Payments Pro payment gateway API with Stone Edge.

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 SEOM tech support to set up PayPal on your Website.

About API Access Credentials

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

SEOM needs 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 SEOM. PayPal also requires the use of either a "Signature" or a "Client Certificate" for user validation to allow access to the API. SEOM 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 SEOM 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 Configuring Stone Edge 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 SEOM. Make sure you know which set of credentials is installed in SEOM 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 SEOM.

  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 opens the Certificates dialog box. Click 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 are prompted to enter the Private Key Password provided during the .p12 creation process. Enter the password and then click Next (leave the two check boxes cleared) .

 

  1. Accept the remaining defaults by clicking Next and Finish on the next two screens. You should receive 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 SEOM's system parameters.

Configuring SEOM

Credit Cards Parameter Group

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

  1. Go to Main Menu > Settings > System Functions > System Parameters.

  2. In the Credit Cards Parameter Group, set the following system parameters:

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

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

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

    4. 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.

    1. 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.

    1. 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 platforms.

    2. 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 SEOM, it should be set to Pre-Authorize. If payment is captured at the web store, it should be set to Sale.

Credit Cards POS Parameter Group

This parameter group can be skipped if you do not have the PlusPOS or Enterprise Editions of SEOM, or do not use the POS system.

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.

  1. Go to Main Menu > Settings > System Functions > System Parameters.

  2. In the Credit Cards POS Parameter Group, set the following system parameters:

    1. CreditCardProcessorPOS: 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".

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

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

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

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

PayPalUseCertificatePOS: Set this parameter to FALSE.

PayPalCertificateNamePOS: Leave this parameter empty.

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

PayPalUseCertificatePOS: Set this parameter to TRUE.

PayPalCertificateNamePOS: 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.

PayPalSignaturePOS: Leave this parameter empty.

    1. PayPalTestModePOS: 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 platforms.

Order Parameter Group

  1. Go to Main Menu > Settings > System Functions > System Parameters.

  2. In the Order Parameter Group, set system parameter:

    1. PayPalOrdersArePaidInFull: To treat Web orders with the payment method "PayPal" as "paid in full", set this to TRUE. It can also be set on a cart-by-cart basis by clicking PC & Cart Based Parameters on the Set System Parameters screen, selecting the Cart ID, and then the Order parameter group.

Create a Payment Method for PayPal Transactions

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

  1. Go to Main Menu > Settings > Data Functions > Payment Methods.

  2. Click Add New.

  3. Enter PayPal (with no space between "Pay" and "Pal") and click OK.

  4. Click Close.

Additional PayPal Payment Processing Information

SEOM cannot initiate payments through PayPal’s Express Checkout system since this depends on control of a customer’s browser, which SEOM is unable to do.

If a customer places a manual order via telephone or at the POS, or if you are entering a new payment at the Payment tab of Process Orders, the customer CANNOT pay using their "PayPal account", they must pay with a credit card.

SEOM processes the transaction 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 Payment tab of Process Orders or Manual Orders, or at the POS interface. Payments can also be captured at the Multi-Order Processor.

For orders imported from shopping carts, SEOM 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 SEOM 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, SEOM treats the order paid through PayPal as it has done in the past. If parameter PayPalOrdersArePaidInFull is set to TRUE, SEOM writes a transaction against the order, effectively "paying" it regardless of whether the payment has actually cleared your PayPal account.

Should the parameter be FALSE, SEOM does 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 at the Payment tab of the Process 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. Should the Edit button not appear on your Process Orders screen, you must set the AllowEditTransactions (Security group) to TRUE.

Once the PayPal Transaction ID is entered, the transaction is visible on the Payment tab and can be managed through SEOM.

Getting Details About a Payment From PayPal

If an order has a PayPal transaction containing the PayPal Transaction ID, you will be able to view this transaction at the Payment tab of the Process Orders screen. Depending on the Status of the payment, the transaction’s State may show "Approved" (which represents a Pending transaction) or "Captured" (representing a received payment). For payments made using the Direct Payment system, merchants may also see credit card information,  assuming this information is provided by the shopping cart. Credit card data is not required to manage PayPal payments in SEOM.

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

 

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 SEOM. In situations such as these, the transaction may clear at PayPal but still show as pending in SEOM. The payment verification system is designed to compare the status between PayPal and SEOM to see if SEOM’s information should be updated.

 

You can verify a transaction’s status on PayPal by clicking on the Transaction at the Payment tab of Process Orders. SEOM recognizes the payment as a PayPal transaction and displays the PayPal Details button next to the Transmit button. By clicking this, SEOM requests 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 SEOM agree (or there is a major issue that cannot be resolved by SEOM), you will only see an OK button to close the pop-up. If the status between PayPal and SEOM does not agree, you may be asked to update the information in SEOM with the data from PayPal. This is recommended for transaction with a status of "n/a".

 

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 SEOM 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 SEOM would not know which card was used, so all transactions run through a PayPal interface are marked as "PayPal" payments. When exporting deposit data to QuickBooks, all of these payments 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 should check the value of the Internet Explorer Security setting "Submit Nonencrypted form data" on each workstation that imports orders, as described in the Knowledge Base article, Error -214702489 Access Denied.

 

Additional Information

Process Orders

Set System Parameters

Special System Parameters

Error -214702489

Created:

Revised: 4/15/13

Published: 04/13/16