PayPal

Important PayPal API Update Available - June 2023

Integration Update Notice (June 2023)

Attention Merchants, UltraCart has a new API integration with PayPal, please upgrade to the new API in order to take advantage of the new functionality and better user experience that the new API provides: Upgrading to PayPal Order API (2023) 

Benefits

  • Improved checkout experience for customers using a modal instead of a browser redirect.

  • Improved analytics tracking because customers are not redirected off domain for PayPal.

  • Additional payment options for customers including PayPal PayLater and Venmo

  • Dual Vaulted payment information for credit cards, PayPal, and Venmo.

  • Superior subscription rebilling initiated from UltraCart

  • Ability to adjust anything on an auto order paid for with PayPal.




Overview

PayPal is an industry leader in payment processing services. PayPal can be implemented as a supplemental payment processing service as well as an all-in-one payment processing service that combines the PayPal-to-PayPal payment processing along with direct credit card processing (where the customer in the UltraCart checkout without any redirect to the PayPal website for login.

Business PayPal Account

You'll need a business paypal account. To upgrade your current PayPal Personal Account to a Business or PremierAccount: Go to https://www.paypal.com/UPGRADE and log in to your PayPalaccount. Click the Upgrade Now button at the bottom of the page. The next page will allow you to choose a personal Premier Account or a Business Account.

Integration Options


There are two integration options to choose from: Express Checkout & Website "Payment Pro".

Navigation

Main Menu → Configuration → checkout → Payments → Methods [tab]


The following shows the Payments screen. The Method Tab is already selected by default.  Select PayPal by clicking the check box to the left of PayPal. 


Notice below the screen has changed by limiting content to only the payment method you selected; in this case, PayPal. Also, PayPal is added in the Tabs list on the left.   It will remain there until you deselect (disable) PayPal.

Express Checkout

The Express Checkout integration requires only a basic business PayPal account. This option will redirect the customer to your company landing page at PayPal.  There, the customer will be prompted to create an account or log in to an existing account to complete the payment. Then the customer is redirected back to the UltraCart checkout to receive the purchase receipt. Express Checkout works seamlessly with any integrated credit card transaction gateway, and is a preferred choice for many customers, especially those that may have credit issues or are particularly interested in maintaining a level of privacy.

Advanced View for Additional Settings

The choices section will then expand to give you more settings.

 

Integration Instructions

  1. Enter your business email address associated with your PayPal business account (if you have a personal PayPal account, you'll need to upgrade it to a business account.)
  2. Choose "Express Checkout" from the "Integration Method" drop-down menu
  3. Configure your "Instant Payment Notification (IPN) to the following URL:       https://secure.ultracart.com/cgi-bin/UCPayPalNotify 
  4. Set Third-Party API permissions to:  paypal_api1.ultracart.com
  5. From the "Advanced Options" section choose "Live" from the drop-down menu.

(There are other optional fields which you can configure which will affect the look and feel of your PayPal landing page.)
   

Once you've finished with the Express Checkout configuration click SAVE at the bottom.  Return to the UltraCart Payments screen to confirm your settings.
 

Notice in the screen shot below that PayPal is now listed below the Methods Tab. All configured methods will appear in this list.  



Website Payments Pro (Express Checkout and Direct Payments)

The PayPal Website "Payments Pro" integration is an All-In-One integration in which PayPal will handle both PayPal-to-PayPal payments ("Express Checkout") and credit card authorizations ("Direct Payments") 

This is a great option for new businesses because the Payments Pro service can be added to the basic paypal service without the more extensive credit application process associated with a standard stand-alone merchant account and transaction gateway solution. Another benefit is that the Payments Pro service does not lock you into a long term contract.


PayPal requires you to have a PayPal Business Account If you want to sign up for Website Payments Pro (Direct Payments and/or Express Checkout).  If you have only a Personal Account, you will be asked to upgrade or open a new business account during the application process.  To start the application process, log in to your PayPal account and click on the "Merchant Services" tab at the top of the screen. 

Application Process

The next screen will be presented only if you DO NOT have a PayPal Business Account.  You can choose to UPGRADE your existing personal account or CREATE a NEW account.  Click the button of your choice.

Merchants upgrading or creating a new business account might see a few additional screens before being presented with the Website Payments Pro application screen.

Website Payments Pro application

Next you will be presented with an Application consisting of 4 screens. The majority of the information required will be filled in if you already have a Business Account.

In addition to completing your account information, the 1st screen (shown below) requires you to agree to some terms. 

Complete all the required fields on all screens.  When you've completed the application, click on the "Submit application" link on the right side of the page.

Once your application is accepted, you will be returned to the "My Account" screen where you will be presented with the current monthly fee for your PayPal service. If you agree, click the "Agree" button. You will then be taken to the API Credentials screen.

Completing "Payments Pro" integration with UltraCart

Integration Instructions

  1. Enter your business email address associated with your PayPal business account (if you have a personal PayPal account, you'll need to upgrade it to the business account.)
  2. Choose "PayPal Website Payments Pro (Express Checkout and Direct Payments)" from the "Integration Method" drop-down menu
  3. Configure your "Instant Payment Notification (IPN) to the following URL:       https://secure.ultracart.com/cgi-bin/UCPayPalNotify  
  4. Set  Third-Party API permissions  to:  paypal_api1.ultracart.com
  5. From the "Advanced Options" section choose "Live" from the drop-down menu.
  6. Click the save button

(There are additional, optional configuration fields, which you can configure which will affect the look and feel of your PayPal landing page.)

Configuring PayPal to properly handle Customer Telephone

By default, the customer email address is the primary contact information for a paypal customer. If you prefer to have the customer telephone number to also be stored in the paypal transaction, you'll need to complete the following configuration: PayPal Customer Telephone Number

Recurring Payments (Subscriptions)

WARNING

The current API integration with PayPal does not support recurring payments for digitial items for new merchants.

PayPal Account Settings for Subscriptions

PayPal requires Enhanced Recurring Payments enabled for recurring (also known as subscriptions or auto orders) payment processing.   

Please see their standard agreement, as this involves an additional monthly cost to your PayPal account: https://www.paypal.com/us/webapps/mpp/ua/us-erp-full

To enable recurring payments on your PayPal account, login to www.paypal.com and navigate to Tools → Recurring Payments → Related Items → Sign up for Enhanced Recurring Payments.

As of Sept 2017, the direct link to that page is this: https://www.paypal.com/us/cgi-bin/webscr?cmd=_product-go&product=premium_services

You will need to review the agreement and click the Agree and Continue button to activate this PayPal feature.

WARNING

PayPal policy is to not allow the addition of PayPal Enhanced Recurring Payments from paypal accounts which had the PayPal Pro integration and then subsequently reverted back to the standard Express Checkout Only configuration.

(*The workaround to this, according to PayPal support, is to open a new account then integrate that account to your UltraCart account.)

3rd Party API Permission for Auto Orders / Subscriptions

If you have integrated using the third party API, then you'll need to make sure that the following permission is enabled: "Create and Manage Recurring Payments"

IMPORTANT NOTE: Limitations & Restrictions to PayPal & Auto Orders

Important note regarding Restrictions and limitations to PayPal & Auto orders

These limitations are caused by PayPal's inability to handle the same level of customization that UltraCart's recurring orders possess.  

  1. No coupons.  A coupon present on a recurring order will cause PayPal to be unavailable as a payment option.
  2. Auto order items must have only one schedule (An annual subscription item can't change to a monthly rebill at a later point).  PayPal cannot handle multiple schedules on the same auto  order record
  3. Pause steps are not supported.
  4. Multiple "Customer-Selectable" configured auto order items are not supported.  We cannot guarantee the items will end up with the same schedule. 


There are two possible actions in regard to an active auto order:

  1. Cancel →  cancels the auto order. The auto order cannot be reactivated once it has been cancelled.
  2. Suspend →  pauses the auto order until you manually unsuspend the auto order.


UltraCart Account Settings for Subscriptions

Navigate to Configuration → Back-OfficeAuto Order ProcessingPayment Settings → Paypal (Section) Advanced Settings (button) →  "Send Recurring Flag" Select Yes, then save the changes.

Follow the instructions there.

Managing Auto Orders with Paypal Payment

When viewing the auto order record of a recurring payment in UltraCart, you'll see the following message regarding the management of the subscription:

Active

This order is managed by PayPal.
Each item is a different transaction and may be managed below.

You are able to cancel or suspend the auto order from the Ultracart auto order record, by clicking the "Cancel" or "Suspend" button located in the item table,
at the bottom of the auto order tab of the auto order.

PLEASE NOTE: You must log into your PayPal account in order to make modifications to the rebill schedule.



Merchants Operating multiple UltraCart accounts

The same PayPal business account should not be associated with multiple UltraCart accounts. Merchants that are operating several UltraCart stores should sign up for a different PayPal account for each.
6

Third Party API permissions


To grant permissions to a third party:

  1. Log in to PayPal with your Personal or Business account. If you do not have an account, create one.
  2. Click Profile at the top right, and select Profile and Settings.
  3. In the left menu, click My selling tools.
  4. In the Selling online section, click Update next to API access.
  5. On the API Access page, click Grant API Permission.
  6. Enter the name of the user to whom you will grant permissions. If you do not know the third party's PayPal user name, contact the third party to request this information.
  7. On the Add New Third Party Permissions page, select the types of permissions you want to grant to the third party and click Add.




In order to properly handle the payment processing, please make sure that you have the following PayPal permissions enabled.

If any of these permissions are not configured on your account, the payment processing will encounter errors that prevent the properly processing of the customer payment for their purchase.

Permissions For Normal TransactionsAdditional Notes
SetExpressCheckout
GetExpressCheckoutDetails
DoDirectPayment
DoCapture
DoVoid
RefundTransaction
Permissions for Paying Affiliates via PayPalAdditional Notes
GetBalance
MassPay

First Party Credentials

Please see the following document that covers the configuration of the First Party Credentials.

Testing Your PayPal Integration

Testing Integration

To test your PayPal integration, you'll need to place a real order using either a personal paypal account (separate of your business paypal account) or for the Payments Pro integration, a real credit card (not configured as a test CC in the ultracart backend) then once you see a successful authorization occur for the payment, you can perform a refund to back out the charge associated with your test purchase.

PayPal Errors

API Error Notifications Emails

If UltraCart recognizes PayPal permissions configuration within your PayPal account that is preventing proper processing of payment transactions for your order, you may receive email notifications to that effect.

The email notification will be sent out to all users on the account that have the "edit settings" permission configured.

Allow UltraCart To Call The [chargeCreditCard] API

If you do not have the chargeCreditCard API permission turned on, you receive a message like this (body text below):

Subject: UltraCart [UC MerchantID] - PayPal permissions incorrect.

Hi <name of merchant as listed on the user login>,

This automated email is to inform you that your PayPal integration has not been configured properly to allow UltraCart to call the [chargeCreditCard] API.  Please contact support for assistance in adjusting your configuration.

-UltraCart


The solution 

To fix this issue, login to your PayPal account and:

1) Under the My Account menu click on the Profile option.
2) On the left side of the page under My Profile click on My Selling Tools.
3) Click the Update link to the right of API Access.
4) Edit the API access and grant permission for UltraCart to call [chargeCreditCard]

