PayPal Integration
Overview
PayPal subscription payments are supported by Monetization Service and Billing Service. Frontend integration with User Service, Billing Service, and PayPal is required.
Billing Service processes subscription transactions and automates billing through API and frontend integration. Billing Service exposes subscription details in a consistent way regardless of the payment provider used. This enables a seamless cross-device and cross-payment provider experience for the end-user.
PayPal Environments
PayPal has a live environment and a sandbox environment. The sandbox environment is used for testing integration without taking money from real accounts / credit cards. When configuring Mosaic development and testing environments, the PayPal sandbox should be used.
Live Environment
The PayPal developer dashboard is used to configure technical app integration. The developer dashboard can be accessed with a PayPal developer account or a business account. Developer accounts can be added through Account Settings accessed from the business dashboard. Developer centric work is done in this dashboard.
The PayPal business dashboard is used to configure, and to view live subscription & payment details. A PayPal business account is required.
Sandbox Environment
In the same developer dashboard where live applications are created, sandbox apps are created as well. Sandbox and live apps are configured side-by-side in the same UI.
The developer dashboard is also used to create sandbox PayPal accounts. Sandbox accounts come in two types: personal and business. Sandbox personal accounts are used to make payments in the sandbox. With a sandbox business account, you can access the PayPal sandbox business dashboard. This dashboard is almost identical to the PayPal business dashboard. It is used to configure and to view sandbox subscription & payment details. And it is used as the owner of the corresponding sandbox app.
|
Note
|
Logging into a sandbox account can be problematic if you are also logged in to PayPal with a non-sandbox account. It’s recommended to use different browser profiles, different browsers, or private mode to access sandbox accounts. |
As a good practice, it is advised to create a new PayPal sandbox business account for each integration. This allows creating PayPal products and plans in isolation without interfering with other tests and environments. This sandbox business account should be used to register the PayPal REST application. Personal sandbox accounts could be shared to purchase subscriptions for different apps and environments. But it makes testing easier if you use specific personal sandbox accounts also only for a single REST application.
Configuring Subscription Plans
Subscription plan and payment plan entities in Monetization Service correlate with PayPal product and plan subscription entities.
|
Important
|
Configuration of PayPal requires some manual steps and care must be taken to ensure that configurations are correctly reflected between Monetization Service and PayPal. Some settings in PayPal cannot be changed after they have been saved. Likewise, some settings in Monetization Service cannot be changed after they have been published. |
The advised configuration process is as follows:
-
Configure Monetization Service to cover your business case. Consider PayPal Limitations to ensure your configuration will be compatible with PayPal.
-
Configure PayPal Products and Plans to reflect the Monetization Service configuration.
By configuring Monetization Service first, available options are clearly displayed and easy to reason-about. Alternatively it is reasonable to start by configuring PayPal, but if you take this route, be sure to carefully consider the PayPal options which should be used.
Configure Monetization Service
For a guide to creating subscription plans with the Monetization Service see the Monetization User Guide.
PayPal Limitations
PayPal only supports a single currency and price per plan (not differentiated for different countries). In Monetization Service, multiple countries can be added to a payment plan where PayPal is enabled, but the currency and price must match for all countries. Each price or currency variation will require an additional payment plan. If a payment plan where PayPal is enabled does not meet this restriction, validation errors will prevent the subscription plan from being published.
Connect PayPal Products and Plans
Each PayPal product must be connected to a subscription plan configured in Monetization Service. The product ID field from PayPal must be stored on the subscription plan. If you have not created the PayPal product yet this can be left blank for now.
Likewise, each PayPal plan must be connected to a payment plan configured in Monetization Service. The plan ID field from PayPal must be stored on the payment plan. If you have not created the PayPal plan yet, leave this blank for now.
Configure PayPal Products and Plans
PayPal products and plans are configured in the PayPal business dashboard, or the PayPal sandbox business dashboard.
Click Create Plan to get started. You will be taken to a Product selection page, or to the product creation page if you have not already created one.
PayPal Product Options
Each PayPal product must be mapped to a subscription plan configured in the Monetization Service.
| PayPal product option | Mosaic compatibility |
|---|---|
Product name |
Should match subscription plan title |
Description |
Should match subscription plan description |
Product ID |
Must match subscription plan PayPal product ID |
Product type |
Depends on the subscription benefits. Suggested value: "Digital goods" |
Industry category |
Depends on the subscription benefits. Suggested value: "Digital media, books, movies, and music" |
Product page URL |
This should be a URL to a frontend where the subscription plan is described. |
Product image URL |
Optional |
PayPal Plan Options
Each PayPal plan must be mapped to a payment plan configured in Monetization Service.
When creating a plan, Fixed pricing must be selected. Other options are not compatible with Mosaic.
A plan ID for the plan is automatically generated on saving the plan.
| PayPal plan option | Mosaic compatibility |
|---|---|
Plan name |
Should match payment plan title NOTE: This property is used as payment description in end-user payment history. |
Plan description |
Should match payment plan description. |
Currency |
Must match the currency configured in Price per Country on the payment plan. NOTE: To be compatible with PayPal the currency must be the same for all countries. |
Charge a one-time setup fee? |
Should be unselected for Mosaic compatibility (setup fee to be implemented). |
Offer a trial period? |
Should be unselected. Currently the setup fee is not compatible with the Mosaic implementation. |
Subscription period: Unlimited billing cycles |
Default option. Fully compatible with Mosaic. |
Subscription period: Limited billing cycles |
This option is compatible with Mosaic billing. Subscriptions will cease to renew and will be made inactive at the end of the billing cycles. If this option is used it will not be reflected in the Mosaic payment plan details, therefore care must be taken to ensure end-users are correctly informed in the UI. |
Subscription period: Price |
Must match the price configured in Price per Country on the payment plan. NOTE: To be compatible with PayPal the price must be the same for all countries. |
Subscription period: (duration) |
Must match the Recurrence Period configured on the payment plan. |
Calculate tax for this subscription plan |
This can be selected, but for now it is not reflected in the billing transactions. |
How many missed billing cycles before a subscription is paused? |
Should be "1" for Mosaic compatibility. |
Turn on auto billing of outstanding payments |
Optional. If this is not enabled then subsequent payment attempts can be initiated manually by the merchant. |
PayPal Plan Status
Plan status should be aligned with Monetization Service. If a plan’s status is
OFF then new subscriptions cannot be made with the plan although existing
subscriptions will continue to be billed. This corresponds to a payment plan
being inactive in Monetization service. A subscription plan can also be set as
inactive in the Mosaic system but this has no representation on the PayPal side.
Saving a plan as Draft in PayPal enables all options to be edited. Once the
plan is turned on, some fields are locked for editing.
| PayPal plan status | Mosaic compatibility |
|---|---|
|
Payment plan status = |
|
Payment plan status = |
Finalize PayPal Provider Settings in Monetization Service
If you have not done so already, finalize Monetization Service configuration by copying the product ID value from each PayPal product to a subscription plan, and copying the plan ID value from each PayPal plan to a payment plan.
Validation before subscription plan publishing will ensure that all product ID and plan ID fields in Monetization Service are set.
|
Important
|
Ensure that relationships between subscription plans and payment plans in Monetization Service correspond with relationships between products and plans in PayPal. |
Validate and Publish Subscription Plans
Double check everything before publication as some fields cannot be edited after publication!
PayPal Technical Integration
The end-user device (e.g. web-browser) needs to communicate with the Mosaic User Service to acquire a JWT. And it needs to call the Billing Service to initialize and finalize the PayPal purchase flow. The actual payment process UI is provided by PayPal. The following diagram shows the flow of API calls and redirects to finish the subscription purchase. The details and the differences of the different calls and flows are described in more details further down. For now it is important that the end-user application integrates with the Billing Service and with the PayPal UI. The Billing Service is handling the PayPal integration by calling the PayPal API and accepting PayPal webhook messages.
Create a PayPal REST API Application
To integrate the PayPal subscription purchase process into your end-user application, you need to configure a PayPal REST API.
Open https://developer.paypal.com/developer/ and log in with your PayPal account that you used in the step Configure PayPal Products and Plans. This account must have the "Developer" permission.
Navigate to My Apps & Credentials to create a new REST API application (if you did not already create one). Applications can be created for the PayPal Sandbox environment or for the PayPal Live environment. Make sure to select the correct environment as this cannot be changed afterward. Click on "Create App" and give it a name. This name cannot be changed anymore (there is an additional "Display Name" but that one is used only in some places). For the sandbox you can define further settings: The App Type (which has to be "Merchant") and the Sandbox Business Account. That account must be the same one that you used when you created the PayPal sandbox product and plans when setting up the Monetization Service (Configure PayPal Products and Plans).
The sandbox and live applications differ slightly in their UI representation but offer the same data and configuration options.
In the "Credentials" section you can find the Client ID and the Secret that you will need to configure in the Mosaic Admin portal (see Configure the Mosaic Admin Portal).
Configure PayPal Application Settings
The application must have the following settings:
-
Accept payments. Make sure that you have in the "Advanced options" the options "Billing agreements" selected.
-
The Return URL should stay empty - this is managed with the Billing Service redirect logic.
-
All the other options are not required for the Billing Service. For security reasons, it is advised to not select more than the absolutely required permissions. So we recommend to uncheck them.
Configure PayPal Application Webhooks
The Billing Service must receive payment related notifications from PayPal. This
is done via webhooks where PayPal calls an API on the Billing Service to inform
about every subscription and payment event that occurred. You can find the URL
that you need to enter in your environment admin portal. For the EU region, it
is https://billing.service.eu.axinom.net/subscribe/paypal-webhook. Please
select the option "All Events". This does include events that PayPal may add in
the future. The Webhook ID you will need to configure in the Mosaic Admin
Portal.
Configure the Mosaic Admin Portal
Now that you created your PayPal REST application, you need to provide the above mentioned PayPal configuration settings via the Mosaic Admin Portal. All the PayPal API and the webhook events are specific to a single REST API application registered in the PayPal developer section. You get all the values below from within your specific application.
|
Important
|
Please be aware that those settings are crucial! If you change from sandbox to production, if you change to another REST API application: all currently running subscriptions will not get any updates (renewals, cancellations, …). So be sure to use the correct PayPal environment for your Mosaic environment. |
| Property | Type | Description | Example |
|---|---|---|---|
client_id |
String |
The client ID for the PayPal REST API application |
AQZ6ksZYshqRddoS3REuRFf8xB7bFnRN…. |
client_secret |
String |
The currently active client secret for the PayPal REST API application |
ELhPbjjF3p1e_tlu0kJdpwxhol-bp2X_M… |
is_sandbox |
Boolean |
Is the PayPal sandbox environment used or not. If you have a Mosaic developer environment you should likely use the sandbox, for a production instance most likely the production PayPal instance. |
true |
webhook_id |
String |
When a new event happens through PayPal (subscription created, payment finished, …) it calls the Billing Service API with this information. You need to create a webhook entry with a specific URL (you get it from the admin portal). PayPal creates a unique Webhook ID for this entry. This ID must be configured here. |
0SE8219540646192J |
The Mosaic Billing Service uses those values to authenticate against the PayPal API (client ID and client secret) and receive a token. With this token we can request subscription details from PayPal and register subscriptions for the redirect purchase flow.
You can configure those settings in the Mosaic Admin Portal for your environment. Go to the Service Configuration section and select the Payment Providers button. Add the PayPal payment provider via "new" or open it if it was already configured before.
PayPal Frontend Integration
Once the subscription plans and the PayPal application settings are configured, you can integrate PayPal subscription purchases into your end-user application. PayPal offers two purchase flows:
-
A purchase flow where the browser redirects the end-user to the PayPal website.
-
A pop-up based approach where the PayPal payment flow opens in a browser pop-up.
For both flows you need to call the Billing Service GraphQL API to pre-register a subscription in PayPal or to get required data to start the process. Please check the Billing Service Technical Specification on how to access this API.
You need to provide the end-user JWT from the Mosaic User Service in every request to the Billing Service GraphQL API as an HTTP header. Please check the corresponding User Service documentation on how to register and log in end-users and how to acquire this JWT.
PayPal Integration via Redirects
PayPal offers a redirect-based purchase flow. In this process, the end-user starts on your website and selects a payment plan to pay via PayPal. The end-user is then redirected in the browser to the PayPal website where he can follow the purchase flow. Once everything is fine, PayPal redirects the end-user to our Mosaic Billing Service. From there the end-user is then redirected back to the success (or error/cancel URL) that you configured in the Billing Service settings.
You can follow these steps to integrate the PayPal redirect purchase flow into your application:
First, you need to call the Billing Service GraphQL API to get a list of all
available subscription plans with their payment plans, prices, and the available
payment providers for each plan. This can be done via the subscriptionPlans
query.
You should filter to list only active subscription plans and payment plans and
show only the price of the desired country. The subscriptionPlans query with
the nested paymentPlans and their prices and available payment providers
(providerConfigs → paymentProvider) can be used.
You need to provide the end-user JWT token from the Mosaic User Service in every request to the Billing Service GraphQL API as an HTTP header. Please check the corresponding User Service documentation on how to register and log in end-users.
When the end-user selects an active payment plan that has PayPal as a payment
option you can call the paypalSubscribe mutation to start the purchase
process. Use the ID of the selected payment plan and for the purchase flow
select "REDIRECT". You can optionally provide an ISO 3166-1 alpha-2 country code
via the country parameter (e.g. US for the United States of America or DE
for Germany). The Billing Service will store this country code for the created
subscription and will validate, that a price is configured for the given
country.
This will prepare a pending subscription in the PayPal system and provide you
with an URL (approveUrl field) to which you should redirect the end-user. The
end-user will then follow the PayPal purchase flow and can either cancel it or
complete it. If there is any kind of error the end-user will stay on the PayPal
page. If he cannot resolve the issue (e.g. insufficient funds or similar) he can
cancel the purchase flow via a button/link on the PayPal page.
PayPal will redirect the end-user to the Billing Service API with some
parameters about the purchase process. The Billing Service will then verify with
the PayPal API if the purchase flow was a success or not (yet). Based on the
PayPal data the Billing Service will update the subscription in its system and
redirect the end-user to your configured success (or cancel) URL. In success
case the Billing Service appends a GET parameter to your URL that contains the
UUID of the created subscription as subscriptionId parameter:
Your application can now request information about the subscription and display
this information. You can use the subscription GraphQL query and provide the
subscription ID as the input parameter. If the subscription purchase succeeded,
but the redirect failed for some reason, the subscription is still activated.
PayPal sends all relevant subscription events as webhook messages to the Billing
Service. Please check the section PayPal Webhooks and Fallbacks for further
information.
PayPal Integration via Pop-ups
The second option that is offered by PayPal is to use the pop-up-based subscribe workflow. This process uses the PayPal JavaScript SDK to render a PayPal subscribe button on your application.
The initial process is the same as in the redirect scenario. You use the same
query (subscriptionPlans) as in the redirect process to get a list of all
available subscription plans with their payment plans, prices, and the available
payment providers for each plan.
Please follow the PayPal documentation in https://developer.paypal.com/docs/subscriptions/integrate/#link-createpaymentbutton on how to integrate a PayPal button into your application.
For every active payment plan that has PayPal as an option you can add a PayPal
button. The button has a callback function createSubscription. In this
function you have to call the Mosaic Billing Service GraphQL API mutation
paypalSubscribe. Use the ID of the selected payment plan and for the purchase
flow input field select "POPUP". From the response you need the paypalPlanId
and the customId. You can optionally provide an ISO 3166-1 alpha-2 country
code via the country parameter (e.g. US for the United States of America or
DE for Germany). The Billing Service will store this country code for the
created subscription and will validate, that a price is configured for the given
country.
When the (asynchronous/promise) call to the Billing Service finishes, return the
actions.subscription.create function with the parameters from the GraphQL
response:
return actions.subscription.create({
plan_id: result.data.paypalSubscribe.paypalPlanId,
custom_id: result.data.paypalSubscribe.customId,
});PayPal will now show a pop-up that is loaded from the PayPal website. The end-user can follow the process and complete the payment process.
Once the process is completed, the pop-up closes and the onApprove callback
function on the PayPal button is executed. You can then call the
paypalActivateSubscription mutation on the Billing Service GraphQL API to
activate the subscription. The data input object contains a property
data.subscriptionID which refers to the PayPal subscription in their system.
You should set this as the paypalSubscriptionId input parameter in the
paypalActivateSubscription mutation call. The Billing Service will then
internally call the PayPal API to verify if the subscription was successfully
activated and synchronize the PayPal data with the Billing Service system.
Afterward, it will return back the data that the client requested (e.g. the
subscription ID and the lifecycle status). You can then show the result to the
end-user.
PayPal Webhooks and Fallbacks
PayPal generates a number of events when a subscription is created, is canceled,
when a payment is completed, when a payment fails, etc. Based on those messages
the Billing Service will update the status and details of the subscriptions in
its system. This acts also as a fallback if there are any errors in the above
redirect or pop-up purchase scenarios. If the redirect to the billing API fails
for some reason or the GraphQL API call to paypalActivateSubscription fails,
the Billing Service will still receive this information from PayPal. Those
messages do not arrive in real-time but may take a few seconds or minutes until
they arrive and are handled.
In those scenarios, you can use the Billing Service GraphQL subscription
subscriptionLifecycleStatusMutated. A GraphQL subscription (not to be confused
with the Billing Service subscription entity) creates a websocket-based
connection where the Billing Service can send live updates. For this endpoint,
it sends live updates when the status of a subscription from the end-user
changes.
This can be used as a fallback mechanism to get notified in real-time when a subscription is activated.
Whenever the status of a subscription from the end-user changes, the
subscriptionLifecycleStatusMutated event is triggered. It sends the ID of the
subscription as "id" along with the user ID, the old lifecycle status, and the
new one. You can use this data to update the subscription status in your
application.