From 72f74dbb613d6f2ee4a20782e1c4492e3066cd90 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 27 Jun 2019 11:09:02 -0500 Subject: [PATCH 1/6] review draft --- _data/toc/graphql.yml | 8 ++ .../graphql/images/paypal-payflow-link.svg | 2 + .../graphql/payment-methods/payflow-link.md | 94 +++++++++++++++++++ .../paypal-create-payflow-pro-token.md | 67 +++++++++++++ .../paypal-get-payflow-link-token.md | 67 +++++++++++++ .../graphql/reference/quote-payment-method.md | 2 + 6 files changed, 240 insertions(+) create mode 100644 guides/v2.3/graphql/images/paypal-payflow-link.svg create mode 100644 guides/v2.3/graphql/payment-methods/payflow-link.md create mode 100644 guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md create mode 100644 guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml index c1621429e8e..0f6c75f081f 100644 --- a/_data/toc/graphql.yml +++ b/_data/toc/graphql.yml @@ -22,6 +22,11 @@ pages: - label: GraphQL Caching url: /graphql/caching.html + - label: Payment methods + children: + - label: PayPal Payflow Link + url: /graphql/payment-methods/payflow-link.html + - label: Development children: - label: Define the GraphQL schema for a module @@ -62,6 +67,9 @@ pages: - label: Paypal endpoint url: /graphql/reference/paypal.html + - label: Payflow getPayflowLinkToken query + url: /graphql/reference/paypal-get-payflow-link-token.html + - label: Products endpoint url: /graphql/reference/products.html children: diff --git a/guides/v2.3/graphql/images/paypal-payflow-link.svg b/guides/v2.3/graphql/images/paypal-payflow-link.svg new file mode 100644 index 00000000000..9d5c5681e35 --- /dev/null +++ b/guides/v2.3/graphql/images/paypal-payflow-link.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 paid.

