From b3e8e765133d8dae02b79f5d887f2debdff9eca0 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Wed, 7 Aug 2019 14:47:53 -0500 Subject: [PATCH 1/3] Hosted Pro docs --- _data/toc/graphql.yml | 6 ++ .../payment-methods/hosted-pro-attributes.md | 4 ++ .../payment-methods/hosted-pro-workflow.md | 21 ++++++ common/images/graphql/paypal-hosted-pro.svg | 2 + .../graphql/payment-methods/hosted-pro.md | 64 +++++++++++++++++++ .../graphql/queries/get-hosted-pro-url.md | 52 +++++++++++++++ 6 files changed, 149 insertions(+) create mode 100644 _includes/graphql/payment-methods/hosted-pro-attributes.md create mode 100644 _includes/graphql/payment-methods/hosted-pro-workflow.md create mode 100644 common/images/graphql/paypal-hosted-pro.svg create mode 100644 guides/v2.3/graphql/payment-methods/hosted-pro.md create mode 100644 guides/v2.3/graphql/queries/get-hosted-pro-url.md diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml index 279f667437f..bcea7cae32a 100644 --- a/_data/toc/graphql.yml +++ b/_data/toc/graphql.yml @@ -68,6 +68,9 @@ pages: - label: customerPaymentTokens query url: /graphql/queries/customer-payment-tokens.html + - label: getHostedProUrl query + url: /graphql/queries/get-hosted-pro-url.html + - label: storeConfig query url: /graphql/queries/store-config.html @@ -208,6 +211,9 @@ pages: - label: PayPal Payments Advanced url: /graphql/payment-methods/payments-advanced.html + - label: PayPal Website Payments Pro Hosted Solution + url: /graphql/payment-methods/hosted-pro.html + - label: Tutorial class: tutorial url: /graphql/tutorials/checkout/index.html diff --git a/_includes/graphql/payment-methods/hosted-pro-attributes.md b/_includes/graphql/payment-methods/hosted-pro-attributes.md new file mode 100644 index 00000000000..519f26b08de --- /dev/null +++ b/_includes/graphql/payment-methods/hosted-pro-attributes.md @@ -0,0 +1,4 @@ +Attribute | Data Type | Description +--- | --- | --- +`cancel_url` | String! | The relative URL of the page that PayPal will redirect to when the buyer cancels the transaction in order to choose a different payment method. If the full URL to this page is `https://www.example.com/paypal/action/cancel.html`, the relative URL is `paypal/action/cancel.html` +`return_url` | String! | The relative URL of the final confirmation page that PayPal will redirect to upon payment success. If the full URL to this page is `https://www.example.com/paypal/action/return.html`, the relative URL is `paypal/action/return.html` \ No newline at end of file diff --git a/_includes/graphql/payment-methods/hosted-pro-workflow.md b/_includes/graphql/payment-methods/hosted-pro-workflow.md new file mode 100644 index 00000000000..2b2b77c5940 --- /dev/null +++ b/_includes/graphql/payment-methods/hosted-pro-workflow.md @@ -0,0 +1,21 @@ +1. The PWA client uses the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation to set the payment method. + +1. The mutation returns a `Cart` object. + +1. The client runs the [`placeOrder`]({{page.baseurl}}/graphql/reference/quote-place-order.html) mutation, which creates an order in Magento and begins the authorization process. + +1. Magento sends information about the cart and order to PayPal. + +1. PayPal's response includes a secure URL that the PWA client will use to connect to PayPal. + +1. The `placeOrder` mutation returns an order ID. The order has the status `payment pending`. + +1. The client runs the [`getHostedProUrl`]({{page.baseurl}}/graphql/queries/get-hosted-pro-url.html) query to retrieve the secure URL. + +1. Magento returns the secure URL in the `secure_form_url` attribute. + +1. The PWA client displays a payment form in an iframe rendered from the secure URL. When the customer completes the form, the client sends the payment information directly to the PayPal gateway, bypassing the Magento server. + +1. After PayPal processes the payment, the gateway runs a silent post request against the Magento server. As a result, Magento sets the order status to pending, and the order is ready to be invoiced. + +1. The PayPal gateway returns control of the customer's browser to the client. \ No newline at end of file diff --git a/common/images/graphql/paypal-hosted-pro.svg b/common/images/graphql/paypal-hosted-pro.svg new file mode 100644 index 00000000000..4f821f8306e --- /dev/null +++ b/common/images/graphql/paypal-hosted-pro.svg @@ -0,0 +1,2 @@ + +
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as pending.

