Ubuntu Wiki

Introduction

Part of the interaction in purchasing an item from an application or an application itself is confirming the purchase and choosing how it is paid for. At the simplest level this is saying "use my default credit card" to more complex interactions involving adding credit card or setting up accounts. To handle this part of the payment process, and to allow other payment providers besides Canonical, it is possible to install a helper that implements the payment interaction on an Ubuntu device.

Specifying a Pay UI Helper

For the system to recognize the Pay UI helper it needs to be a Click package that includes the "pay-ui" hook in its manifest. The file pointed to by the hook should be a FreeDesktop.org desktop file that gives information on how to run the helper. The "Exec" line should contain the name of an executable along with a "%u" to specify where the information on what is being purchased should be specified for the helper. When a helper is installed a click hook runs for pay-service that it detects the new helper and it gets registered internally so that on the next payment request the Pay UI Helper is run to service the user's request. The Exec key is the only required key in the desktop file.

Minimal Pay UI helper definition

[Desktop Entry]
Exec=pay-ui-helper %u

The desktop file may also contain a "Refund" action. If the user requests a refund, and the payment provider requires some amount of user interaction to process that refund, the Pay UI helper will be asked to display a refund view of the UI. If there is no refund action pay-service will assume that no user interaction is required for this payment provider and process the refund directly. A refund action should provide an Exec line with a different executable or the same executable with addition parameters appended to let it know which mode it is being used in. The Exec line should also include a "%u" where the item being refunded will be inserted.

Example with desktop actions

[Desktop Entry]
Exec=pay-ui-helper %u
Actions=Refund;

[Desktop Action Refund]
Exec=pay-ui-helper --refund %u

Item Information

When a Pay UI helper is started it is given a URL in the form:

purchase://$(package)/$(item)

For example:

purchase://com.ubuntu.developer.example/purchased-example

It is expected that the Pay UI helper will parse this URL and get both the package ID and the item ID to use when processing the purchase.

Before the Pay UI Helper is started the pay-service will get the item information from the server to ensure that there is up-to-date and correct information on the item being purchased. The Pay UI Helper can get information on the item being purchased by querying pay-service over DBus. Pay service provides a helper library, libpay-ui, which provides access to the item information to be used by the Pay UI Helper. For Pay UI helpers written in QML there are also QML widgets provided to display information about the item being purchased in a delightful way. It is recommended that those widgets be used if possible.

Lifecycle

The Pay UI helper is started when an application or scope requests a payment to be processed through the pay service. Pay service validates the request and ensures that the item is not already purchased. If a purchase needs to occur the pay service creates a Mir trusted prompt session and sets up a Mir socket for the Pay UI Helper, starting it with that connection as its MIR_SOCKET environment variable. The Pay UI Helper can then connect to Mir and request surfaces that will be placed over the application, appearing like it is part of the application. The Pay UI Helper should then go through the steps for payment, and exit when it has reached a terminal state; either purchased or the purchase being cancelled. Upon exiting the Pay Service will verify the transaction and respond back to the caller with the updated state of the item.

It is also possible that the Pay UI could be cancelled while executing resulting in the application being killed. This could happen for system issues, including lack of memory or other pressures. While it is unlikely, it is a case that Pay UI Helpers should take into account and ensure that they handle that situation.

FAQ

Q: Does my Pay UI helper have to be written in QML? A: No, but it is preferred. There are standard widgets that are provided for QML that handle interactions with the Pay Service that you'd otherwise need to support. All that is required is that you can use the Mir connection to get surfaces for drawing.

Q: Do I need to be able to talk to the Ubuntu Software Store? A: No, all client communication with the Software Store should be handled by the Pay Service. The server side components of your purchase service should communicate with the Ubuntu Software Store when they confirm the purchase.