From 249913386b4b64ffdc8c2e03b1d18ff2a5ddd728 Mon Sep 17 00:00:00 2001 From: liudmyla Date: Tue, 16 Jul 2024 10:20:47 +0200 Subject: [PATCH 01/11] 36803 - added some documentation for installation and workflow collection --- README.md | 2 +- ...ercetools-workflow.postman_collection.json | 0 docs/usecases/README.MD | 89 +++++++++++++++++++ 3 files changed, 90 insertions(+), 1 deletion(-) rename docs/{ => usecases}/PayPal-commercetools-workflow.postman_collection.json (100%) create mode 100644 docs/usecases/README.MD diff --git a/README.md b/README.md index d18772e..dee8573 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This is a [connect application](https://marketplace.commercetools.com/) to integ [PayPal commercetools connector](https://marketplace.commercetools.com/integration/paypal) is available in the commercetools marketplace. -The connector must be used together with [PayPal client api](https://www.npmjs.com/package/paypal-commercetools-client) for the frontend integration. +The connector is designed be used together with [PayPal client api](https://www.npmjs.com/package/paypal-commercetools-client) for the frontend integration. If it is not possible for some reason you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. The payments demo and integration to the commercetools frontend can be seen at https://poc-mediaopt2.frontend.site/ and [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). diff --git a/docs/PayPal-commercetools-workflow.postman_collection.json b/docs/usecases/PayPal-commercetools-workflow.postman_collection.json similarity index 100% rename from docs/PayPal-commercetools-workflow.postman_collection.json rename to docs/usecases/PayPal-commercetools-workflow.postman_collection.json diff --git a/docs/usecases/README.MD b/docs/usecases/README.MD new file mode 100644 index 0000000..a04cc41 --- /dev/null +++ b/docs/usecases/README.MD @@ -0,0 +1,89 @@ +

+ + commercetools logo +
+ + PayPal logo +
+

+ +In this folder you can find the use cases for the PayPal commercetools connector. Here we summarize the actual workflow and the expected results. The simplified workflow that only includes backend calls through postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). + +# Use Cases + +## Installation + +The connector itself is the backend part of the payment process, it is designed to be used together with the [PayPal client api](https://www.npmjs.com/package/paypal-commercetools-client) for the frontend integration. If it is not possible for some reason you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. We also use commercetools frontend (further referred as CoFe), but it is an optional part, shown here for illustration how to develop necessary API for the PayPal client. + +### Connector installation + +There are two possible ways to integrate the connector, both fully covered in the mentioned documentation. + +1. Installed [directly from the commercetools marketplace](https://docs.commercetools.com/merchant-center/connect). +2. Create your own deployment using [commercetools connect API](https://docs.commercetools.com/connect/getting-started). + +The connector includes a merchant center application, which is automatically installed and deployed when installing the connector, but it might be needed to update the custom application link after the deployment, as described in [commercetools documentation](https://docs.commercetools.com/merchant-center-customizations/deployment-examples/commercetools-connect). + +### Frontend installation +The client can be directly installed to the shop frontend using npm: + +```npm i paypal-commercetools-client``` + +and then the components imported directly from the package, see for example the [payment form in CoFe integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). + +## Payment Process + +To start the payment process with the connector the preliminary prepared commercetools cart and payment is required. In our case we have used the CoFe frontend to create the cart and the payment, but the example process through the [commercetools HTTP API](https://docs.commercetools.com/api/) is also provided in Postman collection and can be separated to following steps: + +### Backend only flow +The backend flow that we provide as a collection can be separated to three parts: +1. creating the cart and payment via standard commercetools HTTP api, which we provide only to get reliable example of the cart for all payments, +2. PayPal specific part, which includes setting the custom type for payment and obtaining the client token. +3. PayPal payment method specific part, that can differ for different payment methods + +The first two categories are covered in the Postman collection Initial part, the third is provided separately for some methods in the corresponding subfolder of the Payment specific folder. To go through the whole payment process of a target method you need to follow first all the calls in initial folder in a Postman collection and then all the specific for this method. All the necessary data are already provided in the collection, so you can just run the requests and see the results. + +### Initial flow +| Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | +| 1 | If not yet - [obtain commercetools access token](https://docs.commercetools.com/api/authorization). | getAccessToken | +| 2 | [Create a cart](https://docs.commercetools.com/api/projects/carts) with some products in it. Products can be added during creation or added separately | Search for a product -> Create Cart -> AddLineItem | +| 3 | [Create a payment](https://docs.commercetools.com/api/projects/payments) with the `paypal-payment-type`. | SetCustomType For Payment | +| 4 | Link the payment to the cart | AddPayment | +| 5 | If not yet - get client token for communication with PayPal | getClientToken | + +#### Payment method specific flow + +MOST OF THE METHODS REQUIRES USER APPROVAL AFTER CREATE PAYPAL ORDER. IT MEANS THAT THE USER SHOULD APPROVE THE ORDER VIA THE LINK, PROVIDED IN THE RESPONSE. +In case if this is applicable for a certain method - it is mentioned in the method description. For sandbox testing sanbdox customer credentials or [sandbox testing cards provided in the PayPal documentation](https://developer.paypal.com/tools/sandbox/card-testing/) can be used to approve the order. + +##### Pay Upon Invoice +Pay Upon invoice is the simplest as the payment is not processed immediately. + +| Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | +|------|------------------------------------------------|--------------------------------------------------------------------------------------| +| 1 | Create an order with Invoice as payment source | createPayPalOrder | + +##### PayPal +| Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | +|------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| 1 | Create an order with PayPal as payment source | createPayPalOrder | +| 2 | In your browser open the link with the "rel" approve in create order response and approve the order | - | +| 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | +| 4 | Capture the order | CaptureOrder | + +##### Card payment + +| Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | +|------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| 1 | Create an order with card as payment source | createPayPalOrder | +| 2 | In your browser open the link with the "rel" approve in create order response and approve the order | - | +| 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | +| 4 | Capture the order | CaptureOrder | + +### Frontend flow +In case of frontend flow the PayPal client components are imported at CoFe frontend and the API required for proper communication between the components and commercetools HTTP API is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). The cart is created by CoFe and is out of scope of this documentation. To create the cart via only HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). + +Here we will describe the [checkout payment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) starting from the point where connector is involved at the backend. + +First the getSettings is called to obtain the information like which methods should actually be shown. For all available settings please see the paypal-payment-panel provided by custom application in the merchant center. From e26e6614840336d37aa8074e374ce825fc477f9a Mon Sep 17 00:00:00 2001 From: liudmyla Date: Tue, 16 Jul 2024 13:15:34 +0200 Subject: [PATCH 02/11] 36803 - minor readme edits --- docs/usecases/README.MD | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/usecases/README.MD b/docs/usecases/README.MD index a04cc41..4c1ca47 100644 --- a/docs/usecases/README.MD +++ b/docs/usecases/README.MD @@ -52,19 +52,19 @@ The first two categories are covered in the Postman collection Initial part, the | 4 | Link the payment to the cart | AddPayment | | 5 | If not yet - get client token for communication with PayPal | getClientToken | -#### Payment method specific flow +### Payment method specific flow MOST OF THE METHODS REQUIRES USER APPROVAL AFTER CREATE PAYPAL ORDER. IT MEANS THAT THE USER SHOULD APPROVE THE ORDER VIA THE LINK, PROVIDED IN THE RESPONSE. In case if this is applicable for a certain method - it is mentioned in the method description. For sandbox testing sanbdox customer credentials or [sandbox testing cards provided in the PayPal documentation](https://developer.paypal.com/tools/sandbox/card-testing/) can be used to approve the order. -##### Pay Upon Invoice +#### Pay Upon Invoice Pay Upon invoice is the simplest as the payment is not processed immediately. | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | |------|------------------------------------------------|--------------------------------------------------------------------------------------| | 1 | Create an order with Invoice as payment source | createPayPalOrder | -##### PayPal +#### PayPal | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | |------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | 1 | Create an order with PayPal as payment source | createPayPalOrder | @@ -72,7 +72,7 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | | 4 | Capture the order | CaptureOrder | -##### Card payment +#### Card payment | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | |------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| From 379e6aa42b90765d5e807637fa686de26d4acd53 Mon Sep 17 00:00:00 2001 From: liudmyla Date: Tue, 16 Jul 2024 15:22:46 +0200 Subject: [PATCH 03/11] 36803 - described first part of frontend flow --- docs/usecases/README.MD | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/usecases/README.MD b/docs/usecases/README.MD index 4c1ca47..439db66 100644 --- a/docs/usecases/README.MD +++ b/docs/usecases/README.MD @@ -25,9 +25,10 @@ There are two possible ways to integrate the connector, both fully covered in th The connector includes a merchant center application, which is automatically installed and deployed when installing the connector, but it might be needed to update the custom application link after the deployment, as described in [commercetools documentation](https://docs.commercetools.com/merchant-center-customizations/deployment-examples/commercetools-connect). ### Frontend installation + The client can be directly installed to the shop frontend using npm: -```npm i paypal-commercetools-client``` +`npm i paypal-commercetools-client` and then the components imported directly from the package, see for example the [payment form in CoFe integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). @@ -36,7 +37,9 @@ and then the components imported directly from the package, see for example the To start the payment process with the connector the preliminary prepared commercetools cart and payment is required. In our case we have used the CoFe frontend to create the cart and the payment, but the example process through the [commercetools HTTP API](https://docs.commercetools.com/api/) is also provided in Postman collection and can be separated to following steps: ### Backend only flow + The backend flow that we provide as a collection can be separated to three parts: + 1. creating the cart and payment via standard commercetools HTTP api, which we provide only to get reliable example of the cart for all payments, 2. PayPal specific part, which includes setting the custom type for payment and obtaining the client token. 3. PayPal payment method specific part, that can differ for different payment methods @@ -44,6 +47,7 @@ The backend flow that we provide as a collection can be separated to three parts The first two categories are covered in the Postman collection Initial part, the third is provided separately for some methods in the corresponding subfolder of the Payment specific folder. To go through the whole payment process of a target method you need to follow first all the calls in initial folder in a Postman collection and then all the specific for this method. All the necessary data are already provided in the collection, so you can just run the requests and see the results. ### Initial flow + | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | 1 | If not yet - [obtain commercetools access token](https://docs.commercetools.com/api/authorization). | getAccessToken | @@ -58,15 +62,17 @@ MOST OF THE METHODS REQUIRES USER APPROVAL AFTER CREATE PAYPAL ORDER. IT MEANS T In case if this is applicable for a certain method - it is mentioned in the method description. For sandbox testing sanbdox customer credentials or [sandbox testing cards provided in the PayPal documentation](https://developer.paypal.com/tools/sandbox/card-testing/) can be used to approve the order. #### Pay Upon Invoice + Pay Upon invoice is the simplest as the payment is not processed immediately. | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -|------|------------------------------------------------|--------------------------------------------------------------------------------------| +| ---- | ---------------------------------------------- | ------------------------------------------------------------------------------------ | | 1 | Create an order with Invoice as payment source | createPayPalOrder | -#### PayPal +#### PayPal + | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -|------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| ---- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | 1 | Create an order with PayPal as payment source | createPayPalOrder | | 2 | In your browser open the link with the "rel" approve in create order response and approve the order | - | | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | @@ -75,15 +81,31 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. #### Card payment | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -|------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| ---- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | 1 | Create an order with card as payment source | createPayPalOrder | | 2 | In your browser open the link with the "rel" approve in create order response and approve the order | - | | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | | 4 | Capture the order | CaptureOrder | ### Frontend flow + In case of frontend flow the PayPal client components are imported at CoFe frontend and the API required for proper communication between the components and commercetools HTTP API is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). The cart is created by CoFe and is out of scope of this documentation. To create the cart via only HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). -Here we will describe the [checkout payment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) starting from the point where connector is involved at the backend. +Here we will describe the [checkout payment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). + +| Step | performed at | description | +|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1 | CoFe frontend [formPayment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) | all necessary payment methods are imported from the package:
`import { PayPal, PayUponInvoice, CardFields, ApplePay, GooglePay } from 'paypal-commercetools-client/dist/esm';` | +| 2 | CoFe frontend [actions](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/frontastic/actions/paypal/index.ts) | the getSettings is called. It actually uses [commercetools frontend api action](https://docs.commercetools.com/frontend-api/action) and addresses CoFe backend | +| 3 | CoFe backend [SettingsController](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/SettingController.ts) | commercetools HTTP API is used to obtain PayPal settings (see also the [PayPal Postman collection](https://github.com/mediaopt/paypal-commercetools-connector/blob/main/docs/paypal.postman_collection.json) getSettings call). | +| 4 | CoFe frontend [formPayment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) | PayPal payment methods parameters ([described later](#Payment-methods-parameters)) are obtained as result of previous steps, including such things as allowed payment methods and configuration of the payment buttons. | +| 5 | CoFe frontend [formPayment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) | the cart is obtained using built-in CoFe methods | +| 6 | CoFe frontend [paypalCheckoutData](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/payPalCheckoutData.tsx) | in this helper file payment methods parameters are calculated based on the previously obtained settings and cart | +| 7 | CoFe frontend [formPayment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) | relevant payment methods with corresponding settings are rendered | + +the further steps are triggered by the user actions, like pressing the payment button. + +#### Payment methods parameters +| Parameter | Description| +|-----------|---| -First the getSettings is called to obtain the information like which methods should actually be shown. For all available settings please see the paypal-payment-panel provided by custom application in the merchant center. From 8b883842a7d30a0431c0ab55847de559b925bff6 Mon Sep 17 00:00:00 2001 From: liudmyla Date: Wed, 17 Jul 2024 12:58:58 +0200 Subject: [PATCH 04/11] 36803 - finished description of frontend side processes --- docs/PayPal.md | 6 +-- docs/usecases/README.MD | 90 +++++++++++++++++++++++++++++++++-------- 2 files changed, 76 insertions(+), 20 deletions(-) diff --git a/docs/PayPal.md b/docs/PayPal.md index cb924e9..575ca1a 100644 --- a/docs/PayPal.md +++ b/docs/PayPal.md @@ -32,9 +32,9 @@ Please see [http://docs.commercetools.com/](http://docs.commercetools.com/) for * [Authorization](#authorization) 1. [Obtain access token](#1-obtain-access-token) - 1. [Obtain access token through password flow](#2-obtain-access-token-through-password-flow) - 1. [Token for Anonymous Sessions](#3-token-for-anonymous-sessions) - 1. [Token Introspection](#4-token-introspection) + 2. [Obtain access token through password flow](#2-obtain-access-token-through-password-flow) + 3. [Token for Anonymous Sessions](#3-token-for-anonymous-sessions) + 4. [Token Introspection](#4-token-introspection) * [PayPal](#paypal) 1. [CreateOrder](#1-createorder) * [PayUponInvoice](#i-example-request-payuponinvoice) diff --git a/docs/usecases/README.MD b/docs/usecases/README.MD index 439db66..55e6670 100644 --- a/docs/usecases/README.MD +++ b/docs/usecases/README.MD @@ -9,13 +9,31 @@ In this folder you can find the use cases for the PayPal commercetools connector. Here we summarize the actual workflow and the expected results. The simplified workflow that only includes backend calls through postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). -# Use Cases - -## Installation +# Table of Contents + +- [Installation](#installation) + - [Connector installation](#connector-installation) + - [Frontend installation](#frontend-installation) +- [Payment Process](#payment-process) + - [Backend only flow](#backend-only-flow) + - [Initial flow](#initial-flow) + - [Payment method specific flow](#payment-method-specific-flow) + - [Pay Upon Invoice](#pay-upon-invoice) + - [PayPal](#paypal) + - [Card payment](#card-payment) + - [Standard flow](#standard-flow) + - [Rendering payment buttons](#rendering-payment-buttons) + - [Payment methods parameters](#payment-methods-parameters) + - [Payment method dependent flow](#payment-method-dependent-flow) + - [PayPal](#paypal-1) + - [Card](#card) + - [Pay Upon Invoice](#pay-upon-invoice-1) + +# Installation The connector itself is the backend part of the payment process, it is designed to be used together with the [PayPal client api](https://www.npmjs.com/package/paypal-commercetools-client) for the frontend integration. If it is not possible for some reason you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. We also use commercetools frontend (further referred as CoFe), but it is an optional part, shown here for illustration how to develop necessary API for the PayPal client. -### Connector installation +## Connector installation There are two possible ways to integrate the connector, both fully covered in the mentioned documentation. @@ -24,7 +42,7 @@ There are two possible ways to integrate the connector, both fully covered in th The connector includes a merchant center application, which is automatically installed and deployed when installing the connector, but it might be needed to update the custom application link after the deployment, as described in [commercetools documentation](https://docs.commercetools.com/merchant-center-customizations/deployment-examples/commercetools-connect). -### Frontend installation +## Frontend installation The client can be directly installed to the shop frontend using npm: @@ -32,11 +50,11 @@ The client can be directly installed to the shop frontend using npm: and then the components imported directly from the package, see for example the [payment form in CoFe integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). -## Payment Process +# Payment Process To start the payment process with the connector the preliminary prepared commercetools cart and payment is required. In our case we have used the CoFe frontend to create the cart and the payment, but the example process through the [commercetools HTTP API](https://docs.commercetools.com/api/) is also provided in Postman collection and can be separated to following steps: -### Backend only flow +## Backend only flow The backend flow that we provide as a collection can be separated to three parts: @@ -46,7 +64,7 @@ The backend flow that we provide as a collection can be separated to three parts The first two categories are covered in the Postman collection Initial part, the third is provided separately for some methods in the corresponding subfolder of the Payment specific folder. To go through the whole payment process of a target method you need to follow first all the calls in initial folder in a Postman collection and then all the specific for this method. All the necessary data are already provided in the collection, so you can just run the requests and see the results. -### Initial flow +## Initial flow | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | @@ -56,12 +74,12 @@ The first two categories are covered in the Postman collection Initial part, the | 4 | Link the payment to the cart | AddPayment | | 5 | If not yet - get client token for communication with PayPal | getClientToken | -### Payment method specific flow +## Payment method specific flow MOST OF THE METHODS REQUIRES USER APPROVAL AFTER CREATE PAYPAL ORDER. IT MEANS THAT THE USER SHOULD APPROVE THE ORDER VIA THE LINK, PROVIDED IN THE RESPONSE. In case if this is applicable for a certain method - it is mentioned in the method description. For sandbox testing sanbdox customer credentials or [sandbox testing cards provided in the PayPal documentation](https://developer.paypal.com/tools/sandbox/card-testing/) can be used to approve the order. -#### Pay Upon Invoice +### Pay Upon Invoice Pay Upon invoice is the simplest as the payment is not processed immediately. @@ -69,7 +87,7 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. | ---- | ---------------------------------------------- | ------------------------------------------------------------------------------------ | | 1 | Create an order with Invoice as payment source | createPayPalOrder | -#### PayPal +### PayPal | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | | ---- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | @@ -78,7 +96,7 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | | 4 | Capture the order | CaptureOrder | -#### Card payment +### Card payment | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | | ---- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | @@ -87,14 +105,16 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | | 4 | Capture the order | CaptureOrder | -### Frontend flow +## Standard flow In case of frontend flow the PayPal client components are imported at CoFe frontend and the API required for proper communication between the components and commercetools HTTP API is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). The cart is created by CoFe and is out of scope of this documentation. To create the cart via only HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). Here we will describe the [checkout payment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). +### Rendering payment buttons + | Step | performed at | description | -|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | CoFe frontend [formPayment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) | all necessary payment methods are imported from the package:
`import { PayPal, PayUponInvoice, CardFields, ApplePay, GooglePay } from 'paypal-commercetools-client/dist/esm';` | | 2 | CoFe frontend [actions](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/frontastic/actions/paypal/index.ts) | the getSettings is called. It actually uses [commercetools frontend api action](https://docs.commercetools.com/frontend-api/action) and addresses CoFe backend | | 3 | CoFe backend [SettingsController](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/SettingController.ts) | commercetools HTTP API is used to obtain PayPal settings (see also the [PayPal Postman collection](https://github.com/mediaopt/paypal-commercetools-connector/blob/main/docs/paypal.postman_collection.json) getSettings call). | @@ -105,7 +125,43 @@ Here we will describe the [checkout payment](https://github.com/mediaopt/paypal- the further steps are triggered by the user actions, like pressing the payment button. -#### Payment methods parameters -| Parameter | Description| -|-----------|---| +### Payment methods parameters + +For the parameters please see also the [PayPal client documentation](https://github.com/mediaopt/paypal-commercetools-client/blob/main/docs/CoFe-PayPal-client-integration.pdf). Here we will only describe the API parameters required for the demonstrated payment methods. In our implementation all mentioned urls trigger corresponding methods at the [PayPal controller CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/PayPalController.ts). Please follow the link for the code, here we only briefly mention the principle. + +| Parameter | Required for functioning | Description | +| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| createPaymentUrl | all components | triggers createPayment. Within this method cart is fetched to check if a relevant PayPal payment already exists, if not the new PayPal type payment is created, returns [CreatePaymentResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | | +| getClientTokenUrl | except PayPal payment buttons | triggers getClientToken. Within this method the client token is obtained from the PayPal side and returned. | | +| createPayPalOrder | all payments | triggers createPayPalOrder. Within this methods cart is fetched to obtain payment details and line items, than payment [custom fields](https://docs.commercetools.com/api/projects/custom-fields) are updated to trigger the connector (see also createPayPalOrder in Postman collection). [CreateOrderResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) is returned. | | +| onApproveUrl | all payments except Pay Upon Invoice | triggers capturePayPalOrder. Within this method if not provided in a call a relevant order id is obtained from card payment information and connector capturePayPalOrder is triggered (also by payment custom fields). Returns [OnApproveResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | | +| authenticateThreeDSOrderUrl | payments with 3D secure | triggers authenticateThreeDSOrder. Within this method the request is parsed to identify if the 3D secure passed successfully. Returns returns an object with the liability_shift, enrollment_status, and authentication_status. | | + +### Payment method dependent flow + +In most of the payment cases the first three steps are the same: + +1. On rendering the button the createPaymentUrl is called to obtain/generate the relevant payment id. +2. If relevant getClientToken is called to obtain the client token at the PayPal side. +3. The button is than rendered by the client via PayPal JS SDK. + +#### Pay Upon Invoice + +1. After user completes the additional data required only for Pay Upon Invoice payment and confirms, the createPayPalOrder is triggered +2. as Pay Upon Invoice does not require immediate payment - we trigger a custom checkout process for pay upon invoice + after the user completes invoice payment on the RatePay side the webhook at the connector side is triggered to capture the order. + +#### PayPal buy now + +1. On click on the target button createPayPalOrderUrl is called +2. if createPayPalOrder call was successfully - the floating window with PayPal login or payment form is opened and the payment can proceed. +3. the user completes the payment on PayPal side and on success onApproveUrl is addressed and capturePayPalOrder is triggered +4. after successfully capture, we trigger the standard checkout process on the frontend side + +#### Card +1. After user completes the card data and confirms, the createPayPalOrder is triggered +2. if 3D secure is required - the floating window with 3D secure form is opened and user needs to confirm the payment +3. if 3D secure is required - authenticateThreeDSOrderUrl is called to authenticate the payment +4. if 3D secure is successful or not required - onApproveUrl is addressed and capturePayPalOrder is triggered +5. after successfully capture, we trigger the standard checkout process on the frontend side From 0aa8b74bbd060099b87ac5091ac0ba9d6db13e1b Mon Sep 17 00:00:00 2001 From: liudmyla Date: Wed, 17 Jul 2024 13:04:52 +0200 Subject: [PATCH 05/11] 36803 - minor format fixes --- docs/PayPal.md | 42 ++++++++++++++++++++--------------------- docs/usecases/README.MD | 14 +++++++------- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/PayPal.md b/docs/PayPal.md index 575ca1a..c33911a 100644 --- a/docs/PayPal.md +++ b/docs/PayPal.md @@ -43,27 +43,27 @@ Please see [http://docs.commercetools.com/](http://docs.commercetools.com/) for * [Card](#iv-example-request-card) * [Google Pay](#v-example-request-google-pay) * [Apple Pay](#vi-example-request-apple-pay) - 1. [getClientToken](#2-getclienttoken) - 1. [CaptureOrder](#3-captureorder) - 1. [CaptureAuthorization](#4-captureauthorization) - 1. [AuthorizeOrder](#5-authorizeorder) - 1. [GetOrder](#6-getorder) - 1. [GetCapture](#7-getcapture) - 1. [createTrackingInformation](#8-createtrackinginformation) - 1. [updateTrackingInformation](#9-updatetrackinginformation) - 1. [UpdateOrder](#10-updateorder) - 1. [SetCustomType For Payment](#11-setcustomtype-for-payment) - 1. [SetCustomType For Customer](#12-setcustomtype-for-customer) - 1. [GetSettings](#13-getsettings) - 1. [Refund](#14-refund) - 1. [Partial Refund](#15-partial-refund) - 1. [CreateVaultSetupToken](#16-createvaultsetuptoken) - * [Card](#i-example-request-card) - * [PayPal](#ii-example-request-paypal-1) - 1. [getUserIdToken](#17-getuseridtoken) - 1. [createPaymentToken](#18-createpaymenttoken) - 1. [getPaymentTokens](#19-getpaymenttokens) - 1. [deletePaymentToken](#20-deletepaymenttoken) + 2. [getClientToken](#2-getclienttoken) + 3. [CaptureOrder](#3-captureorder) + 4. [CaptureAuthorization](#4-captureauthorization) + 5. [AuthorizeOrder](#5-authorizeorder) + 6. [GetOrder](#6-getorder) + 7. [GetCapture](#7-getcapture) + 8. [createTrackingInformation](#8-createtrackinginformation) + 9. [updateTrackingInformation](#9-updatetrackinginformation) + 10. [UpdateOrder](#10-updateorder) + 11. [SetCustomType For Payment](#11-setcustomtype-for-payment) + 12. [SetCustomType For Customer](#12-setcustomtype-for-customer) + 13. [GetSettings](#13-getsettings) + 14. [Refund](#14-refund) + 15. [Partial Refund](#15-partial-refund) + 16. [CreateVaultSetupToken](#16-createvaultsetuptoken) + * [Card](#i-example-request-card) + * [PayPal](#ii-example-request-paypal-1) + 17. [getUserIdToken](#17-getuseridtoken) + 18. [createPaymentToken](#18-createpaymenttoken) + 19. [getPaymentTokens](#19-getpaymenttokens) + 20. [deletePaymentToken](#20-deletepaymenttoken) -------- diff --git a/docs/usecases/README.MD b/docs/usecases/README.MD index 55e6670..7c28f7a 100644 --- a/docs/usecases/README.MD +++ b/docs/usecases/README.MD @@ -25,7 +25,7 @@ In this folder you can find the use cases for the PayPal commercetools connector - [Rendering payment buttons](#rendering-payment-buttons) - [Payment methods parameters](#payment-methods-parameters) - [Payment method dependent flow](#payment-method-dependent-flow) - - [PayPal](#paypal-1) + - [PayPal PayPal buy now](#paypal-buy-now) - [Card](#card) - [Pay Upon Invoice](#pay-upon-invoice-1) @@ -130,12 +130,12 @@ the further steps are triggered by the user actions, like pressing the payment b For the parameters please see also the [PayPal client documentation](https://github.com/mediaopt/paypal-commercetools-client/blob/main/docs/CoFe-PayPal-client-integration.pdf). Here we will only describe the API parameters required for the demonstrated payment methods. In our implementation all mentioned urls trigger corresponding methods at the [PayPal controller CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/PayPalController.ts). Please follow the link for the code, here we only briefly mention the principle. | Parameter | Required for functioning | Description | -| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -| createPaymentUrl | all components | triggers createPayment. Within this method cart is fetched to check if a relevant PayPal payment already exists, if not the new PayPal type payment is created, returns [CreatePaymentResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | | -| getClientTokenUrl | except PayPal payment buttons | triggers getClientToken. Within this method the client token is obtained from the PayPal side and returned. | | -| createPayPalOrder | all payments | triggers createPayPalOrder. Within this methods cart is fetched to obtain payment details and line items, than payment [custom fields](https://docs.commercetools.com/api/projects/custom-fields) are updated to trigger the connector (see also createPayPalOrder in Postman collection). [CreateOrderResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) is returned. | | -| onApproveUrl | all payments except Pay Upon Invoice | triggers capturePayPalOrder. Within this method if not provided in a call a relevant order id is obtained from card payment information and connector capturePayPalOrder is triggered (also by payment custom fields). Returns [OnApproveResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | | -| authenticateThreeDSOrderUrl | payments with 3D secure | triggers authenticateThreeDSOrder. Within this method the request is parsed to identify if the 3D secure passed successfully. Returns returns an object with the liability_shift, enrollment_status, and authentication_status. | | +|-----------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| createPaymentUrl | all components | triggers **createPayment**. Within this method cart is fetched to check if a relevant PayPal payment already exists, if not the new PayPal type payment is created, returns [CreatePaymentResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | +| getClientTokenUrl | except PayPal payment buttons | triggers **getClientToken**. Within this method the client token is obtained from the PayPal side and returned. | +| createPayPalOrder | all payments | triggers **createPayPalOrder**. Within this methods cart is fetched to obtain payment details and line items, than payment [custom fields](https://docs.commercetools.com/api/projects/custom-fields) are updated to trigger the connector (see also createPayPalOrder in Postman collection). [CreateOrderResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) is returned. | +| onApproveUrl | all payments except Pay Upon Invoice | triggers **capturePayPalOrder**. Within this method if not provided in a call a relevant order id is obtained from card payment information and connector capturePayPalOrder is triggered (also by payment custom fields). Returns [OnApproveResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | +| authenticateThreeDSOrderUrl | payments with 3D secure | triggers **authenticateThreeDSOrder**. Within this method the data passed through the client are parsed to identify if the 3D secure passed successfully. Returns returns an object with the liability_shift, enrollment_status, and authentication_status. | ### Payment method dependent flow From 818726d4644bcac7f8f728c4d178b00a353c27d3 Mon Sep 17 00:00:00 2001 From: liudmyla Date: Wed, 17 Jul 2024 15:31:23 +0200 Subject: [PATCH 06/11] 36803 - some documentation corrections --- README.md | 35 +++++++++++++--------- docs/{usecases => workflows}/README.MD | 40 +++++++++++++++----------- 2 files changed, 46 insertions(+), 29 deletions(-) rename docs/{usecases => workflows}/README.MD (82%) diff --git a/README.md b/README.md index dee8573..32b4d4c 100644 --- a/README.md +++ b/README.md @@ -15,28 +15,37 @@ This is a [connect application](https://marketplace.commercetools.com/) to integ [PayPal commercetools connector](https://marketplace.commercetools.com/integration/paypal) is available in the commercetools marketplace. -The connector is designed be used together with [PayPal client api](https://www.npmjs.com/package/paypal-commercetools-client) for the frontend integration. If it is not possible for some reason you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. - -The payments demo and integration to the commercetools frontend can be seen at https://poc-mediaopt2.frontend.site/ and [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). +## Project Description +The project demo website https://poc-mediaopt2.frontend.site/ is built using three parts: +1. The connector itself, provided in this repository +2. The PayPal client api for the frontend integration. The client is available at [npm](https://www.npmjs.com/package/paypal-commercetools-client) and [github](https://github.com/mediaopt/paypal-commercetools-client). If for some reason you can't use the client for your integration - you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. +3. The client is integrated in commercetools frontend. Using commercetools frontend for storefront is optional. The integration details can be seen ad [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). ## Prerequisites To use the connector you need to have the following: - commercetools Composable Commerce account and [API client](https://docs.commercetools.com/api/projects/api-clients#apiclient) credentials, namely: - - region (CTP_REGION) - region, in which your commercetools project is hosted - - project key (CTP_PROJECT_KEY) - the key of your commercetools project - - client ID (CTP_CLIENT_ID) - the ID of your commercetools API client - - client secret (CTP_CLIENT_SECRET) - the secret of your commercetools API client - - scope (CTP_SCOPE) - the scope of your commercetools API client + +| credential | environmental variable | description | +|---------------|------------------------|-------------------------------------------------------| +| region | CTP_REGION | region, in which your commercetools project is hosted | +| project key | CTP_PROJECT_KEY) | the key of your commercetools project | +| client ID | CTP_CLIENT_ID) | the ID of your commercetools API client | +| client secret | CTP_CLIENT_SECRET | the secret of your commercetools API client | +| scope | CTP_SCOPE | the scope of your commercetools API client | + - [PayPal business customer account](https://www.google.com/aclk?sa=l&ai=DChcSEwjPz82wyK2GAxWSiVAGHUwzAVoYABABGgJkZw&gclid=Cj0KCQjw3tCyBhDBARIsAEY0XNnOcx462M0ej3RizrdN9a_6fl2O5_bfwVqOOzyHxz_9M7L10B8NfL0aAgA6EALw_wcB&sig=AOD64_0bOBSNaFhCg-wypewofyWkrpoBWg&q&adurl&ved=2ahUKEwiIqcewyK2GAxXlSkEAHejBBbQQqyQoAHoECAIQDA) and [API client](https://developer.paypal.com/api/rest/#link-getclientidandclientsecret) credentials,namely: - - client ID (PAYPAL_CLIENT_ID) - the ID of your PayPal API client - - client secret (PAYPAL_CLIENT_SECRET) - the secret of your PayPal API client - - environment (PAYPAL_ENVIRONMENT) - the environment of your PayPal API client (production or sandbox) + +| credential | environmental variable | description | +|---------------|------------------------|-------------------------------------------------------------------| +| client ID | PAYPAL_CLIENT_ID | the ID of your PayPal API client | +| client secret | PAYPAL_CLIENT_SECRET | the secret of your PayPal API client | +| environment | PAYPAL_ENVIRONMENT | the environment of your PayPal API client (production or sandbox) | ## Instructions -The connector can be installed [directly from the commercetools marketplace](https://docs.commercetools.com/merchant-center/connect). +The connector can be installed [directly from the commercetools marketplace](https://docs.commercetools.com/merchant-center/connect) or deployed from github repository via [commercetools Connect API](https://docs.commercetools.com/connect/). To run the connector locally: @@ -62,4 +71,4 @@ In the docs folder you can find: - description of each application included (README.md) - architecture of the connector (Architecture.pdf) - documented PayPal Commercetools API Postman collection (PayPal.md, paypal.postman_collection.json) -- Postman collection for testing the backend workflows for different payment methods (PayPal-commercetools-workflows.postman_collection.json) +- workflows folder with examples how to use the connector individually or together with PayPal client and commercetools frontend \ No newline at end of file diff --git a/docs/usecases/README.MD b/docs/workflows/README.MD similarity index 82% rename from docs/usecases/README.MD rename to docs/workflows/README.MD index 7c28f7a..132d715 100644 --- a/docs/usecases/README.MD +++ b/docs/workflows/README.MD @@ -7,7 +7,7 @@

-In this folder you can find the use cases for the PayPal commercetools connector. Here we summarize the actual workflow and the expected results. The simplified workflow that only includes backend calls through postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). +In this folder you can find the example workflows for the PayPal commercetools connector. Here we summarize the actual workflows for both using only the connector for the backend side implementation and using the [PayPal client](https://www.npmjs.com/package/paypal-commercetools-client) in commercetools Frontend (CoFe) [integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main) and the expected results. The workflow that only includes backend calls through Postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). # Table of Contents @@ -48,7 +48,11 @@ The client can be directly installed to the shop frontend using npm: `npm i paypal-commercetools-client` -and then the components imported directly from the package, see for example the [payment form in CoFe integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). +The client is react-based, so for other frameworks it is needed to load the React script in project stack. + +And then the components are imported directly from the package, see for example the [payment form in CoFe integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). + + # Payment Process @@ -67,7 +71,7 @@ The first two categories are covered in the Postman collection Initial part, the ## Initial flow | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | +|------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | 1 | If not yet - [obtain commercetools access token](https://docs.commercetools.com/api/authorization). | getAccessToken | | 2 | [Create a cart](https://docs.commercetools.com/api/projects/carts) with some products in it. Products can be added during creation or added separately | Search for a product -> Create Cart -> AddLineItem | | 3 | [Create a payment](https://docs.commercetools.com/api/projects/payments) with the `paypal-payment-type`. | SetCustomType For Payment | @@ -107,7 +111,11 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. ## Standard flow -In case of frontend flow the PayPal client components are imported at CoFe frontend and the API required for proper communication between the components and commercetools HTTP API is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). The cart is created by CoFe and is out of scope of this documentation. To create the cart via only HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). +In this section we describe the flow that is used at our the [demo website](https://poc-mediaopt2.frontend.site/) where the PayPal client is integrated into CoFe and the connector is installed at the merchant center. It is important to note that the CoFe project structure involves two separate parts - frontend and backend and [our integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc) involves both of them. + +In our integration the PayPal client components are imported at [CoFe frontend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/frontend) and the API required for proper communication between the components and commercetools HTTP API ((and therefore the PayPal commercetools connector) is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). + +The cart creation before the payment with PayPal begins and the checkout procedure after the PayPal payment is complete are created by standard CoFe methods and are out of scope of this documentation. To create the cart via only HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). Here we will describe the [checkout payment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). @@ -127,15 +135,15 @@ the further steps are triggered by the user actions, like pressing the payment b ### Payment methods parameters -For the parameters please see also the [PayPal client documentation](https://github.com/mediaopt/paypal-commercetools-client/blob/main/docs/CoFe-PayPal-client-integration.pdf). Here we will only describe the API parameters required for the demonstrated payment methods. In our implementation all mentioned urls trigger corresponding methods at the [PayPal controller CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/PayPalController.ts). Please follow the link for the code, here we only briefly mention the principle. +For complete list of parameters please see the [PayPal client documentation](https://github.com/mediaopt/paypal-commercetools-client/blob/main/docs/CoFe-PayPal-client-integration.pdf). Here we will only describe the API parameters required for the demonstrated payment methods. In our implementation all mentioned urls trigger corresponding methods at the [PayPal controller CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/PayPalController.ts). Please follow the link for the code, here we only briefly mention the principle. -| Parameter | Required for functioning | Description | -|-----------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| createPaymentUrl | all components | triggers **createPayment**. Within this method cart is fetched to check if a relevant PayPal payment already exists, if not the new PayPal type payment is created, returns [CreatePaymentResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | -| getClientTokenUrl | except PayPal payment buttons | triggers **getClientToken**. Within this method the client token is obtained from the PayPal side and returned. | -| createPayPalOrder | all payments | triggers **createPayPalOrder**. Within this methods cart is fetched to obtain payment details and line items, than payment [custom fields](https://docs.commercetools.com/api/projects/custom-fields) are updated to trigger the connector (see also createPayPalOrder in Postman collection). [CreateOrderResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) is returned. | -| onApproveUrl | all payments except Pay Upon Invoice | triggers **capturePayPalOrder**. Within this method if not provided in a call a relevant order id is obtained from card payment information and connector capturePayPalOrder is triggered (also by payment custom fields). Returns [OnApproveResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | -| authenticateThreeDSOrderUrl | payments with 3D secure | triggers **authenticateThreeDSOrder**. Within this method the data passed through the client are parsed to identify if the 3D secure passed successfully. Returns returns an object with the liability_shift, enrollment_status, and authentication_status. | +| Parameter | Required for functioning | Description | +| --------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| createPaymentUrl | all components | triggers **createPayment**. Within this method cart is fetched to check if a relevant PayPal payment already exists, if not the new PayPal type payment is created, returns [CreatePaymentResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | +| getClientTokenUrl | except PayPal payment buttons | triggers **getClientToken**. Within this method the client token is obtained from the PayPal side and returned. | +| createPayPalOrder | all payments | triggers **createPayPalOrder**. Within this methods cart is fetched to obtain payment details and line items, than payment [custom fields](https://docs.commercetools.com/api/projects/custom-fields) are updated to trigger the connector (see also createPayPalOrder in Postman collection). [CreateOrderResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) is returned. | +| onApproveUrl | all payments except Pay Upon Invoice | triggers **capturePayPalOrder**. Within this method if not provided in a call a relevant order id is obtained from card payment information and connector capturePayPalOrder is triggered (also by payment custom fields). Returns [OnApproveResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | +| authenticateThreeDSOrderUrl | payments with 3D secure | triggers **authenticateThreeDSOrder**. Within this method the data passed through the client are parsed to identify if the 3D secure passed successfully. Returns returns an object with the liability_shift, enrollment_status, and authentication_status. | ### Payment method dependent flow @@ -148,15 +156,15 @@ In most of the payment cases the first three steps are the same: #### Pay Upon Invoice 1. After user completes the additional data required only for Pay Upon Invoice payment and confirms, the createPayPalOrder is triggered -2. as Pay Upon Invoice does not require immediate payment - we trigger a custom checkout process for pay upon invoice - after the user completes invoice payment on the RatePay side the webhook at the connector side is triggered to capture the order. +2. as Pay Upon Invoice does not require immediate payment - we trigger a custom checkout process for pay upon invoice (with extra liability message) +3. after the user completes invoice payment on the RatePay side the webhook at the connector side is triggered to capture the order. #### PayPal buy now 1. On click on the target button createPayPalOrderUrl is called 2. if createPayPalOrder call was successfully - the floating window with PayPal login or payment form is opened and the payment can proceed. 3. the user completes the payment on PayPal side and on success onApproveUrl is addressed and capturePayPalOrder is triggered -4. after successfully capture, we trigger the standard checkout process on the frontend side +4. after successful capture, we trigger the standard checkout process on the frontend side #### Card @@ -164,4 +172,4 @@ In most of the payment cases the first three steps are the same: 2. if 3D secure is required - the floating window with 3D secure form is opened and user needs to confirm the payment 3. if 3D secure is required - authenticateThreeDSOrderUrl is called to authenticate the payment 4. if 3D secure is successful or not required - onApproveUrl is addressed and capturePayPalOrder is triggered -5. after successfully capture, we trigger the standard checkout process on the frontend side +5. after successful capture, we trigger the standard checkout process on the frontend side From d73ec09bcf447280ef568cbe61650b1142bec3fd Mon Sep 17 00:00:00 2001 From: liudmyla Date: Thu, 18 Jul 2024 10:08:40 +0200 Subject: [PATCH 07/11] 36803 - fixes after review --- README.md | 11 +++++------ docs/workflows/README.MD | 23 ++++++++++++----------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 32b4d4c..db4b788 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,10 @@ This is a [connect application](https://marketplace.commercetools.com/) to integ [PayPal commercetools connector](https://marketplace.commercetools.com/integration/paypal) is available in the commercetools marketplace. -## Project Description -The project demo website https://poc-mediaopt2.frontend.site/ is built using three parts: -1. The connector itself, provided in this repository -2. The PayPal client api for the frontend integration. The client is available at [npm](https://www.npmjs.com/package/paypal-commercetools-client) and [github](https://github.com/mediaopt/paypal-commercetools-client). If for some reason you can't use the client for your integration - you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. -3. The client is integrated in commercetools frontend. Using commercetools frontend for storefront is optional. The integration details can be seen ad [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). +The payments demo can be seen at https://poc-mediaopt2.frontend.site/. + +## Integration +The connector is supposed to be used together with the PayPal client app. The client is available at [npm](https://www.npmjs.com/package/paypal-commercetools-client) and [github](https://github.com/mediaopt/paypal-commercetools-client). The connector is responsible for the backend integration with commercetools and PayPal, while the client is responsible for the frontend. If for some reasons the PayPal client app can't be used, the [PayPal JS SDK](https://developer.paypal.com/sdk/js/) should be used instead. The example of the integration with commercetools frontend is covered in [docs/usecases/README.md](docs/usecases/README.md) and the code can be seen in [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). ## Prerequisites @@ -35,7 +34,7 @@ To use the connector you need to have the following: | client secret | CTP_CLIENT_SECRET | the secret of your commercetools API client | | scope | CTP_SCOPE | the scope of your commercetools API client | -- [PayPal business customer account](https://www.google.com/aclk?sa=l&ai=DChcSEwjPz82wyK2GAxWSiVAGHUwzAVoYABABGgJkZw&gclid=Cj0KCQjw3tCyBhDBARIsAEY0XNnOcx462M0ej3RizrdN9a_6fl2O5_bfwVqOOzyHxz_9M7L10B8NfL0aAgA6EALw_wcB&sig=AOD64_0bOBSNaFhCg-wypewofyWkrpoBWg&q&adurl&ved=2ahUKEwiIqcewyK2GAxXlSkEAHejBBbQQqyQoAHoECAIQDA) and [API client](https://developer.paypal.com/api/rest/#link-getclientidandclientsecret) credentials,namely: +- [PayPal business customer account](https://www.paypal.com/de/business/getting-started) and [API client](https://developer.paypal.com/api/rest/#link-getclientidandclientsecret) credentials,namely: | credential | environmental variable | description | |---------------|------------------------|-------------------------------------------------------------------| diff --git a/docs/workflows/README.MD b/docs/workflows/README.MD index 132d715..19d193e 100644 --- a/docs/workflows/README.MD +++ b/docs/workflows/README.MD @@ -31,16 +31,16 @@ In this folder you can find the example workflows for the PayPal commercetools c # Installation -The connector itself is the backend part of the payment process, it is designed to be used together with the [PayPal client api](https://www.npmjs.com/package/paypal-commercetools-client) for the frontend integration. If it is not possible for some reason you are obliged to use [PayPal JS SDK](https://developer.paypal.com/sdk/js/) instead. We also use commercetools frontend (further referred as CoFe), but it is an optional part, shown here for illustration how to develop necessary API for the PayPal client. +For installation of CoFe please refer to [commercetools official documentation](https://commercetools.com/products/frontend). If you prefer to use the PayPal JS SDK instead of the PayPal client app, please refer to [PayPal official documentation](https://developer.paypal.com/sdk/js/) ## Connector installation -There are two possible ways to integrate the connector, both fully covered in the mentioned documentation. +There are two possible ways to integrate the connector, both fully covered in the following documentation. 1. Installed [directly from the commercetools marketplace](https://docs.commercetools.com/merchant-center/connect). 2. Create your own deployment using [commercetools connect API](https://docs.commercetools.com/connect/getting-started). -The connector includes a merchant center application, which is automatically installed and deployed when installing the connector, but it might be needed to update the custom application link after the deployment, as described in [commercetools documentation](https://docs.commercetools.com/merchant-center-customizations/deployment-examples/commercetools-connect). +The connector includes a merchant center application, which is automatically installed and deployed when installing the connector. If the custom application doesn't work correct after deployment please [check if its link is up-to-date](https://docs.commercetools.com/merchant-center-customizations/deployment-examples/commercetools-connect). ## Frontend installation @@ -81,20 +81,21 @@ The first two categories are covered in the Postman collection Initial part, the ## Payment method specific flow MOST OF THE METHODS REQUIRES USER APPROVAL AFTER CREATE PAYPAL ORDER. IT MEANS THAT THE USER SHOULD APPROVE THE ORDER VIA THE LINK, PROVIDED IN THE RESPONSE. -In case if this is applicable for a certain method - it is mentioned in the method description. For sandbox testing sanbdox customer credentials or [sandbox testing cards provided in the PayPal documentation](https://developer.paypal.com/tools/sandbox/card-testing/) can be used to approve the order. + +In case if this is applicable for a certain method - it is mentioned in the method description. For sandbox testing PayPal sandbox customer credentials or [sandbox testing cards provided by PayPal](https://developer.paypal.com/tools/sandbox/card-testing/) can be used to approve the order. ### Pay Upon Invoice Pay Upon invoice is the simplest as the payment is not processed immediately. | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -| ---- | ---------------------------------------------- | ------------------------------------------------------------------------------------ | +|------|------------------------------------------------|--------------------------------------------------------------------------------------| | 1 | Create an order with Invoice as payment source | createPayPalOrder | ### PayPal | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -| ---- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +|------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | 1 | Create an order with PayPal as payment source | createPayPalOrder | | 2 | In your browser open the link with the "rel" approve in create order response and approve the order | - | | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | @@ -103,7 +104,7 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. ### Card payment | Step | Description | [Postman Collection](PayPal-commercetools-workflow.postman_collection.json) workflow | -| ---- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +|------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | 1 | Create an order with card as payment source | createPayPalOrder | | 2 | In your browser open the link with the "rel" approve in create order response and approve the order | - | | 3 | Get payment by id, to update the payment version, as the correct version is needed for next step | Get Payment By Id | @@ -111,11 +112,11 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. ## Standard flow -In this section we describe the flow that is used at our the [demo website](https://poc-mediaopt2.frontend.site/) where the PayPal client is integrated into CoFe and the connector is installed at the merchant center. It is important to note that the CoFe project structure involves two separate parts - frontend and backend and [our integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc) involves both of them. +In this section we describe the flow that is used at our [demo website](https://poc-mediaopt2.frontend.site/) where the PayPal client is integrated into CoFe and the connector is installed at the merchant center. It is important to note that the CoFe project structure involves two separate parts - frontend and backend and [our integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc) involves both of them. In our integration the PayPal client components are imported at [CoFe frontend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/frontend) and the API required for proper communication between the components and commercetools HTTP API ((and therefore the PayPal commercetools connector) is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). -The cart creation before the payment with PayPal begins and the checkout procedure after the PayPal payment is complete are created by standard CoFe methods and are out of scope of this documentation. To create the cart via only HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). +The cart creation before the payment with PayPal begins and the checkout procedure after the PayPal payment is complete are created by standard CoFe methods and are out of scope of this documentation. To create the cart via HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). Here we will describe the [checkout payment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx). @@ -138,7 +139,7 @@ the further steps are triggered by the user actions, like pressing the payment b For complete list of parameters please see the [PayPal client documentation](https://github.com/mediaopt/paypal-commercetools-client/blob/main/docs/CoFe-PayPal-client-integration.pdf). Here we will only describe the API parameters required for the demonstrated payment methods. In our implementation all mentioned urls trigger corresponding methods at the [PayPal controller CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/PayPalController.ts). Please follow the link for the code, here we only briefly mention the principle. | Parameter | Required for functioning | Description | -| --------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-----------------------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | createPaymentUrl | all components | triggers **createPayment**. Within this method cart is fetched to check if a relevant PayPal payment already exists, if not the new PayPal type payment is created, returns [CreatePaymentResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) | | getClientTokenUrl | except PayPal payment buttons | triggers **getClientToken**. Within this method the client token is obtained from the PayPal side and returned. | | createPayPalOrder | all payments | triggers **createPayPalOrder**. Within this methods cart is fetched to obtain payment details and line items, than payment [custom fields](https://docs.commercetools.com/api/projects/custom-fields) are updated to trigger the connector (see also createPayPalOrder in Postman collection). [CreateOrderResponse](https://github.com/mediaopt/paypal-commercetools-client/blob/main/src/types/index.ts) is returned. | @@ -151,7 +152,7 @@ In most of the payment cases the first three steps are the same: 1. On rendering the button the createPaymentUrl is called to obtain/generate the relevant payment id. 2. If relevant getClientToken is called to obtain the client token at the PayPal side. -3. The button is than rendered by the client via PayPal JS SDK. +3. The button is then rendered by the client via PayPal JS SDK. #### Pay Upon Invoice From e17ad182a8780bae950acc81b29c2d62e89bd0ba Mon Sep 17 00:00:00 2001 From: liudmyla Date: Thu, 18 Jul 2024 10:11:24 +0200 Subject: [PATCH 08/11] 36803 - fixed the workflows folder name and references to it --- README.md | 2 +- .../PayPal-commercetools-workflow.postman_collection.json | 0 docs/workflows/{README.MD => README.md} | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename docs/{usecases => workflows}/PayPal-commercetools-workflow.postman_collection.json (100%) rename docs/workflows/{README.MD => README.md} (100%) diff --git a/README.md b/README.md index db4b788..35a7fd0 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ This is a [connect application](https://marketplace.commercetools.com/) to integ The payments demo can be seen at https://poc-mediaopt2.frontend.site/. ## Integration -The connector is supposed to be used together with the PayPal client app. The client is available at [npm](https://www.npmjs.com/package/paypal-commercetools-client) and [github](https://github.com/mediaopt/paypal-commercetools-client). The connector is responsible for the backend integration with commercetools and PayPal, while the client is responsible for the frontend. If for some reasons the PayPal client app can't be used, the [PayPal JS SDK](https://developer.paypal.com/sdk/js/) should be used instead. The example of the integration with commercetools frontend is covered in [docs/usecases/README.md](docs/usecases/README.md) and the code can be seen in [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). +The connector is supposed to be used together with the PayPal client app. The client is available at [npm](https://www.npmjs.com/package/paypal-commercetools-client) and [github](https://github.com/mediaopt/paypal-commercetools-client). The connector is responsible for the backend integration with commercetools and PayPal, while the client is responsible for the frontend. If for some reasons the PayPal client app can't be used, the [PayPal JS SDK](https://developer.paypal.com/sdk/js/) should be used instead. The example of the integration with commercetools frontend is covered in [docs/usecases/README.md](docs/workflows/README.md) and the code can be seen in [github](https://github.com/mediaopt/paypal-commercetools-cofe-integration). ## Prerequisites diff --git a/docs/usecases/PayPal-commercetools-workflow.postman_collection.json b/docs/workflows/PayPal-commercetools-workflow.postman_collection.json similarity index 100% rename from docs/usecases/PayPal-commercetools-workflow.postman_collection.json rename to docs/workflows/PayPal-commercetools-workflow.postman_collection.json diff --git a/docs/workflows/README.MD b/docs/workflows/README.md similarity index 100% rename from docs/workflows/README.MD rename to docs/workflows/README.md From a394642287cbd5e1efab1a8ab04c2d86d01203d8 Mon Sep 17 00:00:00 2001 From: liudmyla Date: Fri, 19 Jul 2024 09:16:46 +0200 Subject: [PATCH 09/11] 36803 - added sequence diagram and slightly modified readme text --- docs/workflows/README.md | 18 +++++-- .../sequence_diagram_paypal_payment.md | 53 +++++++++++++++++++ 2 files changed, 66 insertions(+), 5 deletions(-) create mode 100644 docs/workflows/sequence_diagram_paypal_payment.md diff --git a/docs/workflows/README.md b/docs/workflows/README.md index 19d193e..2e8e305 100644 --- a/docs/workflows/README.md +++ b/docs/workflows/README.md @@ -7,7 +7,15 @@

-In this folder you can find the example workflows for the PayPal commercetools connector. Here we summarize the actual workflows for both using only the connector for the backend side implementation and using the [PayPal client](https://www.npmjs.com/package/paypal-commercetools-client) in commercetools Frontend (CoFe) [integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main) and the expected results. The workflow that only includes backend calls through Postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). +In this folder you can find simplified example workflows for the PayPal commercetools connector, which should be sufficient to reproduce demonstrated payments. For all details please refer to [Architecture.pdf](../Architecture.pdf). + +Here we summarize the actual workflows for: +1. using only the connector for the backend side implementation +2. using the [PayPal client](https://www.npmjs.com/package/paypal-commercetools-client) in commercetools Frontend (CoFe) [integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main). + +The workflow that only includes backend calls through Postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). + +The sequence diagram that show a bit more details about the backend side of a payment process with PayPal buy now payment is also provided at [sequence_diagram_paypal_payment.md](sequence_diagram_paypal_payment.md). # Table of Contents @@ -25,13 +33,13 @@ In this folder you can find the example workflows for the PayPal commercetools c - [Rendering payment buttons](#rendering-payment-buttons) - [Payment methods parameters](#payment-methods-parameters) - [Payment method dependent flow](#payment-method-dependent-flow) - - [PayPal PayPal buy now](#paypal-buy-now) + - [PayPal buy now](#paypal-buy-now) - [Card](#card) - [Pay Upon Invoice](#pay-upon-invoice-1) # Installation -For installation of CoFe please refer to [commercetools official documentation](https://commercetools.com/products/frontend). If you prefer to use the PayPal JS SDK instead of the PayPal client app, please refer to [PayPal official documentation](https://developer.paypal.com/sdk/js/) +For installation of CoFe please refer to [commercetools official documentation](https://commercetools.com/products/frontend). If you prefer to use the PayPal JS SDK instead of the PayPal client app, please refer to [PayPal official documentation](https://developer.paypal.com/sdk/js/). ## Connector installation @@ -112,7 +120,7 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. ## Standard flow -In this section we describe the flow that is used at our [demo website](https://poc-mediaopt2.frontend.site/) where the PayPal client is integrated into CoFe and the connector is installed at the merchant center. It is important to note that the CoFe project structure involves two separate parts - frontend and backend and [our integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc) involves both of them. +In this section we describe the flow that is used at our [demo website](https://poc-mediaopt2.frontend.site/) where the PayPal client is integrated into CoFe and the connector is installed at the merchant center. It is important to note that the CoFe project structure involves two separate parts - frontend and backend and [our integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc) involves both of them. Frontend is responsible for a client side and backend for the server (see also [Architecture.pdf](../Architecture.pdf)). In our integration the PayPal client components are imported at [CoFe frontend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/frontend) and the API required for proper communication between the components and commercetools HTTP API ((and therefore the PayPal commercetools connector) is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). @@ -123,7 +131,7 @@ Here we will describe the [checkout payment](https://github.com/mediaopt/paypal- ### Rendering payment buttons | Step | performed at | description | -| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | CoFe frontend [formPayment](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/components/commercetools-ui/checkout/checkout-form/fields/formPayment.tsx) | all necessary payment methods are imported from the package:
`import { PayPal, PayUponInvoice, CardFields, ApplePay, GooglePay } from 'paypal-commercetools-client/dist/esm';` | | 2 | CoFe frontend [actions](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/frontend/frontastic/actions/paypal/index.ts) | the getSettings is called. It actually uses [commercetools frontend api action](https://docs.commercetools.com/frontend-api/action) and addresses CoFe backend | | 3 | CoFe backend [SettingsController](https://github.com/mediaopt/paypal-commercetools-cofe-integration/blob/main/packages/poc/backend/payment-paypal/actionControllers/SettingController.ts) | commercetools HTTP API is used to obtain PayPal settings (see also the [PayPal Postman collection](https://github.com/mediaopt/paypal-commercetools-connector/blob/main/docs/paypal.postman_collection.json) getSettings call). | diff --git a/docs/workflows/sequence_diagram_paypal_payment.md b/docs/workflows/sequence_diagram_paypal_payment.md new file mode 100644 index 0000000..7b85cce --- /dev/null +++ b/docs/workflows/sequence_diagram_paypal_payment.md @@ -0,0 +1,53 @@ +Here we present a simplified sequence diagram for payment process with PayPal buy now payment. For full detailed process please refer to [Architecture.pdf](../Architecture.pdf). + +In this diagram we focus on the interaction with the PayPal commercetools connector and PayPal client app required to complete the payment. + +The communication between commercetools frontend (CoFe) and commercetools HTTP API (CoCo) that is not related directly to the payment with PayPal is not shown in this diagram. In brief CoFe has built in routines to update the cart and the payment whenever they might have being changed. + +The official documentation for the API mentioned it the diagram can be found at [commercetools Frontend API's](https://docs.commercetools.com/frontend-api/action), [commercetools HTTP API](https://docs.commercetools.com/http-api), and [PayPal orders v2 API](https://developer.paypal.com/docs/api/orders/v2/). + +```mermaid +sequenceDiagram + title PayPal payment flow + box CoFe + participant frontend as frontend/client app + participant backend + end + participant CoCo as CoCo/connector (extension) + Note over frontend,backend: commercetools Frontend API + Note over backend, CoCo: commercetools HTTP API,
connector: endpoint custom-objects
or action custom fields + Note over CoCo, PayPal: PayPal orders v2 API + frontend-->>backend: getSettings action + backend-->>CoCo: getSetting request + Note over backend, CoCo: endpoint >custom-objects/
paypal-commercetools-connector + CoCo-->>backend: GetSettingsResponse + backend-->>frontend: GetSettingsResponse, Session data + frontend-->>backend: createPayment action + backend-->>CoCo: createPayment request + note over backend, CoCo: paymentInterface: 'PayPal' + CoCo-->>backend: createPayment response + backend-->>CoCo: updateCart request + note over backend, CoCo: action addPayment + CoCo-->>backend: updateCart response + backend-->>frontend: cart data, payment data, session data + frontend-->>frontend: render payment component(s) + frontend-->>frontend: user clicks on buy now button + frontend-->>backend: createOrder action. + backend-->>CoCo: createPayPalOrder request + Note over backend, CoCo: endpoint payments/{{payment-id}}
action setCustomField + CoCo-->>PayPal: PayPal createOrder request + PayPal-->>CoCo: PayPal createOrder response + CoCo-->>CoCo: update payment request + CoCo-->>backend: createPayPal order response + backend-->>frontend: createPayPal order response, payment data + create participant window as PayPal floating window + frontend-->>window: PayPal order data + window-->>window: user approves the payment + destroy window + window-->>frontend: order approve + frontend-->>backend: captureOrder action + backend-->>CoCo: capturePayPal order request + Note over backend, CoCo: endpoint payments/{{payment-id}}
action setCustomField + CoCo-->>backend: capturePayPal order response + backend-->>frontend: capturePayPal order response, payment data +``` \ No newline at end of file From 74c8fa3c68671905b4a7e5b12611a7dcdd506fec Mon Sep 17 00:00:00 2001 From: liudmyla Date: Fri, 19 Jul 2024 09:22:42 +0200 Subject: [PATCH 10/11] 36803 - added required steps to start payment --- docs/workflows/sequence_diagram_paypal_payment.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/workflows/sequence_diagram_paypal_payment.md b/docs/workflows/sequence_diagram_paypal_payment.md index 7b85cce..269c4da 100644 --- a/docs/workflows/sequence_diagram_paypal_payment.md +++ b/docs/workflows/sequence_diagram_paypal_payment.md @@ -2,7 +2,7 @@ Here we present a simplified sequence diagram for payment process with PayPal bu In this diagram we focus on the interaction with the PayPal commercetools connector and PayPal client app required to complete the payment. -The communication between commercetools frontend (CoFe) and commercetools HTTP API (CoCo) that is not related directly to the payment with PayPal is not shown in this diagram. In brief CoFe has built in routines to update the cart and the payment whenever they might have being changed. +The communication between commercetools frontend (CoFe) and commercetools HTTP API (CoCo) that is not related directly to the payment with PayPal is not explained in this diagram. In brief CoFe has built in routines to update the cart and the payment whenever they might have being changed. The official documentation for the API mentioned it the diagram can be found at [commercetools Frontend API's](https://docs.commercetools.com/frontend-api/action), [commercetools HTTP API](https://docs.commercetools.com/http-api), and [PayPal orders v2 API](https://developer.paypal.com/docs/api/orders/v2/). @@ -17,6 +17,7 @@ sequenceDiagram Note over frontend,backend: commercetools Frontend API Note over backend, CoCo: commercetools HTTP API,
connector: endpoint custom-objects
or action custom fields Note over CoCo, PayPal: PayPal orders v2 API + Note over frontend, CoCo: Cart is created by built in CoFe methods and has products and user data in it frontend-->>backend: getSettings action backend-->>CoCo: getSetting request Note over backend, CoCo: endpoint >custom-objects/
paypal-commercetools-connector From 4e25e9ee0d9321a0be27438bc3579973641646da Mon Sep 17 00:00:00 2001 From: liudmyla Date: Mon, 12 Aug 2024 10:34:46 +0200 Subject: [PATCH 11/11] 36803 - minor fixes after review --- docs/workflows/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/workflows/README.md b/docs/workflows/README.md index 2e8e305..a2b2e50 100644 --- a/docs/workflows/README.md +++ b/docs/workflows/README.md @@ -13,9 +13,9 @@ Here we summarize the actual workflows for: 1. using only the connector for the backend side implementation 2. using the [PayPal client](https://www.npmjs.com/package/paypal-commercetools-client) in commercetools Frontend (CoFe) [integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main). -The workflow that only includes backend calls through Postman is also provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). +The workflow that only includes backend calls through Postman is provided as a [workflow Postman Collection](PayPal-commercetools-workflow.postman_collection.json). -The sequence diagram that show a bit more details about the backend side of a payment process with PayPal buy now payment is also provided at [sequence_diagram_paypal_payment.md](sequence_diagram_paypal_payment.md). +The sequence diagram that shows more details about the backend side of a payment process with PayPal Buy Now payment is also provided at [sequence_diagram_paypal_payment.md](sequence_diagram_paypal_payment.md). # Table of Contents @@ -33,7 +33,7 @@ The sequence diagram that show a bit more details about the backend side of a pa - [Rendering payment buttons](#rendering-payment-buttons) - [Payment methods parameters](#payment-methods-parameters) - [Payment method dependent flow](#payment-method-dependent-flow) - - [PayPal buy now](#paypal-buy-now) + - [PayPal Buy Now](#paypal-buy-now) - [Card](#card) - [Pay Upon Invoice](#pay-upon-invoice-1) @@ -122,7 +122,7 @@ Pay Upon invoice is the simplest as the payment is not processed immediately. In this section we describe the flow that is used at our [demo website](https://poc-mediaopt2.frontend.site/) where the PayPal client is integrated into CoFe and the connector is installed at the merchant center. It is important to note that the CoFe project structure involves two separate parts - frontend and backend and [our integration](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc) involves both of them. Frontend is responsible for a client side and backend for the server (see also [Architecture.pdf](../Architecture.pdf)). -In our integration the PayPal client components are imported at [CoFe frontend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/frontend) and the API required for proper communication between the components and commercetools HTTP API ((and therefore the PayPal commercetools connector) is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). +In our integration the PayPal client components are imported at [CoFe frontend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/frontend) and the API required for proper communication between the components and commercetools HTTP API (and therefore the PayPal commercetools connector) is developed at the [CoFe backend](https://github.com/mediaopt/paypal-commercetools-cofe-integration/tree/main/packages/poc/backend). The cart creation before the payment with PayPal begins and the checkout procedure after the PayPal payment is complete are created by standard CoFe methods and are out of scope of this documentation. To create the cart via HTTP API please see the [official commercetools documentation](https://docs.commercetools.com/api/). @@ -168,7 +168,7 @@ In most of the payment cases the first three steps are the same: 2. as Pay Upon Invoice does not require immediate payment - we trigger a custom checkout process for pay upon invoice (with extra liability message) 3. after the user completes invoice payment on the RatePay side the webhook at the connector side is triggered to capture the order. -#### PayPal buy now +#### PayPal Buy Now 1. On click on the target button createPayPalOrderUrl is called 2. if createPayPalOrder call was successfully - the floating window with PayPal login or payment form is opened and the payment can proceed.