diff --git a/modules/payment/src/Plugin/Commerce/PaymentGateway/OffsitePaymentGatewayInterface.php b/modules/payment/src/Plugin/Commerce/PaymentGateway/OffsitePaymentGatewayInterface.php
index 837b185e..163f6d48 100644
--- a/modules/payment/src/Plugin/Commerce/PaymentGateway/OffsitePaymentGatewayInterface.php
+++ b/modules/payment/src/Plugin/Commerce/PaymentGateway/OffsitePaymentGatewayInterface.php
@@ -20,6 +20,10 @@ use Symfony\Component\HttpFoundation\Request;
  * creating the payment in onNotify() is preferred, since it is guaranteed to
  * be called even if the customer does not return to the site.
  *
+ * Note that onReturn() will be skipped if onNotify() was called before the
+ * customer returned to the site, completing the payment process and
+ * placing the order.
+ *
  * If the customer declines to provide their payment details, and cancels
  * the payment at the payment provider, they will be redirected back to the
  * cancel url.
@@ -40,6 +44,11 @@ interface OffsitePaymentGatewayInterface extends PaymentGatewayInterface, Suppor
   /**
    * Processes the "return" request.
    *
+   * This method should only be concerned with creating/completing payments,
+   * the parent order should not be touched. The order state is updated
+   * automatically when the order is paid in full, or manually by the
+   * merchant (via the admin UI).
+   *
    * @param \Drupal\commerce_order\Entity\OrderInterface $order
    *   The order.
    * @param \Symfony\Component\HttpFoundation\Request $request
diff --git a/modules/payment/src/Plugin/Commerce/PaymentGateway/SupportsNotificationsInterface.php b/modules/payment/src/Plugin/Commerce/PaymentGateway/SupportsNotificationsInterface.php
index 27f47a29..5d960d57 100644
--- a/modules/payment/src/Plugin/Commerce/PaymentGateway/SupportsNotificationsInterface.php
+++ b/modules/payment/src/Plugin/Commerce/PaymentGateway/SupportsNotificationsInterface.php
@@ -17,6 +17,11 @@ interface SupportsNotificationsInterface {
   /**
    * Processes the notification request.
    *
+   * This method should only be concerned with creating/completing payments,
+   * the parent order should not be touched. The order state is updated
+   * automatically when the order is paid in full, or manually by the
+   * merchant (via the admin UI).
+   *
    * Note:
    * This method can't throw exceptions on failure because some payment
    * providers expect an error response to be returned in that case.