[Not supported by viewer]
10
[Not supported by viewer]
8
[Not supported by viewer]

Magento returns the information needed to request an iframe from PayPal.

[Not supported by viewer]
7
[Not supported by viewer]

Request the token information.

[Not supported by viewer]
5
[Not supported by viewer]

PayPal returns the secure URL.

[Not supported by viewer]
4
[Not supported by viewer]

Magento requests a secure URL.

[Not supported by viewer]

Magento returns the order ID.

[Not supported by viewer]
6
[Not supported by viewer]

Place the order.

[Not supported by viewer]
3
[Not supported by viewer]
2
[Not supported by viewer]

Magento returns the Cart object.

[Not supported by viewer]

Client
(PWA)

[Not supported by viewer]

Magento

[Not supported by viewer]
1
[Not supported by viewer]

Set the payment method.

<p style="font-size: 13px">Set the payment method.</p>
9
[Not supported by viewer]

Display a payment form in an iframe. Customer clicks the PayPal button.

[Not supported by viewer]

PayPal

[Not supported by viewer] \ No newline at end of file diff --git a/guides/v2.3/graphql/payment-methods/hosted-pro.md b/guides/v2.3/graphql/payment-methods/hosted-pro.md new file mode 100644 index 00000000000..2de511d19d4 --- /dev/null +++ b/guides/v2.3/graphql/payment-methods/hosted-pro.md @@ -0,0 +1,64 @@ +--- +group: graphql +title: PayPal Website Payments Pro Hosted Solution payment method +--- + +PayPal's [Website Payments Pro Hosted Solution](https://developer.paypal.com/docs/classic/paypal-payments-pro/integration-guide/) allows merchants to accept credit cards, debit cards, and PayPal payments directly on their websites. The merchant must be based in the United Kingdom to create a new integration with this payment method. PayPal continues to support merchants with existing integrations outside the UK. + +## Website Payments Pro Hosted Solution workflow + +The following diagram shows the workflow for placing an order when Website Payments Pro Hosted Solution is the selected payment method. + +![PayPal Website Payments Pro Hosted Solution sequence diagram]({{site.baseurl}}/common/images/graphql/paypal-hosted-pro.svg) + +{% include graphql/payment-methods/hosted-pro-workflow.md %} + +## `setPaymentMethodOnCart` mutation + +When you set the payment method for a Website Payments Pro Hosted Solution, you must set the `code` attribute to `hosted_pro`. In addition, the payload must contain a `hosted_pro` object, which defines the following attributes: + +{% include graphql/payment-methods/hosted-pro-attributes.md %} + +## Example setPaymentMethodOnCart mutation + +The following example shows the `setPaymentMethodOnCart` mutation constructed for the Website Payments Pro Hosted Solution payment method. + +**Request** + +```graphql +mutation { + setPaymentMethodOnCart(input: { + cart_id: "H87OmEkvusP7ZPkd2634pQFxY4dKI3a4" + payment_method: { + code: "hosted_pro" + hosted_pro: { + cancel_url: "paypal/hostedpro/cancel" + return_url: "paypal/hostedpro/return" + } + } + }) + { + cart { + selected_payment_method { + code + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setPaymentMethodOnCart": { + "cart": { + "selected_payment_method": { + "code": "hosted_pro", + } + } + } + } +} +``` diff --git a/guides/v2.3/graphql/queries/get-hosted-pro-url.md b/guides/v2.3/graphql/queries/get-hosted-pro-url.md new file mode 100644 index 00000000000..83a2731e362 --- /dev/null +++ b/guides/v2.3/graphql/queries/get-hosted-pro-url.md @@ -0,0 +1,52 @@ +--- +group: graphql +title: getHostedProUrl query +--- + +The `getHostedProUrl` query is required to complete a transaction when the [PayPal Website Payments Pro Hosted Solution payment method]({{page.baseurl}}/graphql/payment-methods/hosted-pro.html) is selected. The query retrieves a PayPal-generated URL that the PWA client connects to, enabling the customer to enter their PayPal credentials and complete the transaction. Run this query after you [set the payment method]({{ page.baseurl}}/graphql/reference/quote-payment-method.html) and [place the order]({{ page.baseurl}}/graphql/reference/quote-place-order.html). + +## Syntax + +`getHostedProUrl(input: HostedProUrlInput!): HostedProUrl` + +## Example usage + +The following query returns the customer's wish list: + +**Request** + +```graphql +query { + getHostedProUrl(input: { cart_id: "mwqoyxgbibvgkr3udszfzomxpoj2gmj6" }) { + secure_form_url + } +} +``` + +**Response** + +```json +{ + "data": { + "getHostedProUrl": { + "secure_form_url": "https://securepayments.sandbox.paypal.com/webapps/HostedSoleSolutionApp/webflow/sparta/hostedSoleSolutionProcess?hosted_button_id=HSSS-iKGrv2XMlHcGGj8u.hlOHA2AeoQHcIQOvoqTEbvgBlKTLXcS8tAg0BRg1AklvfIhU5ip0g" + } + } +} +``` + +## Input attributes + +The `getHostedProUrl` query must contain the following attribute: + +Attribute | Data type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer’s cart + +## Output attributes + +The query returns the PayPal URL that enable the customer to sign in to PayPal and complete the transaction. + +Attribute | Data type | Description +--- | --- | --- +`secure_form_url` | String | Secure URL generated by PayPal From bfaa7ea3088dac0a65e56b9ba7db53ca522c26af Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 8 Aug 2019 14:26:25 -0500 Subject: [PATCH 2/3] review comments --- _includes/graphql/payment-methods/hosted-pro-workflow.md | 6 +++--- common/images/graphql/paypal-hosted-pro.svg | 2 +- guides/v2.3/graphql/payment-methods/hosted-pro.md | 7 ++++++- guides/v2.3/graphql/queries/get-hosted-pro-url.md | 2 +- 4 files changed, 11 insertions(+), 6 deletions(-) diff --git a/_includes/graphql/payment-methods/hosted-pro-workflow.md b/_includes/graphql/payment-methods/hosted-pro-workflow.md index 2b2b77c5940..e11e33f2b9a 100644 --- a/_includes/graphql/payment-methods/hosted-pro-workflow.md +++ b/_includes/graphql/payment-methods/hosted-pro-workflow.md @@ -4,9 +4,9 @@ 1. The client runs the [`placeOrder`]({{page.baseurl}}/graphql/reference/quote-place-order.html) mutation, which creates an order in Magento and begins the authorization process. -1. Magento sends information about the cart and order to PayPal. +1. Magento sends information about the cart and order to PayPal and requests a secure URL that the PWA client will later use to connect to PayPal. -1. PayPal's response includes a secure URL that the PWA client will use to connect to PayPal. +1. PayPal's response includes the secure URL. 1. The `placeOrder` mutation returns an order ID. The order has the status `payment pending`. @@ -16,6 +16,6 @@ 1. The PWA client displays a payment form in an iframe rendered from the secure URL. When the customer completes the form, the client sends the payment information directly to the PayPal gateway, bypassing the Magento server. -1. After PayPal processes the payment, the gateway runs a silent post request against the Magento server. As a result, Magento sets the order status to pending, and the order is ready to be invoiced. +1. After PayPal processes the payment, the gateway runs a silent post request against the Magento server. As a result, Magento sets the order status to processing, and the order is ready to be invoiced. 1. The PayPal gateway returns control of the customer's browser to the client. \ No newline at end of file diff --git a/common/images/graphql/paypal-hosted-pro.svg b/common/images/graphql/paypal-hosted-pro.svg index 4f821f8306e..63a12c2ca2d 100644 --- a/common/images/graphql/paypal-hosted-pro.svg +++ b/common/images/graphql/paypal-hosted-pro.svg @@ -1,2 +1,2 @@ -
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as pending.