Until you grant permission for UltraCart to call chargeCreditCard, your customers can not use direct credit cards during the checkout.  This is limiting your sales to PayPal only.




About repeated notices

This message gets triggered whenever PayPal returns error code 10002 for a transaction. So, you may receive this notification multiple times.

If transactions were previously processing through PayPal okay then suddenly you receive these problem notices, its possible that PayPal is experiencing some sort of temporary processing problem on their end. You should investigate with paypal and make sure that you have the [chargeCreditCard] configured.

*IF you do, then you should contact paypal to inquire about processing issues on their end.

UltraCart has received ERROR: 10501

Hi <name>,

UltraCart has received ERROR: 10501 Invalid Configuration This transaction cannot be processed due to an invalid merchant configuration from PayPal.

Make sure that you have accepted the "PayPal Payments Pro" agreement in your PayPal account after you have been approved by PayPal for PayPal Payments Pro. If you have accepted their agreement but are still getting this error, PayPal also occasionally acknowledges the agreement and activates Virtual Terminal but somehow misses activating PayPal Payments Pro itself; if your PayPal "Get Started" summary screen only shows Virtual Terminal and nothing about PayPal Payments Pro, please contact PayPal support to get your PayPal Payments Pro service activated.

If you are only using PayPal Payments Standard with a regular PayPal personal, Business or Premier account (i.e., if you have not upgraded to PayPal Payments Pro), please go to Seller Admin > Payment Preferences and make sure you have PayPal Payments Standard checked (rather than PayPal Payments Pro) and click Submit to save any changes you make.

