PayPal Commerce Platform

Overview

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 recently launched 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.

Installation

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.

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

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

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.

Settings

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). This message is blank by default and shows on OPAY (payment page) before the customer leaves the Miva store to go to PayPal.
Transaction Mode: Automatic Capture or Authorization Only
Currency: The currency you want to settle payments in
Status:

No Linked PayPal Account
Pending – Your email address needs to be confirmed before processing payments (This applies to newly created PayPal accounts only)
Linked – Your account is approved for PayPal Payments. Ability to accept credit card payments is pending.
Linked – Your account is approved for PayPal Payments. Ability to accept credit card has been denied. [ In this case PayPal typically needs additional information ]
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.

Once completed close, the popup window

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

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.

If, for example, your store 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.

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”

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

Then on OPAY you'll see the card fields:

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

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.

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.

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

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.

Tax is also calculated and displayed. Tax will be calculated using whatever tax module you have configured in 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)

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

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

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.

Storefront

Product Page

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

Order Login

Customer Information

Shipping & Payment Selection

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:

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

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

https://developer.paypal.com/docs/checkout/integration-features/customize-button/

Disable Funding Sources

Here is a full list of possible values to disable different funding sources: https://developer.paypal.com/docs/checkout/reference/customize-sdk/#disable-funding

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:

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

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

PayPal Pay In 4 / Pay Later

The PayPal Commerce Platform Integration supports PayPal's latest Pay In 4 Features. The monthly payments for Pay in 4 are shown when using the PayPal Credit banners. Below are some details on who is eligible to use Pay In 4:

Pay in 4 is available on purchases from $30-$600
Pay in 4 is not currently available to residents of California, Georgia, Louisiana, New Mexico, North Dakota, Missouri, South Dakota, Wisconsin, or any U.S. Territories. Offer availability also depends on the merchant.
You must be of legal age in your state of residence to use Pay in 4.
The messaging renders based on the country of where the merchant account was created in (No dynamic geolocation lookup)
Pay in 4 is only available for US merchants. If it's a US merchant, then they will get the Pay Later messaging (either the Pay in 4 or the PayPal Credit messaging)
The Pay in 4 messaging is available for amounts between $30-$600 and the PayPal Credit messaging will be displayed for higher price points.
Once the buyer logs into their PayPal account during checkout, and if their PayPal account is based in one of the states that Pay in 4 is not eligible then they will not see this as an option to use to pay with

Miva 10.01.00 Updates

The following changes, bugfixes and improvements are part of Miva 10.01.00

Check Account Status Button

Prior to 10.01.00 Miva would make calls automatically when you viewed the PayPal Settings screen in the Miva admin. However, there were cases where this call was not being made which forced customers to have to remove the account and re-add it in order to see the updated account status. To fix this issue, we have removed the auto-call to PayPal and instead added a manual button. If your account is not initially approved for credit card processing, you can manually check periodically by clicking the "Update Status" button.

Support For Transaction Status of "Denied"

PayPal Commerce Platform has a Transaction Status for each transaction which is different from whether the payment was approved or declined. PayPal has a transaction status of "Denied" which we now will prevent an any order from being placed in Miva if the initial transaction status is "Denied." Note: This transaction status can change after the order has been created as well. In previous versions of the software we would allow orders with a transaction of Denied to be created. Here is a list of available transaction statuses, as well as reasons for a denied status can occur, which typically have to do with Fraud Rules.

Paypal Invoice ID Field is now sent with all Transactions

The invoice_id field (Miva's Order Number) is now sent with every transaction. Previous versions of our Express Checkout / PayPal Payments Pro modules did send this value. It becomes a searchable field in PayPal so that its easy to lookup orders in PayPal by the Miva Order ID. The important thing to note here is that PayPal does not allow duplicate values for this field by default. If you are planning to use PayPal's Credit Card Processing its is strongly recommended you adjust your PayPal account setting so that duplicate transactions are allowed. Without this setting enabled, only one payment per order will be allowed to be processed.

How to Allow Duplicate Invoice IDs

In PayPal go to Account Settings -> Payment Preferences -> Click Update for Block Payments -> Click No next to "Block Multiple Payments Per Invoice ID

Bug Fixes

Additional Basket Charges are now handeled correctly fixing the "AMOUNT_MISMATCH" error. This error occurs when a module add a custom charge to the basket. Example of Error:
Product Page Version of Smart Buttons clears existing basket even if you never complete checkout.
PayPal Commerce Platform: Field errors reference an incorrect tab
SKU field is not set for an Order Item when the Product Page version of PayPal Buttons are used

Miva 10.05.00 Updates

The following changes, bugfixes and improvements are part of Miva 10.05.00

Recalculation of Tax & Shipping Prior to Order Completion

Starting from 10.05.00 and above, when using PayPal Express Checkout, Miva will re-calculate Tax and Shipping on the order once Address Line 1 is known. For privacy reasons, PayPal does not send us Address line 1 until the payment has been approved by the customer (ie clicking complete order). In many cases calculating taxes (via a service like TaxJar of Avalara) will produce different tax amounts (could be higher or lower) when address line 1 is sent in the the request vs when it is not sent.

To ensure the order always has the most accurate tax amount and correct shipping method, once we get address line 1, we will make a call back to Miva to re-calculate taxes and shipping. This can result in the following 4 scenarios:

1. Taxes and shipping get re-calculated using address line 1 and nothing changes
2. Taxes get re-calculated using address line 1 and the taxes are higher or lower. The result of this is the order total (and amount charged) will automatically be updated and the new order total will be reflected on the invoice screen
3. Shipping get re-calculated using address line 1 and the shipping rates are higher or lower. The result of this is the order total (and amount charged) will automatically be updated and the new order total will be reflected on the invoice screen
4. There is some error updating the taxes or shipping on the order. For example, you could have a shipping rule preventing the shipping from being applied now that the address is known. In this case the customer is redirected back to OCST with an error to complete the checkout via the standard checkout process, which PayPal can still be used. (See example below)

By always re-calculating taxes and shipping once the Address Line 1 is known, it ensures that the tax on the order will always be accurate and match taxes calculated by another order processing system such as an ERP and the shipping method is still valid for the order.

Fallback to OCST on Error

In the event of an error finalizing an order when using PayPal Express Checkout, the customer is now redirected to OCST (Customer Bill To / Ship To) as part of the standard Miva checkout flow. They can then complete checkout and select PayPal as a payment method on the payment information page.

The following use cases may cause an error sending the customer back to OCST to complete checkout

1. The order is unable to be updated after Address Line 1 is known (see above). While in most cases this should just work, PayPal does have limits on how much the amount can change and it may be rejected based on jurisdiction.
2. Once Address Line 1 is known, the shipping method no longer applies to the order. For example, it is a PO Box and you don't ship to PO Boxes
3. Once Address Line 1 is known, Tax or Shipping Fail to re-calculate for any reason.

Bug Fix For Orders Missing Customer Information

The PayPal Commerce Platform integration has been updated to prevent missing customer address information on some orders when the order is created in Miva.

The following changes have been implemented to address this:

1. We no longer overwrite existing values with empty values - Since we get the address details in some API calls and not others, this will prevent empty values from overwriting a previously saved value.
2. Customer data sent in the payment_source object is now surfaced in the payment record in admin. This includes values such as Email, Name & Phone Number. This change is reto-active and old orders will now have this data show up since it was being saved previously just not displayed in admin.

PayPal Name, Phone Number and Email are now displayed in the Payment Record

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

Terms & Policies