[Not supported by viewer]
10
[Not supported by viewer]
8
[Not supported by viewer]

Magento returns the information needed to request an iframe from PayPal.

[Not supported by viewer]
7
[Not supported by viewer]

Request the token information.

[Not supported by viewer]
5
[Not supported by viewer]

PayPal returns the secure URL.

[Not supported by viewer]
4
[Not supported by viewer]

Magento requests a secure URL.

[Not supported by viewer]

Magento returns the order ID.

[Not supported by viewer]
6
[Not supported by viewer]

Place the order.

[Not supported by viewer]
3
[Not supported by viewer]
2
[Not supported by viewer]

Magento returns the Cart object.

[Not supported by viewer]

Client
(PWA)

[Not supported by viewer]

Magento

[Not supported by viewer]
1
[Not supported by viewer]

Set the payment method.

<p style="font-size: 13px">Set the payment method.</p>
9
[Not supported by viewer]

Display a payment form in an iframe. Customer clicks the PayPal button.

[Not supported by viewer]

PayPal

[Not supported by viewer] \ No newline at end of file +
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as processing.

[Not supported by viewer]
10
[Not supported by viewer]
8
[Not supported by viewer]

Magento returns the information needed to request an iframe from PayPal.

[Not supported by viewer]
7
[Not supported by viewer]