-UltraCart


The solution 

 

To fix this issue, login to your PayPal account and:

1) Under the My Account menu click on the Profile option.
2) On the left side of the page under My Profile click on My Selling Tools.
3) Click the Update link to the right of API Access.
4) Edit the API access and grant permission for UltraCart to call [doCapture]

Until you grant permission for UltraCart to call doCapture, the orders will be stuck in "Payment Status = pending".

About Authorization Model


Authorization Model

The configuration of the "Authorization Model" will affect the point at which the authorized payment is captured:

  • "Auth and Capture" - Capture will occur upon the authorization when the customer is sent over to paypal to make their payment
  • "Auth then Capture" - "doCapture" call will occur when the order is marked as shipped from the shipping department.

Paypal Errors

Here is a link to a spreadsheet of PayPal Virtual Terminal error responses, what they mean, and what you can do about them:

https://www.paypalobjects.com/en_US/vhelp/servicemanagement_help/vterror.htm

Here is a list of Address Verification System Responses:

https://www.paypalobjects.com/en_US/vhelp/servicemanagement_help/avs_response.htm

Here are some of the common errors that we see in UC Accounts:


error codeerror meaning
0005The transaction was declined without explanation by the card issuer
0013The transaction amount is greater than the maximum the issuer allows.
0014The issuer indicates that this card is not valid.
0043The card has been reported stolen
0051The credit limit for this account has been exceeded.
0054The card is expired.
1015The credit card number was invalid
1511

