Repository: AdobeDocs/commerce-extensibility
Pull request #369: CEXT-4634: Add PaaS webhook guide for validate-payment
Author: login: kuflower
Labels: name: major-update
description: Significant original updates to existing content
name: feedback
Created: 2025-05-14T19:42:52Z | Merged: 2025-05-19T18:22:09Z

## Purpose of this pull request

- Added PaaS webhook guide for validate-payment
- Fixed typos in ACCS webhook fields of validate-payments (missing `data`)

## Affected pages

<!-- REQUIRED List the affected pages on developer.adobe.com (URLs). Not necessary for large numbers of files. -->

- https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/use-cases/#validate-payment-info



Diff:
diff --git a/src/pages/starter-kit/checkout/payment-use-cases.md b/src/pages/starter-kit/checkout/payment-use-cases.md
index 130a05259..99514dcb0 100644
--- a/src/pages/starter-kit/checkout/payment-use-cases.md
+++ b/src/pages/starter-kit/checkout/payment-use-cases.md
@@ -12,7 +12,7 @@ This page explores different use cases and scenarios for implementing payment me
 
 For more general use cases, refer to [use-cases](./use-cases.md).
 
-## Payment flow: Get order details from Adobe Commerce using the masked cart ID
+## Get order details from Adobe Commerce using the masked cart ID
 
 The following steps demonstrate the payment flow:
 
@@ -24,10 +24,12 @@ The following steps demonstrate the payment flow:
 
 ![sequence.png](../../_images/starterkit/sequence.png)
 
-## Payment methods: Validate payment info
+## Validate payment info
 
 To perform a headless checkout and payment, the Commerce instance must ensure that the payment has succeeded and the order can be placed.
 
+### Set payment method additional data
+
 To ingest payment gateway specific information in the payment process, the checkout process must use the [`setPaymentMethodOnCart` mutation](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-payment-method/) in combination with the `payment_method.additional_data` field to persist the information required to validate the payment once the order is placed.
 
 ```graphql
@@ -58,10 +60,42 @@ setPaymentMethodOnCart(
 }
 ```
 
-With this information persisted, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) so that every time an order is placed, a synchronous call dispatches to the App Builder application implementing the payment method to validate the payment.
+### Validate the payment with a webhook
+
+With this additional information saved, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) to validate the payment during order placement. This webhook triggers a synchronous call to your App Builder application, which is responsible for verifying payment details before the order is finalized.
+
+The following example demonstrates how to add a webhook to the [`observer.sales_order_place_before`](../../webhooks/use-cases/order-placement-validation.md) method:
 
 &#8203;<Edition name="paas" /> To register a webhook, [modify the `webhooks.xml` file](../../webhooks/hooks.md) and create a new webhook with the following configuration:
 
+```xml
+<?xml version="1.0"?>
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_AdobeCommerceWebhooks:etc/webhooks.xsd">
+    <method name="observer.sales_order_place_before" type="before">
+        <hooks>
+            <batch name="out_of_process_payment_methods">
+                <hook name="validate_payment"
+                      url="https://<your_app_builder>.adobeioruntime.net/api/v1/web/commerce-checkout-starter-kit/validate-payment"
+                      method="POST" timeout="20000" softTimeout="0" priority="100" required="true"
+                      fallbackErrorMessage="Error on validation">
+                    <fields>
+                        <field name="payment_method" source="data.order.payment.method" />
+                        <field name="payment_additional_information" source="data.order.payment.additional_information" />
+                    </fields>
+                    <rules>
+                        <rule field="data.order.payment.method" operator="equal" value="<your_payment_method_code>" />
+                    </rules>
+                </hook>
+            </batch>
+        </hooks>
+    </method>
+</config>
+```
+
+&#8203;<Edition name="saas" />
+For Adobe Commerce as a Cloud Service, you can [create webhooks in the Admin](../../webhooks/create-webhooks.md).
+
 ```yaml
 Hook Settings
 
@@ -69,30 +103,30 @@ Hook Settings
   Webhook Type: before
   Batch Name: validate_payment
   Hook Name: oope_payment_methods_sales_order_place_before
-  URL: https://<yourappbuilder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/validate-payment
+  URL: https://<your_app_builder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/validate-payment
   Active: Yes
   Method: POST
 
 Hook Fields
 
   Name: payment_method
-  Source: order.payment.method
-  
+  Source: data.order.payment.method
+
   Name: payment_additional_information
-  Source: order.payment.additional_information
+  Source: data.order.payment.additional_information
 
 Hook Rules
 
-  Name: payment_method 
-  Value: <yourpaymentmethodcode>
+  Name: payment_method
+  Value: <your_payment_method_code>
   Operator: equal
 ```
 
