Create topic for PayPal Express Checkout payment method

_data/toc/graphql.yml

@@ -105,9 +105,6 @@ pages:
             - label: Payflow Pro handlePayflowProResponse mutation
               url: /graphql/reference/paypal-handle-payflow-pro-response.html
 
-            - label: Paypal endpoint
-              url: /graphql/reference/paypal.html
-
             - label: Products endpoint
               url: /graphql/reference/products.html
               children:
@@ -198,6 +195,9 @@ pages:
 
         - label: Authorize.Net
           url: /graphql/payment-methods/authorize-net.html
+
+        - label: PayPal Express Checkout
+          url: /graphql/payment-methods/paypal-express-checkout.html
 
         - label: PayPal Payflow Link
           url: /graphql/payment-methods/payflow-link.html

_includes/graphql/payment-methods/paypal-express-checkout-attributes.md

@@ -0,0 +1,4 @@
+Attribute |  Data Type | Description
+--- | --- | ---
+`payer_id` | String! | The unique ID of the PayPal customer
+`token` | String! | The token returned by the `createPaypalExpressToken` mutation

_includes/graphql/payment-methods/paypal-express-checkout-workflow.md

@@ -0,0 +1,23 @@
+1. When the buyer clicks a PayPal button, the frontend executes the [`createPaypalExpressToken`]({{page.baseurl}}/graphql/mutations/create-paypal-express-token.html) mutation.
+
+1. Magento requests a secure token from PayPal. Magento gathers information in the specified cart and sends this information to PayPal as part of a request for a secure token.
+
+1. If the token request succeeds, PayPal returns a token. You must include this token in subsequent steps.
+
+1. Magento sends the token to the client. The `createPaypalExpressToken` response includes the token and the PayPal URLs to be used in the next step.
+
+1. Redirect the customer to PayPal for approval. Depending on your implementation, the customer is either redirected to the PayPal login screen, or the customer enters their credentials in-context.
+
+1. If the customer approves the payment, PayPal redirects the customer back to the payment confirmation page. The response includes the secure token and payer ID as GET parameters.
+
+1. Set the payment method. The frontend runs the [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation. The payload includes the PayPal token, the payer ID, and the cart ID. The cart may have been updated since the token was requested, as shipping costs, taxes, and other adjustments might have been applied to the cart. Magento submits the updated cart to PayPal.
+
+1. Magento returns a `Cart` object.
+
+1. Place the order with the [`placeOrder`]({{page.baseurl}}/graphql/reference/quote-place-order.html) mutation.
+
+1. Magento sends the secure token, payer ID, and final cart information to PayPal.
+
+1. PayPal captures the payment by transferring the funds from the customer account to the appropriate merchant account.
+
+1. Magento creates an order, ready for fulfillment.

guides/v2.3/graphql/mutations/create-paypal-express-token.md

@@ -0,0 +1,104 @@
+---
+group: graphql
+title: createPaypalExpressToken mutation
+---
+
+The `createPaypalExpressToken` mutation begins the authorization process for the following payment methods:
+
+* PayPal Express Checkout
+* PayPal Payflow Pro with Express Checkout
+* PayPal Payflow Link with Express Checkout
+
+The input includes the cart ID, the payment method code, and a set of URLs that PayPal uses to respond to the token request. If the request is successful, PayPal returns a token. The [`setPaymentMethodOnCart`]({{page.baseurl}}/graphql/reference/quote-payment-method.html) mutation uses this token later in the authorization process.
+
+## Syntax
+
+`mutation: {createPaypalExpressToken(input: PaypalExpressTokenInput!): {PaypalExpressToken}}`
+
+## Example usage
+
+**Request**
+
+```graphql
+mutation {
+    createPaypalExpressToken(
+        input: {
+            cart_id: "rMQdWEecBZr4SVWZwj2AF6y0dNCKQ8uH"
+            code: "paypal_express"
+            express_button: true
+            urls: {
+                return_url: "paypal/action/return.html"
+                cancel_url: "paypal/action/cancel.html"
+            }
+        }
+    )
+    {
+        token
+        paypal_urls{
+            start
+            edit
+        }
+    }
+}
+```
+
+**Response**
+
+```json
+{
+  "data": {
+    "createPaypalExpressToken": {
+      "token": "<PayPal_Token>"
+      "paypal_urls": {
+        "start": "https://www.sandbox.paypal.com/checkoutnow?token=<PayPal_Token>"
+        "edit": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&useraction=continue&token=<PayPal_Token>"
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+### PaypalExpressTokenInput {#PaypalExpressTokenInput}
+
+The `PaypalExpressTokenInput` object defines the attributes required to receive a payment token from PayPal.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`cart_id` | String! | The unique ID that identifies the customer's cart
+`code` | String! | Payment method code
+`express_button` | Boolean | Indicates whether the buyer selected the PayPal Express Checkout button. The default value is `false`
+`urls` | [`PaypalExpressUrlsInput!`](#PaypalExpressUrlsInput) | A set of relative URLs that PayPal will use in response to various actions during the authorization process.
+`use_paypal_credit` | Boolean | Indicates whether the buyer clicked the PayPal credit button. The default value is `false`
+
+### PaypalExpressUrlsInput {#PaypalExpressUrlsInput}
+
+The `PaypalExpressUrlsInput` object contains a set of relative URLs that PayPal will use in response to various actions during the authorization process. Magento prepends the base URL to this value to create a full URL. For example, if the full URL is `https://www.example.com/path/to/page.html`, the relative URL is `path/to/page.html`. Use this input for Express Checkout and Payments Standard payment methods.
+
+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`.
+`pending_url` | String | The relative URL of the page that PayPal will redirect to when the payment has been put on hold for additional review. This condition mostly applies to ACH transactions, and is not applicable to most PayPal solutions. If the full URL to this page is `https://www.example.com/paypal/action/success_pending.html`, the relative URL is `paypal/action/success_pending.html`.
+`return_url` | String! | The relative URL of the final confirmation page that PayPal will redirect to upon payment success. If the full URL is `https://www.example.com/paypal/action/success_review.html`, the relative URL is `paypal/action/success_review.html`.
+`success_url` | String | The relative URL of the order confirmation page that PayPal will redirect to when the payment is successful and additional confirmation is not needed. Not applicable to most PayPal solutions. If the full URL to this page is `https://www.example.com/paypal/action/success.html`, the relative URL is `paypal/action/success.html`.
+
+## Output attributes
+
+### PaypalExpressToken {#PaypalExpressToken}
+
+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
+--- | --- | ---
+`paypal_urls` | [PaypalExpressUrlList](#PaypalExpressUrlList) | A set of URLs that allow the buyer to authorize payment and adjust checkout details
+`token` | String | The token returned by PayPal
+
+### PaypalExpressUrlList {#PaypalExpressUrlList}
+
+The `PaypalExpressUrlList` object defines a set of URLs that allow the buyer to authorize payment and adjust checkout details.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`edit` | String | The PayPal URL that allows the buyer to edit their checkout details
+`start` | String | The URL to the PayPal login page

guides/v2.3/graphql/payment-methods/paypal-express-checkout.md

@@ -0,0 +1,84 @@
+---
+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 merchant can use PayPal Express Checkout as a standalone option, or combine it with one of these other PayPal payment 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.
+
+## PayPal Express Checkout workflow
+
+The following diagram shows the workflow for placing an order when PayPal Express Checkout is the selected 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 %}
+
+## Additional Payment information
+
+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:
+
+{% include graphql/payment-methods/paypal-express-checkout-attributes.md %}
+
+## Example setPaymentMethodOnCart mutation
+
+The following example shows the `setPaymentMethodOnCart` mutation constructed for the PayPal Express payment method.
+
+**Request**
+
+```graphql
+mutation {
+  setPaymentMethodOnCart(input: {
+    cart_id: "rMQdWEecBZr4SVWZwj2AF6y0dNCKQ8uH"
+    payment_method: {
+        code: "paypal_express"
+        additional_data: {
+            paypal_express: {
+                payer_id: "<PayPal_PayerID>"
+                token: "<PayPal_Token>"
+            }
+        }
+      }
+  }) {
+    cart {
+      selected_payment_method {
+        code
+        title
+      }
+    }
+  }
+}
+```
+
+**Response**
+
+```json
+{
+  "data": {
+    "setPaymentMethodOnCart": {
+      "cart": {
+        "selected_payment_method": {
+          "code": "paypal_express",
+          "title": "PayPal Express Checkout"
+        }
+      }
+    }
+  }
+}
+```
+
+## 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)