Enabling & Disabling Payment Methods
PayPal Button Placement Best Practices
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.
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
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). 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
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.
Login using your PayPal account and grant Access for Miva to connect to your PayPal account.
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.
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.
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:
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.
PayPal now has a new transaction status field which gets returned in each payment response. There are 5 different statuses:
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.
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.
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 completeProduct 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.
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.
The product page version of the PayPal Checkout buttons will only purchase the product your viewing. It ignores any other items in the cart.
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)
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/
Here is a full list of possible values to disable different funding sources: https://developer.paypal.com/docs/checkout/reference/customize-sdk/#disable-funding
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.
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:
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:
The following changes, bugfixes and improvements are part of Miva 10.01.00
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.
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.
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
The following changes, bugfixes and improvements are part of Miva 10.05.00.
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 (i.e. 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 four scenarios:
By always re-calculating taxes and shipping once 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 that the shipping method is still valid for the order.
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:
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: