PAY-5702: Adds docs for the updated vault feature in Payment Services

src/pages/graphql/schema/checkout/index.md

@@ -6,7 +6,7 @@ title: Checkout
 
 The checkout schema helps complete the customer checkout process by managing and retrieving payment tokens and checkout agreements.
 
-The checkout workflow differs for each online payment time. See the following topics for more information.
+The checkout workflow differs for each online payment type. See the following topics for more information.
 
 *  [Braintree](../../payment-methods/braintree.md)
 *  [Braintree vault](../../payment-methods/braintree-vault.md)

src/pages/graphql/schema/checkout/mutations/create-payment-order.md

@@ -75,23 +75,23 @@ The `CreatePaymentOrderinput` object contains the following input attributes:
 
 Attribute |  Data Type | Description
 --- | --- | ---
-`cartId` | String! | The unique ID of the cart
+`cartId` | String! | The unique ID of the cart.
 `location` | PaymentLocation! | The origin location for that payment request. The possible values are
-PRODUCT_DETAIL, MINICART, CART, CHECKOUT, ADMIN
-`methodCode` | String! | The code for the selected payment method
-`paymentSource` | String! | The payment source for the payment method. The possible values are credit card (`cc`), PayPal (`paypal`), and Apple Pay (`applepay`)
-`vaultIntent` | Boolean | Indicates whether the payment information should be vaulted. This attribute is only applicable to the `hosted_fields` payment method. The default value is `false`
+`PRODUCT_DETAIL`, `MINICART`, `CART`, `CHECKOUT`, `ADMIN`.
+`methodCode` | String! | The code for the selected payment method.
+`paymentSource` | String! | The payment source for the payment method. The possible values are credit card (`cc`), PayPal (`paypal`), and Apple Pay (`applepay`).
+`vaultIntent` | Boolean | Indicates whether the payment information should be vaulted. This attribute is only applicable to the `hosted_fields` payment method. The default value is `false`.
 
 ## Output attributes
 
 The `CreatePaymentOrderOutput` object contains the payment order details that are needed to fulfill a payment.
 
 Attribute |  Data Type | Description
 --- | --- | ---
