Instant Purchase module
The Instant Purchase module allows customers to place orders in seconds without going through the full checkout process.
This feature takes the form of a button on product pages. When a customer clicks this button, the system places their order using the default shipping, billing address, and stored payment method. Once the order is placed, an order confirmation message appears in the notification area.
This article explains how this module works and ways to customize it using its extension points. For merchant instructions, see Instant Purchase in the user guide.
The logic found in the Instant Purchase module is divided into two parts:
Instant Purchase logic
This module allows any product to be added to an instant purchase order.
The module creates an additional section in the Customer Data cache for Instant Purchase data. This data is updated when the relevant customer data changes, such as adding or removing a stored payment method or the default shipping address.
The implementation for this interface defines Instant Purchase calculations. The default implementation uses several interfaces to choose the appropriate payment method, billing and shipping addresses, and shipping method.
Responsible for choosing the stored payment method. The default value is the last created and saved payment method used.
Instant Purchase will not use payment methods that were used but not saved.
Responsible for choosing the shipping address. The default implementation chooses the default shipping address set by the customer.
Responsible for choosing the billing address. The default implementation chooses the default billing address set by the customer.
Responsible for choosing the shipping method. The default implementation chooses the cheapest shipping method.
Since the final price of the shipment is calculated after product and quantity are specified in the final confirmation, “Cheapest price” is displayed in the confirmation pop-up for the customer.
The Instant Purchase capability logic is the most customizable part of the module. For more customization details, see the Customization Points section.
The logic for the order placement process is found in the
The whole process is divided into several steps with each step implemented by a corresponding class in the
Since order placement requires specific steps to be followed, this part of the module does not declare separate interfaces. To customize the behavior of the order placement process, use plugins.
Use dependency injection to override preferences for interfaces marked with the
@api notation and modify the behavior of the module.
Instant Purchase calculation
InstantPurchaseOption object is a data container that holds the stored payment method, shipping and billing addresses, and shipping method used by the Instant Purchase module.
The logic of how this data is retrieved is the responsibility of the
To create an
InstantPurchaseOption object from the gathered data, use the
The customization points for stored payment, shipping address, billing address, and shipping method are used in the default
InstantPurchaseInterface implementation (
They become invalid if a different implementation is used.
choose() method for custom implementations of the following interfaces must return an instance of the correct class or
null if nothing can be chosen.
|Customization Point||Interface||Return Class|
Deferred Shipping Method
Choosing the shipping method based on a customer’s address is difficult without all the information on the shipping subject because it is hard to estimate the cost and effort. To address this issue, the Instant Purchase module allows you to postpone the final decision on which shipping method to use until the exact product and quantity is known.
Use the following steps to help you implement a custom deferred shipping method:
- Create an implementation of the
choose()method that returns a
ShippingMethodInterfacewith the following properties:
- Returns a unique string when
This string is used as a key to determine the corresponding logic during order placement.
- Returns a translated phrase when
This phrase is shown as the shipping method description in the Instant Purchase confirmation pop-up.
Create an implementation of the
DeferredShippingMethodChooserInterface. Unlike the
ShippingMethodChooserInterface, this interface retrieves the
Quote\Addressinstead of the customer’s address, so it has access to the necessary data.
This method must return a string that identifies the shipping method using the format
<carrier code>_<method code>or
nullif nothing can be chosen.
- Add an entry in the
di.xmlfile that specifies your defined method code and custom implementation:
1 2 3 4 5 6 7 8 9 <type name="Magento\InstantPurchase\Model\ShippingMethodChoose\DeferredShippingMethodChooserPool"> <arguments> <argument name="choosers" xsi:type="array"> <!-- item name attribute is method code defined in ShippingMethodChooserInterface implementation--> <!-- item value is class name of DeferredShippingMethodChooserInterface implementation--> <item name="cheapest" xsi:type="object">Magento\InstantPurchase\Model\ShippingMethodChoose\CheapestMethodDeferredChooser</item> </argument> </arguments> </type>
You can customize order placement using plugins.
Before and after plugins can be created to add custom behaviors in the
PlaceOrder class and any class in the
Customizing payment handling is a special case for the order placement process. See Payment Method Integration for more details.
You can customize the strings on the Instant Purchase confirmation pop-up by using plugins on classes in the
The format of the payment method can also be customized for specific payments.
Payment method integration
A payment method implementation can be integrated with Instant Purchase if it meets the following requirements:
- It implements the payment provider gateway mechanism.
- It implements vault integration.
- The payment along with the stored payment token is processed on the server side
The framework for payment method integration is provided in the
Integration is not enabled by default and requires developer action to make sure everything works as expected and avoid unpredictable bugs on production sites.
If the payment method meets all the requirements listed, you can enable Instant Purchase integration in the
The minimal configuration for Instant Purchase integration development is as follows:
1 2 3 4 5 6 7 8 9 10 11 <config> <default> <payment> <vault_payment_method_code><!-- replace this value with your vault payment method code --> <instant_purchase> <supported>1</supported> </instant_purchase> </vault_payment_method_code> </payment> <default> </config>
This minimal configuration is to help you get started with Instant Purchase integration development and is not recommended for production sites.
The following is an example of a full configuration meant for production:
1 2 3 4 5 6 7 8 9 10 11 12 13 <config> <default> <payment> <vault_payment_method_code><!-- replace this value with your vault payment method code --> <instant_purchase> <available>Implementation_Of_Magento\InstantPurchase\PaymentMethodIntegration\AvailabilityCheckerInterface</available> <tokenFormat>Implementation_Of_Magento\InstantPurchase\PaymentMethodIntegration\PaymentTokenFormatterInterface</tokenFormat> <additionalInformation>Implementation_Of_Magento\InstantPurchase\PaymentMethodIntegration\PaymentAdditionalInformationProviderInterface</additionalInformation> </instant_purchase> </vault_payment_method_code> </payment> <default> </config>
All elements of the integration configuration are optional and have default implementations.
If some integration options are provided, then explicit usage of
<supported>1</supported> is not required.
<supported>0</supported> will disable integration regardless of all other settings.
Integration availability checker
The integration availability checker allows you to specify if your payment integration is available based on the current Magento configuration specification or other data. For example, Magento Open Source provides Braintree Stored Credit Cards which supports Instant Purchase unless 3D Secure is enabled.
The default implementation for the availability checker always returns
Custom availability checkers need to implement the
AvailabilityCheckerInterface and can be applied to a payment method by specifying the class name (or virtual type name) in the
default/payment/<vault payment method code>/instant_purchase/available configuration option.
Payment Token Formatter
The Magento Vault module provides an interface to persist and manage stored payment methods.
The properties defined in the interface is necessary to use the payment method.
Almost all the information used to provide the description for stored payment methods are stored as additional data and are not standardized. This is why the default token formatter returns the payment method title as the token description.
We recommend you provide a custom token formatter for your Instant Purchase integration to provide the correct information for your payment token
The Instant Purchase module guarantees that the correct token associated with corresponding payment method is passed to the formatter.
To configure the formatter, use the
default/payment/<vault payment method code>/instant_purchase/tokenFormat configuration path.
Additional Payment Information Provider
Some payment methods require the collection of additional information during the checkout process for order placement.
By default, the Instant Purchase module specifies the following properties as additional payment information:
||Holds the Customer identifier|
||The public hash for the stored payment method|
||Required by Vault framework|
To change the default behavior or add specific fields, implement the
PaymentAdditionalInformationProviderInterface and specify it as the value for the
default/payment/<vault payment method code>/instant_purchase/additionalInformation configuration option.
The default implementation returns an empty array.
Instant Purchase Payment Marker
In most cases, developers should use interfaces for custom implementations and not rely on internal code.
However, sometimes conditional logic for payment processing needs to be implemented to handle payments initiated from different entry points.
For these cases, the payment object’s
InfoInterface holds an
additional_information property, accessible via the
getAdditionalInformation() method, which can return the
Use this marker if no other options are available to implement specific payment logic for the Instant Purchase module.