diff --git a/guides/source/developers/payments/payment-methods.html.md b/guides/source/developers/payments/payment-methods.html.md
index e67e87012f8..e4ca9bbdf27 100644
--- a/guides/source/developers/payments/payment-methods.html.md
+++ b/guides/source/developers/payments/payment-methods.html.md
@@ -30,6 +30,8 @@ service providers][payment-service-providers] article. -->
 - `available_to_users`: Determines if the payment method is visible to users.
 - `available_to_admin`: Determines if the payment method is visible to
   administrators.
+- `deprecated`: Determines whether the payment method has been deprecated and 
+  should not be used anymore.
 
 <!-- TODO:
   Uncomment the link to the payment service providers article once it is merged.
diff --git a/guides/source/developers/payments/payment-service-providers.html.md b/guides/source/developers/payments/payment-service-providers.html.md
index bb9e77f770d..4c88f5ef52f 100644
--- a/guides/source/developers/payments/payment-service-providers.html.md
+++ b/guides/source/developers/payments/payment-service-providers.html.md
@@ -64,3 +64,13 @@ You would need to extend or rewrite this class with your preferred PSP
 integration.
 
 [credit-card-base]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/payment_method/credit_card.rb
+
+### Switching payment service provider
+
+After switching payment service provider, there may be `Spree::PaymentMethod` 
+records referencing a `type` class that does not exist anymore.
+
+If you cannot delete these records, you can deprecate them running 
+`rake payment_method:deprecate_unsupported_payment_methods`. 
+This way, their `type` will be set to `Spree::PaymentMethod`, allowing for 
+records retrieval without errors.