[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 token information.

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

Magento requests a secure token.

[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 to payflow_link.

[Not supported by viewer]
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/payflow-link.md b/guides/v2.3/graphql/payment-methods/payflow-link.md new file mode 100644 index 00000000000..5d545a378a6 --- /dev/null +++ b/guides/v2.3/graphql/payment-methods/payflow-link.md @@ -0,0 +1,94 @@ +--- +group: graphql +title: Paypal Payflow Link payment method +--- + +PayPal [PayFlow Link](https://developer.paypal.com/docs/classic/payflow/integration-guide/) is available for merchants in the United States and Canada only. Customers are not required to have a personal PayPal account. Instead, customers enter their credit card information in a form that is hosted by PayPal. + +The Payflow gateway uses a secure token to send non-credit card transaction data to the Payflow server for storage in a way that cannot be intercepted and manipulated maliciously. This token secures the data for a one-time transaction and is valid for 30 minutes. When the AWS client runs the `placeOrder` mutation, Magento requests a secure token. The Payflow server returns the token as a string of up to 32 alphanumeric characters. + +## Payflow Link workflow + +The following diagram shows the workflow for placing an order when Payflow Link is the selected payment method. + +![PayPal Payflow Link sequence diagram]({{page.baseurl}}/graphql/images/paypal-payflow-link.svg) + +1. The PWA client uses the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation to set the payment method to `payflow_link`. + +2. The mutation returns a `Cart` object. + +3. 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. + +4. Magento requests a secure token from the Payflow Link gateway. + +5. The gateway response includes a secure token, a secure token ID, and the URL to use for requesting the Payflow form in step 9. + +6. The `placeOrder` mutation returns an order ID. Magento does not return secure token information. The order has the status `payment pending`. + +7. The client runs the [`getPayflowLinkToken`]({{page.baseurl}}/graphql/reference/paypal-get-payflow-link-token.html) mutation to retrieve the secure token information. + +8. Magento returns the token information. + +9. The client displays a payment form in an iframe rendered from the URL specified by the `paypal_url` from `getPayflowLinkToken` mutation response. When the customer completes the form, the client sends the payment information directly to the Payflow gateway, bypassing the Magento server. + +10. 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. + +11. The Payflow gateway returns control of the customer's browser to the client. + +## Additional Payment information + +You must set the following attributes when setting the payment method to `payflow_link`: + +Attribute | Data Type | Description +--- | --- | --- +`cancel_url` | String! | The URL PayPal will redirect back to upon payment cancellation +`error_url` | String! | The URL PayPal will redirect back to upon payment error +`return_url` | String! | The URL PayPal will redirect back to upon payment success + +## Example setPaymentMethodOnCart mutation + +The following example shows the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation constructed for the Payflow Link payment method. + +**Request** + +``` text +mutation { + setPaymentMethodOnCart(input: { + payment_method: { + code: "payflow_link" + additional_data: { + payflow_link: { + return_url: "https://www.example.com/payflow/test/return", + error_url: "https://www.example.com/payflow/test/error", + cancel_url: "https://www.example.com/payflow/test/cancel" + } + } + } + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG" + }) { + cart { + selected_payment_method { + code + title + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setPaymentMethodOnCart": { + "cart": { + "selected_payment_method": { + "code": "payflow_link", + "title": "PayPal Payflow Link" + } + } + } + } +} +``` diff --git a/guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md b/guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md new file mode 100644 index 00000000000..91a69e8b265 --- /dev/null +++ b/guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md @@ -0,0 +1,67 @@ +--- +group: graphql +title: getPayflowLinkToken query +--- + +The `getPayflowLinkToken` query retrieves PayPal payment credentials for a PayPal Payflow transaction. You must 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). + +See [Paypal Payflow Link payment method]({{page.baseurl}}/graphql/payment-methods/payflow-link.html) for detailed information about the workflow of PayPal Payflow transactions. + +## Syntax + +`getPayflowLinkToken(input: PayflowLinkTokenInput): PayflowLinkToken` + +## Example + +The following example requests a token in a Payflow Link transaction. + +**Request** + +```text +{ + getPayflowLinkToken(input: {cart_id: "123"}) { + secure_token + secure_token_id + mode + paypal_url + } +} +``` + +**Response** + +```json +{ + "data": { + "getPayflowLinkToken": { + "secure_token": "", + "secure_token_id": "", + "mode": "TEST", + "paypal_url": "https://pilot-payflowlink.paypal.com" + } + } +} +``` + +## Input attributes + +### PayflowLinkTokenInput {#PayflowLinkTokenInput} + +The `PayflowLinkTokenInput` object defines the attributes required to receive a Payflow Link token from PayPal. + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart + +## Output attributes + +### PayflowLinkToken + +The `PaypalExpressToken` object contains a token returned by PayPal and a set of URLs that allow the buyer to authorize payment and adjust checkout details. + +Attribute | Data Type | Description +--- | --- | --- +`mode` | `PayflowLinkMode` | The mode for the Payflow Link payment. Must be `LIVE` (actual transaction) or `TEST` (sandbox transaction) +`paypal_url` | String | The PayPal URL used for requesting a Payflow form +`secure_token` | String | Secure token generated by PayPal +`secure_token_id` | String | Secure token ID generated by PayPal diff --git a/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md b/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md new file mode 100644 index 00000000000..f1d3997185e --- /dev/null +++ b/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md @@ -0,0 +1,67 @@ +--- +group: graphql +title: getPayflowLinkToken query +--- + +The `getPayflowLinkToken` query retrieves PayPal payment credentials for a PayPal Payflow transaction. You must 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). + +See [Paypal Payflow Link payment method]({{page.baseurl}}/graphql/payment-methods/payflow-link.html) for detailed information about the workflow of PayPal Payflow Link transactions. + +## Syntax + +`getPayflowLinkToken(input: PayflowLinkTokenInput): PayflowLinkToken` + +## Example + +The following example requests a token in a Payflow Link transaction. + +**Request** + +```text +{ + getPayflowLinkToken(input: {cart_id: "123"}) { + secure_token + secure_token_id + mode + paypal_url + } +} +``` + +**Response** + +```json +{ + "data": { + "getPayflowLinkToken": { + "secure_token": "", + "secure_token_id": "", + "mode": "TEST", + "paypal_url": "https://pilot-payflowlink.paypal.com" + } + } +} +``` + +## Input attributes + +### PayflowLinkTokenInput {#PayflowLinkTokenInput} + +The `PayflowLinkTokenInput` object defines the attributes required to receive a Payflow Link token from PayPal. + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart + +## Output attributes + +### PayflowLinkToken + +The `PaypalExpressToken` object contains a token returned by PayPal and a set of URLs that allow the buyer to authorize payment and adjust checkout details. + +Attribute | Data Type | Description +--- | --- | --- +`mode` | `PayflowLinkMode` | The mode for the Payflow Link payment. Must be `LIVE` (actual transaction) or `TEST` (sandbox transaction) +`paypal_url` | String | The PayPal URL used for requesting a Payflow form +`secure_token` | String | Secure token generated by PayPal +`secure_token_id` | String | Secure token ID generated by PayPal diff --git a/guides/v2.3/graphql/reference/quote-payment-method.md b/guides/v2.3/graphql/reference/quote-payment-method.md index 87b14815a8f..d77e71ab3c3 100644 --- a/guides/v2.3/graphql/reference/quote-payment-method.md +++ b/guides/v2.3/graphql/reference/quote-payment-method.md @@ -14,6 +14,8 @@ Credit Card (Authorize.Net) | `authorizenet_acceptjs` No Payment Information Required | `free` [PayPal Express Checkout]({{ page.baseurl}}/graphql/reference/paypal.html) | `paypal_express` [PayPal Express Checkout Payflow Edition]({{ page.baseurl}}/graphql/reference/paypal.html) | `payflow_express` +PayPal Payflow Pro | `payflowpro` +PayPal Payflow Link | `payflow_link` Purchase Order | `purchaseorder` Apply the `setPaymentMethodOnCart` mutation after setting the shipping address, shipping method, and after applying any discounts to the cart. From 427fd913c9b1ede6662c31e1140e4c7b7a0f3ea2 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 27 Jun 2019 12:35:08 -0500 Subject: [PATCH 2/6] Check in updated graphic --- guides/v2.3/graphql/images/paypal-payflow-link.svg | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guides/v2.3/graphql/images/paypal-payflow-link.svg b/guides/v2.3/graphql/images/paypal-payflow-link.svg index 9d5c5681e35..ee4a3cdd297 100644 --- a/guides/v2.3/graphql/images/paypal-payflow-link.svg +++ b/guides/v2.3/graphql/images/paypal-payflow-link.svg @@ -1,2 +1 @@ - -
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as paid.

[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 token information.

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

Magento requests a secure token.

[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 to payflow_link.

[Not supported by viewer]
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 paid.

[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 token information.

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

Magento requests a secure token.

[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 to payflow_link.

[Not supported by viewer]
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 From ebb0c0ab18bdb5a6601cbc004ff0c5db96614a28 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 27 Jun 2019 12:57:19 -0500 Subject: [PATCH 3/6] another try at the graphic --- guides/v2.3/graphql/images/paypal-payflow-link.svg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/guides/v2.3/graphql/images/paypal-payflow-link.svg b/guides/v2.3/graphql/images/paypal-payflow-link.svg index ee4a3cdd297..22eb4be611d 100644 --- a/guides/v2.3/graphql/images/paypal-payflow-link.svg +++ b/guides/v2.3/graphql/images/paypal-payflow-link.svg @@ -1 +1,2 @@ -
11
[Not supported by viewer]

PayPal returns control to the browser.

[Not supported by viewer]

PayPal updates the order as paid.

[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 token information.

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

Magento requests a secure token.

[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 to payflow_link.

[Not supported by viewer]
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 paid.

[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 token information.

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

Magento requests a secure token.

[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 to payflow_link.

[Not supported by viewer]
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 From b92c9c25913a6ab252c2395124254084cf811726 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 27 Jun 2019 16:05:40 -0500 Subject: [PATCH 4/6] delete extraneous file --- .../paypal-create-payflow-pro-token.md | 67 ------------------- 1 file changed, 67 deletions(-) delete mode 100644 guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md diff --git a/guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md b/guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md deleted file mode 100644 index 91a69e8b265..00000000000 --- a/guides/v2.3/graphql/reference/paypal-create-payflow-pro-token.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -group: graphql -title: getPayflowLinkToken query ---- - -The `getPayflowLinkToken` query retrieves PayPal payment credentials for a PayPal Payflow transaction. You must 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). - -See [Paypal Payflow Link payment method]({{page.baseurl}}/graphql/payment-methods/payflow-link.html) for detailed information about the workflow of PayPal Payflow transactions. - -## Syntax - -`getPayflowLinkToken(input: PayflowLinkTokenInput): PayflowLinkToken` - -## Example - -The following example requests a token in a Payflow Link transaction. - -**Request** - -```text -{ - getPayflowLinkToken(input: {cart_id: "123"}) { - secure_token - secure_token_id - mode - paypal_url - } -} -``` - -**Response** - -```json -{ - "data": { - "getPayflowLinkToken": { - "secure_token": "", - "secure_token_id": "", - "mode": "TEST", - "paypal_url": "https://pilot-payflowlink.paypal.com" - } - } -} -``` - -## Input attributes - -### PayflowLinkTokenInput {#PayflowLinkTokenInput} - -The `PayflowLinkTokenInput` object defines the attributes required to receive a Payflow Link token from PayPal. - -Attribute | Data Type | Description ---- | --- | --- -`cart_id` | String! | The unique ID that identifies the customer's cart - -## Output attributes - -### PayflowLinkToken - -The `PaypalExpressToken` object contains a token returned by PayPal and a set of URLs that allow the buyer to authorize payment and adjust checkout details. - -Attribute | Data Type | Description ---- | --- | --- -`mode` | `PayflowLinkMode` | The mode for the Payflow Link payment. Must be `LIVE` (actual transaction) or `TEST` (sandbox transaction) -`paypal_url` | String | The PayPal URL used for requesting a Payflow form -`secure_token` | String | Secure token generated by PayPal -`secure_token_id` | String | Secure token ID generated by PayPal From 357a25ad0c4e8ecac776a7777ab6faa0ec62044b Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 27 Jun 2019 16:09:25 -0500 Subject: [PATCH 5/6] Apply suggestions from code review Co-Authored-By: Erik Marr <45772211+erikmarr@users.noreply.github.com> --- .../v2.3/graphql/reference/paypal-get-payflow-link-token.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md b/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md index f1d3997185e..52a4167df48 100644 --- a/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md +++ b/guides/v2.3/graphql/reference/paypal-get-payflow-link-token.md @@ -47,7 +47,7 @@ The following example requests a token in a Payflow Link transaction. ### PayflowLinkTokenInput {#PayflowLinkTokenInput} -The `PayflowLinkTokenInput` object defines the attributes required to receive a Payflow Link token from PayPal. +The `PayflowLinkTokenInput` object defines the attributes required to receive a Payflow Link token from PayPal. Attribute | Data Type | Description --- | --- | --- @@ -57,7 +57,7 @@ Attribute | Data Type | Description ### PayflowLinkToken -The `PaypalExpressToken` object contains a token returned by PayPal and a set of URLs that allow the buyer to authorize payment and adjust checkout details. +The `PayflowLinkToken` object contains a token returned by PayPal and a set of URLs that allow the buyer to authorize payment and adjust checkout details. Attribute | Data Type | Description --- | --- | --- From 575bd0cd6df1d73fd5f3269dd8d99c035a01886e Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Thu, 27 Jun 2019 16:12:16 -0500 Subject: [PATCH 6/6] Apply suggestions from code review --- guides/v2.3/graphql/payment-methods/payflow-link.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/v2.3/graphql/payment-methods/payflow-link.md b/guides/v2.3/graphql/payment-methods/payflow-link.md index 5d545a378a6..1894c1f9f6d 100644 --- a/guides/v2.3/graphql/payment-methods/payflow-link.md +++ b/guides/v2.3/graphql/payment-methods/payflow-link.md @@ -1,6 +1,6 @@ --- group: graphql -title: Paypal Payflow Link payment method +title: PayPal Payflow Link payment method --- PayPal [PayFlow Link](https://developer.paypal.com/docs/classic/payflow/integration-guide/) is available for merchants in the United States and Canada only. Customers are not required to have a personal PayPal account. Instead, customers enter their credit card information in a form that is hosted by PayPal.