Duplicate transaction attempt.


Affiliate Management MassPay API Errors


PayPal MassPay Errors related to processing affiliate commissions via PayPal MassPay

While attempting to process payments for affiliates, an error appears on the page that says "PayPal MassPay API failed. You do not have permissions to make this API Call". This error means that you need to grant access to that particular API call within your PayPal account so that UltraCart can call it. Log into your PayPal account, then navigate:

PayPal Navigation

My Account → Profile → My Settings → My Selling Tools → API Access [update].


Under that section within PayPal.com, you'll need to give the UltraCart API login the additional permission to do MassPay, then save the changes.


PayPal AMEX Support

PayPal now requires all merchants that would like to use AMEX in their PayPal account to sign an agreement directly with American Express. 

Error Message

If you are getting the following error:

L_ERRORCODE1

10566

L_LONGMESSAGE1

The credit card type is not supported

L_SEVERITYCODE1

Error

L_SHORTMESSAGE1

Credit card type unsupported

this means that you have not accepted the PayPal AMEX agreement. Until you do this on your PayPal account it will not support American Express. You can read more about this at PayPal's AMEX Update.

Frequently asked Questions


Question: We upgraded from the legacy API to the new PayPal API and are now seeing that our paypal orders are showing the following message n the status section of the auto order editor: 'PayPal details lack status.' Is the auto order now broken?

Answer: While PayPal is not longer reporting a status for the auto order, Ultracart will capture any payments send back via the Instant Payment Notification, and will process the order accordingly. You will, however, need to log into PayPal to cancel or modify the existing auto order.

Question: I have an item configured with $0.00 item cost and a flat shipping cost. When I test a checkout with this item, I'm getting an error message that Paypal cannot process a free offer. Why?

Answer: Paypal has a strict policy that items must be configured with a item cost in order to allow a payment to be processed. Shipping fee's alone will not work. The minimum cost that PayPal will allow for an item is $0.01.


Related PayPal Knowledgebase Articles

Paypal-UltraCart Integration

https://developer.paypal.com/docs/payflow/fmf/integration-guide/FMFSetup/#configuring-your-fraud-management-filters