24/7 Support: 800.608.6482


PayPal Commerce Platform

1. Overview

2. Installation

3. Setup & Configuration

4. Enabling & Disabling Payment Methods

5. Credit Card Payments

6. PayPal Button Placement Best Practices

7. Button Configuration Settings

8. Template Changes

9. Depreciated PayPal Modules


The PayPal Commerce Platform is the newest payments platform from PayPal which includes PayPal Checkout (previously named PayPal Express Checkout), Credit Card Payments, and PayPal Credit (including upcoming Pay in 4 functionality). This is a completely new integration with the intention of replacing all previously existing PayPal Products including PayPal Payments Pro and Payflow Pro. Customers must manually turn on PayPal Commerce Platform and turn off any existing PayPal modules prior to use.

PayPal Commerce is the recommended payments solution for Miva.


You must be on Miva 10.00.00 or higher to use PayPal Commerce Platform.

To install the PayPal Commerce Platform, navigate to the store level Modules screen. This is under the Settings Menu at the bottom Right, then Modules.

PayPal Commerce Platform - Miva

Either filter by module type of “Payment” or search for “PayPal”

PayPal Commerce Platform - Miva

PayPal Commerce Platform should be the first payment module in the list. To install on your store click the install button.

Once installed you’ll see a new tab on the payments screen for “PayPal Commerce Platform” where you configure the module

PayPal Commerce Platform - Miva

Setup & Configuration

Once the module is installed, you only need to link your PayPal account to get started. There are no API keys to manually enter.


Environment: Sandbox or Production - If you have an existing account linked, changing from Sandbox to Production or vice versa will clear your linked account settings. This is also a way to clear the account to link a new account if you needed to.
PayPal Handoff Message: This is an optional message displayed to the customer only when they choose PayPal as a payment option from OSEL (not using the PayPal buttons)
Transaction Mode: Automatic Capture or Authorization Only
Currency: The currency you want to settle payments in

  1. No Linked PayPal Account
  2. Pending – Your email address needs to be confirmed before processing payments (This applies to newly created PayPal accounts only)
  3. Linked – Your account is approved for PayPal Payments. Ability to accept credit card payments is pending.
  4. Linked – Your account is approved for PayPal Payments. Ability to accept credit card has been denied. [ In this case PayPal typically needs additional information ]
  5. Linked – Active and ready to accept payments

Card Field Styles

This is a JSON object which can be used to style the PayPal Credit Card Inputs.

Connecting Your PayPal Account

Click the “Connect” Button to link your PayPal account. You’ll see a PayPal login screen.

PayPal Commerce Platform - Miva

Login using your PayPal account and grant Access for Miva to connect to your PayPal account.

Once completed close, the popup window

PayPal Commerce Platform - Miva

Miva should automatically refresh the settings screen to show you an updated status message.

PayPal Commerce Platform - Miva

Note: After you have sucessfully linked your account, the email address tied to that account will be displayed. This will show you which PayPal account is linked to your Miva store in the event you have multiple PayPal accounts.

Enabling & Disabling Payment Methods

By default, when you setup the PayPal Commerce Platform, it will create two payment methods. One for Credit Card Payments and another for PayPal. If you only wish to use one of these payment methods, you must hide the other under Setting -> Payment Setting -> Payment Method Rules.

PayPal Commerce Platform - Miva

If for example has a different Gateway setup for Credit Card payments such as Braintree and you only wanted to configure PayPal, you can click on the Credit Card method and check the option for “Exclude This Option Unless Permitted By Products” This will hide it globally.

PayPal Commerce Platform - Miva

You could also setup exclusions rules to hide the method as well to hide the method you do not wish to show.

Credit Card Payments

Once your account has been linked and approved for credit card payments, there is no additional configuration needed. A new payment method will show during checkout labeled “Credit Card”

PayPal Commerce Platform - Miva

Note: PayPal will auto-detect the card type, so the customer does not need to select it here.

Then on OAPY you’ll see the card fields:

PayPal Commerce Platform - Miva

Customizing Checkout Styling

If you wish to customize the styling of these fields further, there is also a CSS stylesheet which gets created when the PayPal module is installed

User Interface -> CSS/JS Resources -> CSS Resources -> paypalcp

PayPal Commerce Platform - Miva

Miva Admin - Void, Capture, Refund

PayPal Commerce platform supports all the payment features of Miva including the ability to Void, Refund, Capture and issues new Authorizations via the Admin. This also includes multiple partial captures and Mutiple partial refunds.

PayPal Commerce Platform - Miva
PayPal Commerce Platform - Miva

Transaction Status

PayPal now has a new transaction status field which gets returned in each payment response. There are 5 different statuses:

  • COMPLETED. The funds for this captured payment were credited to the payee's PayPal account.
  • DECLINED. The funds could not be captured.
  • PARTIALLY_REFUNDED. An amount less than this captured payment's amount was partially refunded to the payer.
  • PENDING. The funds for this captured payment was not yet credited to the payee's PayPal account.
  • REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.

Most orders will come back with a status of completed. However its possible for some orders to enter a manual fraud review which should have the transaction status of pending. Orders with this status should not be shipped. Based on the results of the review the status will eirther change to completed, or declined.

PayPal Commerce Platform - Miva

Using Order Workflows to Filter by Transaction Status

Miva's Order Workflow Tool can help you create automated rules to move orders with a transaction status of pending into its own queue. This way they can be manually be reviewed or integrations to ERP/OMS systems can ignore these orders until they are approved.

