GraphQL: Add payflow_express and misc payment methods (#5158)

keharper · web-flow · commit 87777c75430c · 2019-08-10T10:29:50.000-05:00
* checkpoint

* small fixes

* review comments

* remove additional_information from EC

* remove additional_information from all methods

* final adjustments

* link errors
diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml
@@ -201,6 +201,9 @@ pages:
 
         - label: PayPal Express Checkout
           url: /graphql/payment-methods/paypal-express-checkout.html
+
+        - label: Express Checkout for other PayPal solutions
+          url: /graphql/payment-methods/payflow-express.html
           
         - label: PayPal Payflow Link
           url: /graphql/payment-methods/payflow-link.html
diff --git a/_includes/graphql/payment-methods/payflow-link-workflow.md b/_includes/graphql/payment-methods/payflow-link-workflow.md
@@ -16,6 +16,6 @@
 
 1. The client displays a payment form in an iframe rendered from the URL specified by the `paypal_url` from the `getPayflowLinkToken` mutation response. 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.
+1. The PayPal gateway returns control of the customer's browser to the client.
diff --git a/guides/v2.3/graphql/payment-methods/authorize-net.md b/guides/v2.3/graphql/payment-methods/authorize-net.md
@@ -30,32 +30,30 @@ The client's browser then posts the nonce to the Magento server along with all t
 
 ## Additional payment information
 
-When you set the payment method to `authorizenet_acceptjs` in the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation, the `additional_data` object must contain an `authorizenet_acceptjs` object.
+When you set the payment method to `authorizenet_acceptjs` in the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation, the payload must contain an `authorizenet_acceptjs` object.
 
 Attribute |  Data Type | Description
 --- | --- | ---
 `cc_last_4` | Int! | The last four digits of the credit or debit card
 `opaque_data_descriptor` | String! | Authorize.Net's description of the transaction request
 `opaque_data_value` | String! | The nonce returned by Authorize.Net
 
-## Example setPaymentMethodOnCart mutation
+### Example usage
 
 The following example assigns the `authorizenet_acceptjs` payment method to the specified cart.
 
 **Request**
 
-```text
+```graphql
 mutation {
   setPaymentMethodOnCart(input: {
     cart_id: "lvdqOLzryManseE2artECZuPClxFgG1o"
     payment_method: {
       code: "authorizenet_acceptjs"
-      additional_data: {
-        authorizenet_acceptjs: {
-          cc_last_4: 1111
-          opaque_data_descriptor: "COMMON.ACCEPT.INAPP.PAYMENT"
-          opaque_data_value: "<nonce_value>"
-          }
+      authorizenet_acceptjs: {
+        cc_last_4: 1111
+        opaque_data_descriptor: "COMMON.ACCEPT.INAPP.PAYMENT"
+        opaque_data_value: "<nonce_value>"
         }
       }
   }) {
diff --git a/guides/v2.3/graphql/payment-methods/hosted-pro.md b/guides/v2.3/graphql/payment-methods/hosted-pro.md
@@ -24,7 +24,7 @@ When you set the payment method for a Website Payments Pro Hosted Solution, you
 
 {% include graphql/payment-methods/hosted-pro-attributes.md %}
 
-## Example setPaymentMethodOnCart mutation
+### Example usage
 
 The following example shows the `setPaymentMethodOnCart` mutation constructed for the Website Payments Pro Hosted Solution payment method.
 
diff --git a/guides/v2.3/graphql/payment-methods/payflow-express.md b/guides/v2.3/graphql/payment-methods/payflow-express.md
@@ -0,0 +1,80 @@
+---
+group: graphql
+title: Express Checkout for other PayPal solutions
+---
+
+Set the payment method code to `payflow_express` to process Express Checkout transactions when the payment method is set to any of the following:
+
+-  Payflow Link
+-  Payflow Pro
+-  Payments Advanced
+-  Payments Pro
+
+PayPal Express Checkout enables customers to pay by credit card or from the security of their personal PayPal accounts. During checkout, the customer is redirected to the secure PayPal site to complete the payment information. The customer is then returned to the store to complete the remainder of the checkout process.
+
+From a GraphQL integration standpoint, this payment method is identical to the [PayPal Express Checkout]({{page.baseurl}}/graphql/payment-methods/payflow-link.html) payment method, with the exception that in the `setPaymentMethodOnCart` mutation, the payment method `code` is set to `payflow_express`.
+
+## PayPal Express Checkout workflow
+
+The following diagram shows the workflow for placing an order when `payflow_express` is the specified payment method.
+
+![PayPal Express Checkout sequence diagram]({{site.baseurl}}/common/images/graphql/paypal-express-checkout.svg)
+
+The following steps describe the flow of calls required to complete a typical PayPal Express Checkout authorization. A successful purchase requires that you send three mutations to PayPal, and the buyer must approve the purchase by logging in to PayPal.
+
+{% include graphql/payment-methods/paypal-express-checkout-workflow.md %}
+
+## `setPaymentMethodOnCart` mutation
+
+When you set the payment method to one of the Express Checkout payment solutions discussed in this topic, you must set the `code` attribute to `payflow_express`. In addition, the payload must contain a `payflow_express` object, which defines the following attributes:
+
+{% include graphql/payment-methods/paypal-express-checkout-attributes.md %}
+
+### Example usage
+
+The following example shows the `setPaymentMethodOnCart` mutation with the `code` set to `payflow_express`.
+
+**Request**
+
+```graphql
+mutation {
+  setPaymentMethodOnCart(input: {
+    cart_id: "rMQdWEecBZr4SVWZwj2AF6y0dNCKQ8uH"
+    payment_method: {
+        code: "payflow_express"
+        payflow_express: {
+          payer_id: "<PayPal_PayerID>"
+          token: "<PayPal_Token>"
+        }
+      }
+  }) {
+    cart {
+      selected_payment_method {
+        code
+      }
+    }
+  }
+}
+```
+
+**Response**
+
+```json
+{
+  "data": {
+    "setPaymentMethodOnCart": {
+      "cart": {
+        "selected_payment_method": {
+          "code": "payflow_express",
+        }
+      }
+    }
+  }
+}
+```
+
+## Related topics
+
+- [`createPaypalExpressToken` mutation]({{page.baseurl}}/graphql/mutations/create-paypal-express-token.html)
+- [`placeOrder` mutation]({{page.baseurl}}/graphql/reference/quote-place-order.html)
+- [`setPaymentMethodOnCart` mutation]({{page.baseurl}}/graphql/reference/quote-payment-method.html)
diff --git a/guides/v2.3/graphql/payment-methods/payflow-link.md b/guides/v2.3/graphql/payment-methods/payflow-link.md
@@ -21,13 +21,13 @@ When you set the payment method to Payflow Link in the [`setPaymentMethodOnCart`
 
 {% include graphql/payment-methods/payflow-link-attributes.md %}
 
-## Example setPaymentMethodOnCart mutation
+### Example usage
 
 The following example shows the `setPaymentMethodOnCart` mutation constructed for the Payflow Link payment method.
 
 **Request**
 
-```text
+```graphql
 mutation {
     setPaymentMethodOnCart(input: {
         payment_method: {
diff --git a/guides/v2.3/graphql/payment-methods/payflow-pro.md b/guides/v2.3/graphql/payment-methods/payflow-pro.md
@@ -5,6 +5,12 @@ title: PayPal Payflow Pro payment method
 
 Payflow Pro is a payment gateway that processes debit and credit card payments. It is available for customers of the United States, Canada, Australia, and New Zealand.
 
+Other PayPal solutions have the same GraphQL workflow as Payflow Pro. The information in this topic also applies to the following PayPal solution:
+
+-  Payments Pro
+
+If Payflow Pro has been configured to implement Express Checkout, use the [PayPal Express Checkout for Payflow payment method]({{page.baseurl}}/graphql/payment-methods/payflow-express.html) instead.
+
 ## Payflow Pro workflow
 
 The following diagram shows the workflow for placing an order when Payflow Pro is the selected payment method.
@@ -19,13 +25,13 @@ When you set the payment method to Payflow Pro in the [`setPaymentMethodOnCart`]
 
 {% include graphql/payment-methods/payflow-pro-attributes.md %}
 
-## Example setPaymentMethodOnCart mutation
+### Example usage
 
 The following example shows the `setPaymentMethodOnCart` mutation constructed for the Payflow Pro payment method.
 
 **Request**
 
-```text
+```graphql
 mutation {
   setPaymentMethodOnCart(input: {
     cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG"
diff --git a/guides/v2.3/graphql/payment-methods/payments-advanced.md b/guides/v2.3/graphql/payment-methods/payments-advanced.md
@@ -3,7 +3,9 @@ group: graphql
 title: PayPal Payments Advanced payment method
 ---
 
-The PayPal Payments Advanced payment solution allows merchants to enable their online stores to collect payments directly via credit card, PayPal Express Checkout, or PayPal's PayPal Credit service. From a GraphQL integration standpoint, PayPal Payments Advanced payment method is identical to the PayPal [Payflow Link]({{page.baseurl}}/graphql/payment-methods/payflow-link.html) payment method, with the exception of the payment method `code`. The PayPal [Payments Advanced documentation](https://developer.paypal.com/docs/classic/products/paypal-payments-advanced/) describes other ways in which the payment methods differ.
+The PayPal Payments Advanced payment solution allows merchants to enable their online stores to collect payments directly via credit card or from the PayPal Credit service. If Payments Advanced has been configured to implement Express Checkout, use the [PayPal Express Checkout for Payflow payment method]({{page.baseurl}}/graphql/payment-methods/payflow-express.html) instead.
+
+From a GraphQL integration standpoint, PayPal Payments Advanced payment method is identical to the PayPal [Payflow Link]({{page.baseurl}}/graphql/payment-methods/payflow-link.html) payment method, with the exception of the payment method `code`. The PayPal [Payments Advanced documentation](https://developer.paypal.com/docs/classic/products/paypal-payments-advanced/) describes other ways in which the payment methods differ.
 
 PayPal Payments Advanced is available in the US and Canada only.
 
@@ -17,36 +19,36 @@ The following diagram shows the workflow for placing an order when Payments Adva
 
 ## Additional Payment information
 
-When you set the payment method code to `payflow_advanced` in the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation, the `additional_data` object must contain a `payflow_link` object, which defines the following attributes:
+## `setPaymentMethodOnCart` mutation
+
+When you set the payment method to PayPal Payments Advanced, you must set the `code` attribute to `payflow_advanced`. In addition, the payload must contain a `payflow_link` object, which defines the following attributes:
 
 {% include graphql/payment-methods/payflow-link-attributes.md %}
 
-## Example setPaymentMethodOnCart mutation
+### Example usage
 
 The following example shows the `setPaymentMethodOnCart` mutation constructed for the Payments Advanced payment method.
 
 **Request**
 
-```text
+```graphql
 mutation {
-    setPaymentMethodOnCart(input: {
-        payment_method: {
-            code: "payflow_advanced"
-            additional_data: {
-                payflow_link: {
-                  return_url: "paypal/action/return.html"
-                  error_url: "paypal/action/error.html"
-                  cancel_url: "paypal/action/cancel.html"
-                }
-            }
+  setPaymentMethodOnCart(input: {
+    payment_method: {
+      code: "payflow_advanced"
+      payflow_link: {
+        return_url: "paypal/action/return.html"
+        error_url: "paypal/action/error.html"
+        cancel_url: "paypal/action/cancel.html"
         }
-        cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG"
+      }
+    cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG"
     }) {
         cart {
-            selected_payment_method {
-                code
-                title
-            }
+          selected_payment_method {
+            code
+            title
+          }
         }
     }
 }
diff --git a/guides/v2.3/graphql/payment-methods/paypal-express-checkout.md b/guides/v2.3/graphql/payment-methods/paypal-express-checkout.md
@@ -3,16 +3,12 @@ group: graphql
 title: PayPal Express Checkout payment method
 ---
 
-The PayPal Express Checkout payment method enables customers to pay by credit card or from the security of their personal PayPal accounts. During checkout, the customer is redirected to the secure PayPal site to complete the payment information. The customer is then returned to your store to complete the remainder of the checkout process.
+The PayPal Express Checkout payment method enables customers to pay by credit card or from the security of their personal PayPal accounts. During checkout, the customer is redirected to the secure PayPal site to complete the payment information. The customer is then returned to the store to complete the remainder of the checkout process.
 
-The merchant can use PayPal Express Checkout as a standalone option, or combine it with one of these other PayPal payment solutions:
+Some alternate PayPal solutions have the same GraphQL workflow when Express Checkout is enabled. The information in this topic also applies to the following PayPal solutions:
 
-- PayPal Payflow Link
-- PayPal Payment Standard
-- Website Payments Standard (Australia only)
-- Website Payments Standard (United Kingdom only)
-
-When these other payment solutions are combined with PayPal Express Checkout, they use the same workflow as PayPal Express Checkout. From the GraphQL perspective, the only difference is the payment method `code` specified in the `setPaymentMethodOnCart` mutation.
+-  Payments Standard
+-  Website Payments Standard
 
 ## PayPal Express Checkout workflow
 
@@ -24,13 +20,13 @@ The following steps describe the flow of calls required to complete a typical Pa
 
 {% include graphql/payment-methods/paypal-express-checkout-workflow.md %}
 
-## Additional Payment information
+## `setPaymentMethodOnCart` mutation
 
-When you set the payment method code to `paypal_express` in the `setPaymentMethodOnCart` mutation, you must also specify attributes specific to this payment method in `additional_data` object. These attributes are defined in the  `paypal_express` object:
+When you set the payment method to Express Checkout, you must set the `code` attribute to `paypal_express`. In addition, the payload must contain a `paypal_express` object, which defines the following attributes:
 
 {% include graphql/payment-methods/paypal-express-checkout-attributes.md %}
 
-## Example setPaymentMethodOnCart mutation
+### Example usage
 
 The following example shows the `setPaymentMethodOnCart` mutation constructed for the PayPal Express payment method.
 
@@ -41,14 +37,12 @@ mutation {
   setPaymentMethodOnCart(input: {
     cart_id: "rMQdWEecBZr4SVWZwj2AF6y0dNCKQ8uH"
     payment_method: {
-        code: "paypal_express"
-        additional_data: {
-            paypal_express: {
-                payer_id: "<PayPal_PayerID>"
-                token: "<PayPal_Token>"
-            }
-        }
+      code: "paypal_express"
+      paypal_express: {
+        payer_id: "<PayPal_PayerID>"
+        token: "<PayPal_Token>"
       }
+    }
   }) {
     cart {
       selected_payment_method {