-You can also enable webhook signature generation by following the [webhooks signature verification](../../webhooks/signature-verification.md) instructions.
+To enhance security, enable webhook signature generation by following the [webhooks signature verification](../../webhooks/signature-verification.md) instructions.
 
-Refer to [`actions/validate-payment.js`](https://github.com/adobe/commerce-checkout-starter-kit/blob/main/actions/validate-payment/index.js) for an example of how to receive the request and validate the payment according to the payment gateway needs.
+Refer to [`actions/validate-payment.js`](https://github.com/adobe/commerce-checkout-starter-kit/blob/main/actions/validate-payment/index.js) for an example of how to validate the payment according to the payment gateway needs.
 
-## Payment methods: Filter out payment method
+## Filter out payment method
 
 In some cases, you may want to filter out a payment method based on the cart details or the customer's information. For example, you may want to disable a payment method based on customer group or product attributes in the cart.
 
@@ -107,8 +141,8 @@ You can use the `plugin.magento.out_of_process_payment_methods.api.payment_metho
 ```xml
 <method name="plugin.magento.out_of_process_payment_methods.api.payment_method_filter.get_list" type="after">
     <hooks>
-        <batch name="check_product_stock">
-            <hook name="check_product_stock" url="https://<yourappbuilder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/filter-payment" method="POST" timeout="20000" softTimeout="0">
+        <batch name="out_of_process_payment_methods">
+            <hook name="payment_method_filter" url="https://<your_app_builder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/filter-payment" method="POST" timeout="20000" softTimeout="0">
                 <fields>
                     <field name="payload" />
                 </fields>
diff --git a/src/pages/starter-kit/checkout/shipping-use-cases.md b/src/pages/starter-kit/checkout/shipping-use-cases.md
index ce1970aa4..22e07193e 100644
--- a/src/pages/starter-kit/checkout/shipping-use-cases.md
+++ b/src/pages/starter-kit/checkout/shipping-use-cases.md
@@ -33,7 +33,7 @@ The following example demonstrates how to add a webhook to the `plugin.magento.o
     <method name="plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates" type="after">
         <hooks>
             <batch name="dps">
-                <hook name="add_shipping_rates_dps" url="https://<yourappbuilder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/shipping-methods" method="POST" timeout="5000" softTimeout="1000" priority="100" required="true">
+                <hook name="add_shipping_rates_dps" url="https://<your_app_builder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/shipping-methods" method="POST" timeout="5000" softTimeout="1000" priority="100" required="true">
                     <fields>
                         <field name="rateRequest" />
                     </fields>
@@ -46,13 +46,7 @@ The following example demonstrates how to add a webhook to the `plugin.magento.o
 
 You can register multiple webhooks for different shipping methods or shipping carriers by adding them into the same batch to ensure they are executed in parallel or create multiple batches to execute them sequentially.
 
-## Remove shipping method
-
-The `plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates` webhook allows you to remove specific shipping methods from the list of available options.
-
-If you use the `flatrate` shipping method, but want to disable it, you must update your webhook response to mark the shipping method as removed. This example is demonstrated in [`actions/shipping-methods.js`](https://github.com/adobe/commerce-checkout-starter-kit/blob/main/actions/shipping-methods/index.js).
-
-## Shipping methods: Payload
+### Payload
 
 The request payload contains information about all items in the cart, including product information, product attributes, shipping address, and customer information for logged-in customers.
 
@@ -130,7 +124,7 @@ Payload example:
 
 You can find examples of how to use shipping addresses, customer data, and product attributes in your App Builder application in [`actions/shipping-methods.js`](https://github.com/adobe/commerce-checkout-starter-kit/blob/main/actions/shipping-methods/index.js).
 
-## Shipping methods: GraphQL
+### GraphQL
 
 In the [`setShippingAddressesOnCart` mutation](https://developer.adobe.com/commerce/webapi/graphql/schema/cart/mutations/set-shipping-address/), available shipping methods that are returned by the webhook are appended to the `available_shipping_methods` field.
 
@@ -271,3 +265,9 @@ In the [`setShippingMethodsOnCart` mutation](https://developer.adobe.com/commerc
   }
 }
 ```
+
+## Remove shipping method
+
+The `plugin.magento.out_of_process_shipping_methods.api.shipping_rate_repository.get_rates` webhook allows you to remove specific shipping methods from the list of available options.
+
+If you use the `flatrate` shipping method, but want to disable it, you must update your webhook response to mark the shipping method as removed. This example is demonstrated in [`actions/shipping-methods.js`](https://github.com/adobe/commerce-checkout-starter-kit/blob/main/actions/shipping-methods/index.js).
diff --git a/src/pages/starter-kit/checkout/tax-use-cases.md b/src/pages/starter-kit/checkout/tax-use-cases.md
index a2027c14f..38879c57f 100644
--- a/src/pages/starter-kit/checkout/tax-use-cases.md
+++ b/src/pages/starter-kit/checkout/tax-use-cases.md
@@ -12,7 +12,7 @@ This page explores different use cases and scenarios for implementing tax integr
 
 For more general use cases, refer to [use-cases](./use-cases.md).
 
-## Tax management: Collect taxes
+## Collect taxes
 
 You can calculate and apply taxes on shopping carts during checkout by using the `collectTaxes` webhook. See [webhooks](../../webhooks/index.md) to understand and setup a webhook.
 
@@ -28,7 +28,7 @@ The following example demonstrates how to add a webhook to the `plugin.magento.o
             <batch name="collect_taxes">
                 <hook
                     name="collect_taxes"
-                    url="https://<yourappbuilder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/tax-calculation"
+                    url="https://<your_app_builder>.runtime.adobe.io/api/v1/web/commerce-checkout-starter-kit/tax-calculation"
                     method="POST" timeout="10000" softTimeout="2000"
                     priority="300" required="true" fallbackErrorMessage="Tax calculation failed. Please try again later."
                     ttl="0"
@@ -168,7 +168,7 @@ The key points for constructing the response are:
 ]
 ```
 
-## Tax management: Update custom attributes on tax classes via Admin UI
+## Update custom attributes on tax classes via Admin UI
 
 The out-of-process tax module allows you to add custom attributes to tax classes. These attributes are useful when integrating with third-party tax systems that require standardized identifiers or additional metadata.  
 For the relevant endpoints to update tax class custom attributes, see the [Tax API reference](./tax-reference.md).


Reviews:
user: login: jhadobe
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T22:39:18Z
user: login: obarcelonap
body: LGTM
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-15T13:53:45Z
user: login: jhadobe
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-19T17:46:32Z

Review comments:
diff_hunk: @@ -86,6 +86,8 @@ The following steps demonstrate the payment flow for getting order details from
 
 To perform a headless checkout and payment, the Commerce instance must ensure that the payment has succeeded and the order can be placed.
 
+#### Set the additional data to the payment method
path: src/pages/starter-kit/checkout/use-cases.md
user: login: jhadobe
body: I think this title needs to change. something like:

```suggestion
#### Set payment method additional data
```
created_at: 2025-05-14T22:36:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -116,12 +118,41 @@ setPaymentMethodOnCart(
 }
 ```
 
-With this information persisted, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) so that every time an order is placed, a synchronous call dispatches to the App Builder application implementing the payment method to validate the payment.
+#### Validate the payment via webhook
path: src/pages/starter-kit/checkout/use-cases.md
user: login: jhadobe
body: ```suggestion
#### Validate the payment with a webhook
```
created_at: 2025-05-14T22:36:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -116,12 +118,41 @@ setPaymentMethodOnCart(
 }
 ```
 
-With this information persisted, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) so that every time an order is placed, a synchronous call dispatches to the App Builder application implementing the payment method to validate the payment.
+#### Validate the payment via webhook
+
+With this additional information saved, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) to validate the payment during order placement. This webhook triggers a synchronous call to your App Builder application, which is responsible for verifying payment details before the order is finalized.
+
+The following example demonstrates how to add a webhook to the [`observer.sales_order_place_before`](../../webhooks/use-cases/order-placement-validation.md) method:
 
 <Edition name="paas" />
 
 To register a webhook in Adobe Commerce on Cloud or on-premises, [modify the `webhooks.xml` file](../../webhooks/hooks.md) and create a new webhook with the following configuration.
 
+```xml
+<?xml version="1.0"?>
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_AdobeCommerceWebhooks:etc/webhooks.xsd">
+    <method name="observer.sales_order_place_before" type="before">
+        <hooks>
+            <batch name="out_of_process_payment_methods">
+                <hook name="validate_payment"
+                      url="https://<yourappbuilder>.adobeioruntime.net/api/v1/web/commerce-checkout-starter-kit/validate-payment"
path: src/pages/starter-kit/checkout/use-cases.md
user: login: jhadobe
body: ```suggestion
                      url="https://<your_app_builder>.adobeioruntime.net/api/v1/web/commerce-checkout-starter-kit/validate-payment"
```
created_at: 2025-05-14T22:38:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -116,12 +118,41 @@ setPaymentMethodOnCart(
 }
 ```
 
-With this information persisted, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) so that every time an order is placed, a synchronous call dispatches to the App Builder application implementing the payment method to validate the payment.
+#### Validate the payment via webhook
+
+With this additional information saved, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) to validate the payment during order placement. This webhook triggers a synchronous call to your App Builder application, which is responsible for verifying payment details before the order is finalized.
+
+The following example demonstrates how to add a webhook to the [`observer.sales_order_place_before`](../../webhooks/use-cases/order-placement-validation.md) method:
 
 <Edition name="paas" />
 
 To register a webhook in Adobe Commerce on Cloud or on-premises, [modify the `webhooks.xml` file](../../webhooks/hooks.md) and create a new webhook with the following configuration.
 
+```xml
+<?xml version="1.0"?>
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_AdobeCommerceWebhooks:etc/webhooks.xsd">
+    <method name="observer.sales_order_place_before" type="before">
+        <hooks>
+            <batch name="out_of_process_payment_methods">
+                <hook name="validate_payment"
+                      url="https://<yourappbuilder>.adobeioruntime.net/api/v1/web/commerce-checkout-starter-kit/validate-payment"
+                      method="POST" timeout="20000" softTimeout="0" priority="100" required="true"
+                      fallbackErrorMessage="Error on validation">
+                    <fields>
+                        <field name="payment_method" source="data.order.payment.method" />
+                        <field name="payment_additional_information" source="data.order.payment.additional_information" />
+                    </fields>
+                    <rules>
+                        <rule field="data.order.payment.method" operator="equal" value="<yourpaymentmethodcode>" />
path: src/pages/starter-kit/checkout/use-cases.md
user: login: jhadobe
body: ```suggestion
                        <rule field="data.order.payment.method" operator="equal" value="<your_payment_method_code>" />
```
created_at: 2025-05-14T22:38:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -58,41 +60,73 @@ setPaymentMethodOnCart(
 }
 ```
 
-With this information persisted, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) so that every time an order is placed, a synchronous call dispatches to the App Builder application implementing the payment method to validate the payment.
+### Validate the payment with a webhook
+
+With this additional information saved, you can configure an [Adobe Commerce Webhook](../../webhooks/index.md) to validate the payment during order placement. This webhook triggers a synchronous call to your App Builder application, which is responsible for verifying payment details before the order is finalized.
+
+The following example demonstrates how to add a webhook to the [`observer.sales_order_place_before`](../../webhooks/use-cases/order-placement-validation.md) method:
 
 &#8203;<Edition name="paas" /> To register a webhook, [modify the `webhooks.xml` file](../../webhooks/hooks.md) and create a new webhook with the following configuration:
 
+```xml
+<?xml version="1.0"?>
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_AdobeCommerceWebhooks:etc/webhooks.xsd">
+    <method name="observer.sales_order_place_before" type="before">
+        <hooks>
+            <batch name="out_of_process_payment_methods">
+                <hook name="validate_payment"
+                      url="https://<your_app_builder>.adobeioruntime.net/api/v1/web/commerce-checkout-starter-kit/validate-payment"
+                      method="POST" timeout="20000" softTimeout="0" priority="100" required="true"
+                      fallbackErrorMessage="Error on validation">
+                    <fields>
+                        <field name="payment_method" source="data.order.payment.method" />
+                        <field name="payment_additional_information" source="data.order.payment.additional_information" />
+                    </fields>
+                    <rules>
+                        <rule field="data.order.payment.method" operator="equal" value="<your_payment_method_code>" />
+                    </rules>
+                </hook>
+            </batch>
+        </hooks>
+    </method>
+</config>
+```
+
+&#8203;<Edition name="saas" />
+For Adobe Commerce as a Cloud Service, you can [create webhook in the Admin](../../webhooks/create-webhooks.md).
path: src/pages/starter-kit/checkout/payment-use-cases.md
user: login: jhadobe
body: ```suggestion
For Adobe Commerce as a Cloud Service, you can [create webhooks in the Admin](../../webhooks/create-webhooks.md).
```
created_at: 2025-05-19T17:45:09Z
author_association: CONTRIBUTOR

PR comments:
user: login: jhadobe
created_at: 2025-05-19T14:21:38Z
body: @kuflower can you resolve conflicts, since we split up the `use-cases.md` page into different modules in #338, these changes will need to move to the new pages, e.g. `payment-use-cases.md`.
author_association: CONTRIBUTOR
user: login: kuflower
created_at: 2025-05-19T17:21:47Z
body: @jhadobe The change has been rebased on top of the latest main branch. I introduced a bit of reorganization in each use case: https://github.com/AdobeDocs/commerce-extensibility/pull/369/commits/40189ae3bf2a9f384de50b65d1de6e1703a4b6d9
Please let me know if you find any issues with them. Thank you!
author_association: COLLABORATOR
user: login: jhadobe
created_at: 2025-05-19T17:47:29Z
body: @kuflower is this ready to publish?
author_association: CONTRIBUTOR
user: login: kuflower
created_at: 2025-05-19T17:54:46Z
body: @jhadobe Yes, it's ready. Please proceed with merging if it's ok with you, thanks!
author_association: COLLABORATOR