PayPal Commerce Platform - Miva

PayPal Checkout

In addition to accepting credit cards directly on your Miva site, the PayPal Commerce Platform also includes the ability to accept PayPal via the PayPal Smart Buttons.

PayPal Commerce Platform - Miva

These buttons bring up the in-context PayPal checkout experience which allows you to pay via PayPal without leaving the Miva site.

The PayPal Checkout experience has been improved and checkout steps removed in this new version compared to previous Express Checkout flows.

New Checkout Experience

The biggest difference is that you now complete the entire checkout process right in the PayPal modal.

You will be presented with shipping methods which pull directly from Miva and any Shipping Method Rules will be applied as if the customer is going through the standard Miva checkout.

PayPal Commerce Platform - Miva

Tax is also calculated and displayed. Tax will be calculated using whatever tax module you have configured in Miva.

PayPal Commerce Platform - Miva

Finally, you click Pay. The modal will close, and Miva will reload the screen directly to Invoice. The standard Miva checkout process is completely skipped.

If you have things like coupons or order notes which need to be accepted via PayPay, they need to be put on the BASK screen so that the customer can apply the coupon prior to clicking PayPal.

Because the standard Miva checkout is bypassed with PayPal checkout, customer credit and points are not available when using PayPal from the Basket/Product screens.

PayPal on Shipping Selection Screen

There is an alternate way to use PayPal as a payment methods and still use the standard checkout. If the customer does not click on the PayPal smart buttons but instead uses the regular Miva checkout, they will be presented with PayPal as a payment option on the Shipping / Payment selection screen (OSEL)

PayPal Commerce Platform - Miva

When you select PayPal you will see the PayPal handoff message which is customized during the module setup:

PayPal Commerce Platform - Miva

Clicking “Complete Order” will then take you off site to PayPal to Pay and redirect you back to Invoice once complete

PayPal Commerce Platform - Miva

Product Page vs Basket Experience

There are versions of the PayPal Buttons. There is a “quick buy” experience which is intended for the product page. When used, it will ignore any other items you have in the cart and only purchase the item you are clicked the payment button from.

The standard version which is intended to be used on the basket and checkout pages will purchase the entire basket.

PayPal Button Placement Best Practices

For new installations of Miva on 10.00.00 or later, when you activate the PayPal Commerce platform, the PayPal buttons (and Credit Banners) are automatically placed in the optimal locations. These can then be customized based on your site's individual needs.


PayPal Commerce Platform - Miva

Product Page

PayPal Commerce Platform - Miva

The product page version of the PayPal Checkout buttons will only purchase the product your viewing. It ignores any other items in the cart.

Basket Page

PayPal Commerce Platform - Miva

Order Login

PayPal Commerce Platform - Miva

Customer Information

PayPal Commerce Platform - Miva

Shipping & Payment Selection

PayPal Commerce Platform - Miva

Button Configuration Settings

On any page you wish to display the PayPal buttons or Credit Banners you need to assign the PayPal Items to the page.

There are two items:

PayPal Commerce Platform - Miva

Paypalcp_buttons – This is used to display the PayPal Payment buttons

Paypalcp_credit – This is used to display the Paypal Credit Banners

By default the items are assigned to the following pages:

PayPal Credit (paypalp_credit)
  • SFNT
  • PROD
  • BASK
  • ORDL
  • OCST
  • OSEL
PayPal Smart Buttons (paypalcp_buttons)
  • PROD
  • BASK
  • ORDL
  • OCST

When an item is assigned to any page, you’ll have some point and click settings to adjust the button styles

PayPal Commerce Platform - Miva

These can be customized to match your site look and feel. Please reference this doc for the different button settings:


Template Changes

When the PayPal module is installed it automatically creates a ReadyTheme Content Section called “PayPal Commerce Platform Configuration”. This content section has the default PayPal Button and PayPal Credit code for each screen:

PayPal Commerce Platform - Miva

By default, Shadows will have the ReadyTheme item output in all the locations recommended for PayPal’s Button placement best practices.

PayPal Commerce Platform - Miva

If you wish to edit or change button placement locations, you can either edit the code in the PayPal configuration Content Section or remove the item tag altogether.

Note: This new item will exist in the page template code even if PayPal is not installed. Because the content section does not exist unless PayPal is installed, it will simply be ignored.

For existing merchants upgrading to this new integration, it will be up to the developer to place the ReadyTheme Item in the locations required.

Template Code Reference

Depreciated PayPal Modules

When version 10.00.00 is initially installed all PayPal module not being used will be removed from the store. As of version 10, all old PayPal modules are being depreciated.

Existing PayPal Modules being used such as Express Checkout will continue to work, however no future updates will be made to them. It is recommended that merchants have a plan to migrates from any of the old PayPal modules to the new PayPal Commerce Platform.

These modules include:

  • PayPal Express Checkout
  • PayPal Payments Pro
  • PayFlow Pro
  • PayPal Link

Looking for Developer Docs?

We have a whole section for that, including: Developer Training Series, Template Language docs, Module Development tutorials and much, much more.

Head to the Developer Section

This website uses cookies to identify visitors, track visitors to our website, store login session information and to remember your user preferences. By continuing to use this site you agree to our use of cookies. Learn More.

This website uses cookies. By continuing to use this site you agree to our use of cookies. Learn More.


Copyright © 1997 – 2019 Miva©, Miva Merchant©, MivaPay©, MivaCon© Miva, Inc. All Rights Reserved.