-`id` | String | The unique order ID generated by PayPal
-`mp_order_id` | String | The unique order ID generated in Commerce if Payment Services is enabled after PayPal returns the `id`
-`status` | String | The status of the payment order. See [order status](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/order-management/orders/order-status.html) for more information
-`amount` | Float | The amount of the payment order
-`currency_code` | String | The currency code of the payment order
+`id` | String | The unique order ID generated by PayPal.
+`mp_order_id` | String | The unique order ID generated in Commerce if Payment Services is enabled after PayPal returns the `id`.
+`status` | String | The status of the payment order. See [order status](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/order-management/orders/order-status.html) for more information.
+`amount` | Float | The amount of the payment order.
+`currency_code` | String | The currency code of the payment order.
 
 See [PayPal currency codes](https://developer.paypal.com/reference/currency-codes/) documentation for more information.

src/pages/graphql/schema/checkout/queries/get-payment-config.md

@@ -10,7 +10,7 @@ This query is available only if you have installed [Payment Services for Adobe C
 
 The `getPaymentConfig` query returns the payment configuration details from locations in the storefront and Admin where the payment method can be set.
 
-The query can return details about the following supported payment methods in [Payment Services](https://experienceleague.adobe.com/docs/commerce-merchant-services/payment-services/payments-checkout/payments-options.html): :
+The query can return details about the following supported payment methods in [Payment Services](https://experienceleague.adobe.com/docs/commerce-merchant-services/payment-services/payments-checkout/payments-options.html):
 
 * Apple Pay
 * Google Pay
@@ -262,10 +262,10 @@ The `PaymentConfigOutput` contains details about each configured payment method:
 
 Attribute |  Data Type | Description
 --- | --- | ---
-`ApplePayConfig` | String! | Apple Pay payment method configuration
-`GooglePayConfig` | String! | Google Pay payment method configuration
-`HostedFieldsConfig` | String! | PayPal Hosted fields payment method configuration
-`SmartButtonsConfig` | String! | PayPal Smart Buttons payment method configuration
+`ApplePayConfig` | String! | Apple Pay payment method configuration.
+`GooglePayConfig` | String! | Google Pay payment method configuration.
+`HostedFieldsConfig` | String! | PayPal Hosted fields payment method configuration.
+`SmartButtonsConfig` | String! | PayPal Smart Buttons payment method configuration.
 
 Each of these output attributes implements the `PaymentConfigItem` interface.
 
@@ -275,7 +275,7 @@ The `PaymentConfigItem` interface contains the fields that are common to all the
 
 Attribute |  Data Type | Description
 --- | --- | ---
-`code` | String | The payment method code as defined in the payment gateway
+`code` | String | The payment method code as defined in the payment gateway.
 `is_visible` | Boolean | Indicates whether the payment method is shown.
 `payment_intent` | String | Defines the payment intent. The possible values are `Authorize` or `Capture`.
 `sdk_params` | SDKParams | PayPal parameters required to load the PayPal JavaScript SDK.
@@ -297,11 +297,11 @@ The `ApplePayConfig` payment method configuration has a `button_styles` object c
 
 Attribute | Data Type | Description
 --- | --- | ---
-`color` | String | The button color
-`height` | Int | The button height in pixels
-`label` | String | The button label
-`layout` | String | The button layout
-`shape` | String | The button shape
+`color` | String | The button color.
+`height` | Int | The button height in pixels.
+`label` | String | The button label.
+`layout` | String | The button layout.
+`shape` | String | The button shape.
 `tagline` | Boolean | Indicates whether the tagline is displayed.
 `use_default_height` | Boolean | Defines if button uses default height. If the value is `False`, the value of `height` is used.
 
@@ -364,11 +364,11 @@ The `SmartButtonsConfig` payment method configuration has a `ButtonStyles` objec
 
 Attribute | Data Type | Description
 --- | --- | ---
-`color` | String | The button color
-`height` | Int | The button height in pixels
-`label` | String | The button label
-`layout` | String | The button layout
-`shape` | String | The button shape
+`color` | String | The button color.
+`height` | Int | The button height in pixels.
+`label` | String | The button label.
+`layout` | String | The button layout.
+`shape` | String | The button shape.
 `tagline` | Boolean | Indicates whether to display the PayPal tagline.
 `use_default_height` | Boolean | Defines if button uses default height. If the value is `False`, the value of `height` is used.
 
@@ -378,16 +378,16 @@ The `SmartButtonsConfig` payment method configuration has a `MessageStyles` obje
 
 Attribute | Data Type | Description
 --- | --- | ---
-`layout` | String | The message layout
-`logo` | String | The message logo
+`layout` | String | The message layout.
+`logo` | String | The message logo.
 
 #### `SDKParams` attributes
 
 The `SDKParams` object provides details about the SDK parameters:
 
 Attribute |  Data Type | Description
 --- | --- | ---
-`name` | String | The name of the SDK parameter
-`value` | String | The value of the SDK parameter
+`name` | String | The name of the SDK parameter.
+`value` | String | The value of the SDK parameter.
 
 These values come from [PayPal JavaScript SDK](https://developer.paypal.com/sdk/js/reference/).

src/pages/graphql/schema/vault/index.md

@@ -0,0 +1,15 @@
+---
+title: Vault
+---
+
+# Vault
+
+<InlineAlert variant="info" slots="text" />
+
+This query is available only if you have installed [Payment Services for Adobe Commerce](https://commercemarketplace.adobe.com/magento-payment-services.html) 2.10.0 or higher.
+
+The vault schema provides GraphQL information to generate **vault** (stored payment details) information endpoints. This schema also provides mutations for modifying a payment token.
+
+Once vaulted, a payment method can be reused as many times as possible without your customer needing to re-enter or authenticate their payment information.
+
+These endpoints can be used to vault stored payment details without a purchase, but tt is possible to [vault a payment method during checkout](https://developer.adobe.com/commerce/webapi/graphql/payment-services/vault/), see the [`customer-payment-tokens`](https://developer.adobe.com/commerce/webapi/graphql/schema/checkout/queries/customer-payment-tokens/) query for more information.

src/pages/graphql/schema/vault/mutations/createVaultCardPaymentToken.md

@@ -0,0 +1,104 @@
+---
+title: createVaultCardPaymentToken mutation
+---
+
+# createVaultCardPaymentToken mutation
+
+<InlineAlert variant="info" slots="text" />
+
+This mutation is available only if you have installed [Payment Services for Adobe Commerce](https://commercemarketplace.adobe.com/magento-payment-services.html) 2.10.0 or higher.
+
+The `createVaultCardPaymentToken` mutation creates a permanent `vault_token_id` and associates an optional card description, visible in the storefront.
+
+To run the `createVaultCardPaymentToken` mutation, you need the `setup_token` generated with the `createVaultCardSetupToken` mutation.
+
+## Syntax
+
+```graphql
+mutation { 
+    createVaultCardPaymentToken(
+        input: CreateVaultCardPaymentTokenInput! 
+    ) CreateVaultCardPaymentTokenOutput    
+}
+```
+
+## Example usage
+
+The following example runs the `createVaultCardPaymentToken` mutation to create a permanent `vault_token_id` for the given payment method.
+
+## Request
+
+```graphql
+mutation {
+  createVaultCardPaymentToken(
+      input: {
+        setup_token_id: "23N11484TX9371211"
+        card_description: "My New Card"
+      } 
+  ) {
+      vault_token_id 
+      payment_source { 
+          card {
+              brand 
+              last_digits 
+              expiry
+          } 
+      }
+  }
+}
+```
+
+## Response
+
+```json
+{
+    "data": {
+        "createVaultCardPaymentToken": {
+            "vault_token_id": "745bf41a-4196-41a6-a17a-0234f89118fc",
+            "payment_source": {
+                "card": {
+                    "brand": "VISA",
+                    "last_digits": "0004",
+                    "expiry": "2027-02"
+                }
+            }
+        }
+    }
+} 
+```
+
+## Input attributes
+
+The `createVaultCardPaymentToken` object contains the following input attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`setup_token_id` | String! | The `setup_token` obtained with the `createVaultCardSetupToken` endpoint.
+`card_description` | Boolean | The description of the vaulted card.
+
+## Output attributes
+
+The `createVaultCardSetupToken` object contains the following attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`vault_token_id` | String! | The vault payment token information.
+`payment_source` | [PaymentSourceOutput]! | The payment source information.
+
+### `PaymentSourceOutput` attributes
+
+The `PaymentSourceOutput` object describes the payment source information. Requires the following attribute:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`card` | [CardPaymentSourceOutput]! | The card payment source information.
+
+### `CardPaymentSourceOutput` object
+
+The `CardPaymentSourceOutput` object describes the card payment source information. Requires the following attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`brand` | String | The brand of the card.
+`last_digits` | String | Last digits of the card.
+`expiry` | String | The expiry date of the card.

src/pages/graphql/schema/vault/mutations/createVaultCardSetupToken.md

@@ -0,0 +1,127 @@
+---
+title: createVaultCardSetupToken mutation
+---
+
+# createVaultCardSetupToken mutation
+
+<InlineAlert variant="info" slots="text" />
+
+This mutation is available only if you have installed [Payment Services for Adobe Commerce](https://commercemarketplace.adobe.com/magento-payment-services.html) 2.10.0 or higher.
+
+The `createVaultCardSetupToken` mutation creates a temporary `setup_token` associated to the given payment source.
+
+Use this token to create a permanent token with the `createVaultCardPaymentToken` mutation. The permanent token represents a payment method that is saved to the customer's vault.
+
+This setup token is generated with an empty card number in the `payment_source` object purposefully. In combination of PayPal SDK, hosted fields or credit cards fields components use this token to securely update the setup token with payment details.
+
+See [Paypal SDK developer documentation](https://developer.paypal.com/docs/multiparty/checkout/save-payment-methods/purchase-later/js-sdk/cards/) for more information.
+
+## Syntax
+
+```graphql
+mutation {
+    createVaultCardSetupToken(
+        input: CreateVaultCardSetupTokenInput!
+    ) CreateVaultCardSetupTokenOutput
+}
+```
+
+## Example usage
+
+The following example runs the `createVaultCardSetupToken` mutation to create a setup token for the given payment details.
+
+**Request:**
+
+```graphql
+mutation {
+      createVaultCardSetupToken(
+          input: {
+              setup_token: {
+                payment_source: {
+                    card: {
+                        name: "John Doe",
+                          billing_address: {
+                            address_line_1: "123 Main Street",
+                            address_line_2: "Apt 4B",
+                            region: "California",
+                            city: "San Jose",
+                            postal_code: "90001",
+                            country_code: "US"
+                          }
+                       }
+                   }
+            },
+            three_ds_mode: "SCA_ALWAYS"
+        }
+      ) {
+          setup_token
+      }
+}
+```
+
+**Response:**
+
+```json
+{
+    "data": {
+        "createVaultCardSetupToken": {
+            "setup_token": "11M29729J2618171X"
+        }
+    }
+}
+```
+
+## Input attributes
+
+The `createVaultCardSetupToken` mutation must contain the following input attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`setup_token` | [VaultSetupTokenInput]! | The setup token information.
+`three_ds_mode` | Boolean | Indicates which 3D Secure authentication mode is in use. The possible values are `OFF`, `SCA_WHEN_REQUIRED`, `SCA_ALWAYS`.
+
+### `VaultSetupTokenInput` attribute
+
+The `VaultSetupTokenInput` object describes the variables needed to create a vault card setup token. Requires the following attribute:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`payment_source` | [PaymentSourceInput]! | The payment source of the payment method.
+
+### `PaymentSourceInput` attribute
+
+The `PaymentSourceInput` object describes the payment source information of the payment method.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`card` | [CardPaymentSourceInput]! | The card payment source information.
+
+### `CardPaymentSourceInput` object
+
+The `CardPaymentSourceInput` object describes the card payment source information.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`billing_address` | [BillingAddressPaymentSourceInput]! | The billing address of the card.
+`name` | String! | The cardholder's name.
+
+### `BillingAddressPaymentSourceInput` object
+
+The `BillingAddressPaymentSourceInput` object includes the billing address information. Requires the following attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`address_line_1` | String | The first line of the address.
+`address_line_2` | String | The second line of the address.
+`region` | String | The region of the address.
+`city` | String | The city of the address.
+`postal_code` | String | The postal code of the address.
+`country_code` | String! | The country code of the address.
+
+## Output attributes
+
+The `createVaultCardSetupTokenOutput` object must contain the following attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`setup_token` | String! | The setup token id.