Add documentation for Payflow Link payment processor (#4861)

* review draft

* Check in updated graphic

* another try at the graphic

* delete extraneous file

* Apply suggestions from code review

Co-Authored-By: Erik Marr <45772211+erikmarr@users.noreply.github.com>

* Apply suggestions from code review

Author: keharper

_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:

guides/v2.3/graphql/images/paypal-payflow-link.svg

@@ -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"
+        }
+      }
+    }
+  }
+}
+```

guides/v2.3/graphql/payment-methods/payflow-link.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": "<token-value>",
+            "secure_token_id": "<token-value-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 `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
+--- | --- | ---
+`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

guides/v2.3/graphql/reference/paypal-get-payflow-link-token.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.