Request the token information.

[Not supported by viewer]
5
[Not supported by viewer]

PayPal returns the secure URL.

[Not supported by viewer]
4
[Not supported by viewer]

Magento requests a secure URL.

[Not supported by viewer]

Magento returns the order ID.

[Not supported by viewer]
6
[Not supported by viewer]

Place the order.

[Not supported by viewer]
3
[Not supported by viewer]
2
[Not supported by viewer]

Magento returns the Cart object.

[Not supported by viewer]

Client
(PWA)

[Not supported by viewer]

Magento

[Not supported by viewer]
1
[Not supported by viewer]

Set the payment method.

<p style="font-size: 13px">Set the payment method.</p>
9
[Not supported by viewer]

Display a payment form in an iframe. Customer clicks the PayPal button.

[Not supported by viewer]

PayPal

[Not supported by viewer] \ No newline at end of file diff --git a/guides/v2.3/graphql/payment-methods/hosted-pro.md b/guides/v2.3/graphql/payment-methods/hosted-pro.md index 2de511d19d4..e8f151b1206 100644 --- a/guides/v2.3/graphql/payment-methods/hosted-pro.md +++ b/guides/v2.3/graphql/payment-methods/hosted-pro.md @@ -3,7 +3,12 @@ group: graphql title: PayPal Website Payments Pro Hosted Solution payment method --- -PayPal's [Website Payments Pro Hosted Solution](https://developer.paypal.com/docs/classic/paypal-payments-pro/integration-guide/) allows merchants to accept credit cards, debit cards, and PayPal payments directly on their websites. The merchant must be based in the United Kingdom to create a new integration with this payment method. PayPal continues to support merchants with existing integrations outside the UK. +PayPal's [Website Payments Pro Hosted Solution](https://developer.paypal.com/docs/classic/paypal-payments-pro/integration-guide/) allows merchants to accept credit cards, debit cards, and PayPal payments directly on their websites. The merchant must be based in the United Kingdom to create a new integration with this payment method. PayPal continues to support merchants with existing integrations outside the UK. + +This payment method is applicable to Direct Payment and Express Checkout implementations of the Website Payments Pro Hosted Solution. + +PayPal's product name for this payment method varies from country to country. [PayPal Website Payments +Pro Hosted Solution Integration Guide](https://www.paypalobjects.com/webstatic/en_GB/developer/docs/pdf/hostedsolution_uk.pdf) provides more information. ## Website Payments Pro Hosted Solution workflow diff --git a/guides/v2.3/graphql/queries/get-hosted-pro-url.md b/guides/v2.3/graphql/queries/get-hosted-pro-url.md index 83a2731e362..61841e030c4 100644 --- a/guides/v2.3/graphql/queries/get-hosted-pro-url.md +++ b/guides/v2.3/graphql/queries/get-hosted-pro-url.md @@ -45,7 +45,7 @@ Attribute | Data type | Description ## Output attributes -The query returns the PayPal URL that enable the customer to sign in to PayPal and complete the transaction. +The query returns the PayPal URL that enables the customer to sign in to PayPal and complete the transaction. Attribute | Data type | Description --- | --- | --- From 21893548a90cad5f40cdc30b26ee21943854cc36 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Fri, 9 Aug 2019 14:52:50 -0500 Subject: [PATCH 3/3] architect comments --- .../payment-methods/hosted-pro-workflow.md | 16 ++++++++-------- common/images/graphql/paypal-hosted-pro.svg | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/_includes/graphql/payment-methods/hosted-pro-workflow.md b/_includes/graphql/payment-methods/hosted-pro-workflow.md index e11e33f2b9a..3000c964ce9 100644 --- a/_includes/graphql/payment-methods/hosted-pro-workflow.md +++ b/_includes/graphql/payment-methods/hosted-pro-workflow.md @@ -4,18 +4,18 @@ 1. The client runs the [`placeOrder`]({{page.baseurl}}/graphql/reference/quote-place-order.html) mutation, which creates an order in Magento and begins the authorization process. -1. Magento sends information about the cart and order to PayPal and requests a secure URL that the PWA client will later use to connect to PayPal. +2. Magento sends information about the order to PayPal and requests a secure URL that the PWA client will later use to connect to PayPal. -1. PayPal's response includes the secure URL. +3. PayPal's response includes the secure URL. -1. The `placeOrder` mutation returns an order ID. The order has the status `payment pending`. +4. The `placeOrder` mutation returns an order ID. The order has the status `payment pending`. -1. The client runs the [`getHostedProUrl`]({{page.baseurl}}/graphql/queries/get-hosted-pro-url.html) query to retrieve the secure URL. +5. The client runs the [`getHostedProUrl`]({{page.baseurl}}/graphql/queries/get-hosted-pro-url.html) query to retrieve the secure URL. -1. Magento returns the secure URL in the `secure_form_url` attribute. +6. Magento returns the secure URL in the `secure_form_url` attribute. -1. The PWA client displays a payment form in an iframe rendered from the secure URL. When the customer completes the form, the client sends the payment information directly to the PayPal gateway, bypassing the Magento server. +7. The PWA client displays a payment form in an iframe rendered from the secure URL. When the customer completes the form, the client sends the payment information directly to the PayPal gateway, bypassing the Magento server. -1. After PayPal processes the payment, the gateway runs a silent post request against the Magento server. As a result, Magento sets the order status to processing, and the order is ready to be invoiced. +8. After PayPal processes the payment, the gateway runs a silent post request against the Magento server. As a result, Magento sets the order status to processing, and the order is ready to be invoiced. -1. The PayPal gateway returns control of the customer's browser to the client. \ No newline at end of file +9. The PayPal gateway returns control of the customer's browser to the client. \ No newline at end of file diff --git a/common/images/graphql/paypal-hosted-pro.svg b/common/images/graphql/paypal-hosted-pro.svg index 63a12c2ca2d..9a0ecb70dc3 100644 --- a/common/images/graphql/paypal-hosted-pro.svg +++ b/common/images/graphql/paypal-hosted-pro.svg @@ -1,2 +1,2 @@ -
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as processing.

[Not supported by viewer]
10
[Not supported by viewer]
8
[Not supported by viewer]

Magento returns the information needed to request an iframe from PayPal.

[Not supported by viewer]
7
[Not supported by viewer]

Request the token information.

[Not supported by viewer]
5
[Not supported by viewer]

PayPal returns the secure URL.

[Not supported by viewer]
4
[Not supported by viewer]

Magento requests a secure URL.

[Not supported by viewer]

Magento returns the order ID.

[Not supported by viewer]
6
[Not supported by viewer]

Place the order.

[Not supported by viewer]
3
[Not supported by viewer]
2
[Not supported by viewer]

Magento returns the Cart object.

[Not supported by viewer]

Client
(PWA)

[Not supported by viewer]

Magento

[Not supported by viewer]
1
[Not supported by viewer]

Set the payment method.

<p style="font-size: 13px">Set the payment method.</p>
9
[Not supported by viewer]

Display a payment form in an iframe. Customer clicks the PayPal button.

[Not supported by viewer]

PayPal

[Not supported by viewer] \ No newline at end of file +
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as processing.

[Not supported by viewer]
10
[Not supported by viewer]
8
[Not supported by viewer]

Magento returns the information needed to request an iframe from PayPal.

[Not supported by viewer]
7
[Not supported by viewer]

Request the secure URL.

[Not supported by viewer]
5
[Not supported by viewer]

PayPal returns the secure URL.

[Not supported by viewer]
4
[Not supported by viewer]

Magento requests a secure URL.

[Not supported by viewer]

Magento returns the order ID.

[Not supported by viewer]
6
[Not supported by viewer]

Place the order.

[Not supported by viewer]
3
[Not supported by viewer]
2
[Not supported by viewer]

Magento returns the Cart object.

[Not supported by viewer]

Client
(PWA)

[Not supported by viewer]

Magento

[Not supported by viewer]
1
[Not supported by viewer]

Set the payment method.

<p style="font-size: 13px">Set the payment method.</p>
9
[Not supported by viewer]

Display a payment form in an iframe. Customer clicks the PayPal button.

[Not supported by viewer]

PayPal

[Not supported by viewer] \ No newline at end of file