IBX-7108: Describe integration with Payum and payment gateways in Dev…

… docs (#2258) * Payum, Stripe and PayPal base * Implement changes after implementation --------- Co-authored-by: Tomasz Dąbrowski <[email protected]> Co-authored-by: Adrien Dupuis <[email protected]>
ibexa · Mar 27, 2024 · 88a6473 · 88a6473
1 parent 9b2385e
commit 88a6473
Show file tree

Hide file tree

Showing 7 changed files with 185 additions and 12 deletions.
diff --git a/docs/commerce/payment/configure_payment.md b/docs/commerce/payment/configure_payment.md
@@ -1,6 +1,5 @@
 ---
 description: Configure payments, modify the default payment processing workflow.
-
 edition: commerce
 ---
 
@@ -51,5 +50,5 @@ so that the system can identify which of your workflows handles the payment proc
 
 ## Configure payment methods
 
-You can define the payment methods [in the UI]([[= user_doc =]]/commerce/payment/configure_payment_method/).
-There is only one default payment method type available: `offline`, but you can [add custom ones](extend_payment.md).
+You can define payment methods [in the UI]([[= user_doc =]]/commerce/payment/configure_payment_method/).
+There is only one default payment method type available: `offline`, but you can configure more by [integrating with Payum](payum_integration.md), or [add custom ones](extend_payment.md).
diff --git a/docs/commerce/payment/enable_paypal_payments.md b/docs/commerce/payment/enable_paypal_payments.md
@@ -0,0 +1,44 @@
+---
+description: Use Payum to integrate the PayPal payment processing service.
+edition: commerce
+---
+
+### Enable PayPal payments with Payum
+
+By using Payum to integrate PayPal into your application, you can offer your customers a versatile payment processing service that supports various payment methods, including credit cards, debit cards, Pay Later options, and alternative payment methods.
+
+Before you can proceed with integrating PayPal, you must [create a PayPal business account](https://www.paypal.com/bizsignup/#/singlePageSignup) and obtain API credentials.
+
+Install the PayPal package:
+
+`composer require payum/paypal-express-checkout-nvp php-http/guzzle7-adapter`
+
+Then, add the following configuration to your YAML configuration file (`payum.yaml` or similar):
+
+```yaml
+payum:
+    gateways:
+        pp_express_checkout:
+            factory: paypal_express_checkout
+            username: <paypal_username>
+            password: <paypal_password>
+            signature: <paypal_signature>
+```
+
+!!! tip
+
+    You can replace `pp_express_checkout` with a different unique identifier.
+
+Ensure that the `username`, `password,` and `signature` fields contain the PayPal API credentials obtained from your PayPal business account.
+
+You can now provide language translations for the PayPal payment service name.
+To do it, within the `ibexa_payment_type` namespace in your translation files, use the provided translation key structure for each of your supported languages:
+
+```yaml
+ibexa:
+    payment_method:
+        type:
+            pp_express_checkout:
+                name: "Translated PayPal Express Checkout name"
+
+```
diff --git a/docs/commerce/payment/enable_stripe_payments.md b/docs/commerce/payment/enable_stripe_payments.md
@@ -0,0 +1,45 @@
+---
+description: Use Payum to integrate the Stripe payment processing service.
+edition: commerce
+---
+
+# Enable Stripe payments with Payum
+
+Stripe is a comprehensive payment platform that offers a suite of tools to handle online and in-person payments, subscriptions, fraud prevention, and more.
+By using Payum to integrate Stripe into your application, you can securely process payments with credit cards, bank transfers, and alternative payment methods.
+
+Before you can proceed with integrating Stripe, [sign up for a Stripe account](https://dashboard.stripe.com/register) and obtain the API keys required for integration.
+
+Install the Stripe package:
+
+`composer require payum/stripe php-http/guzzle7-adapter`
+
+Then, add the following configuration to your YAML configuration file (`payum.yaml` or similar):
+
+```yaml
+payum:
+    gateways:
+        strp_checkout:
+            factory: stripe_checkout
+            publishable_key: <publishable_key>
+            secret_key: <secret_key>
+
+```
+
+!!! tip
+
+    You can replace `strp_checkout` with a different unique identifier.
+
+Ensure that the `publishable_key` and `secret_key` fields contain the Stripe API keys.
+
+You can now provide language translations for the Stripe payment platform name.
+To do it, within the `ibexa_payment_type` namespace in your translation files, use the provided translation key structure within your translation files:
+
+```yaml
+ibexa:
+    payment_method:
+        type:
+            strp_checkout:
+                name: "Translated Stripe Checkout name"
+
+```
diff --git a/docs/commerce/payment/extend_payment.md b/docs/commerce/payment/extend_payment.md
@@ -13,8 +13,8 @@ You can also [customize the payment processing workflow](configure_payment.md#cu
 
 ## Create custom payment method type
 
-If your application needs payment methods of other type than the default `offline` one, you must create custom payment method types. 
-Code samples below show how this could be done if your organization wants to use PayPal.
+If your application needs payment methods of other type than the default `offline` one, or ones offered by Payum, you can create custom payment method types.
+Code samples below show how this could be done if your organization wants to use PayPal independently.
 
 !!! note "Gateway integration requirement"
 

diff --git a/docs/commerce/payment/payment.md b/docs/commerce/payment/payment.md
@@ -5,23 +5,25 @@ edition: commerce
 
 # Payment
 
-The Payment component enables users to define and manage payment methods, as well as create and manage payments, search for payment methods and payments and filter payment search results. 
+With the Payment component users can define and manage payment methods, create and manage payments, search for payment methods and payments, and filter payment search results.
 Depending on their role, users can also enable or disable payment methods, modify payment information, as well as cancel payments.
 
-Only one payment method type is available: `offline`.
+Available payment method types:
 
-From the development perspective, the component enables customization of the payment workflow. 
+- offline – out of the box
+- online payment services – through [integration with Payum](payum_integration.md)
 
-The component exposes the following:
+From the development perspective, the component enables [customization of the payment workflow](configure_payment.md#custom-payment-workflows).
+
+The component exposes the following APIs:
 
 - [Payment method PHP API](payment_method_api.md) that allows for managing payment methods
 - [Payment method REST API](../../api/rest_api/rest_api_reference/rest_api_reference.html#payment-methods) that helps manage payment methods over HTTP
 - [Payment PHP API](payment_api.md) that allows for managing payments
 
-
 ### Services
 
 The Payment package provides the following services, which are entry points for calling backend APIs:
 
 - `Ibexa\Contracts\Payment\PaymentMethodServiceInterface`
-- `Ibexa\Contracts\Payment\PaymentServiceInterface`
+- `Ibexa\Contracts\Payment\PaymentServiceInterface`
diff --git a/docs/commerce/payment/payum_integration.md b/docs/commerce/payment/payum_integration.md
@@ -0,0 +1,79 @@
+---
+description: Add new payment methods through Payum such as Stripe or PayPal.
+edition: commerce
+---
+
+# Payum integration
+
+[Payum](https://payum.gitbook.io/payum/) is a payment processing solution that simplifies the integration of various payment services like Stripe and PayPal into your application.
+These services provide security of online transactions, and allow you to accept multiple payment methods while ensuring a seamless experience for the customers.
+By configuring service gateways, mapping workflow actions and translating payment service names, you streamline the online payment process, and can offer a diverse payment experience.
+
+## General Payum configuration
+
+In your Payum configuration file, for example, `payum.yaml`, set up a payment service gateway by specifying the factory, credentials and other necessary settings.
+Replace `<payment_method_identifier>` with a unique identifier of the method provided by the payment service.
+
+```yaml
+payum:
+    gateways:
+        <payment_method_identifier>:
+            factory: <gateway_factory>
+            # Add specific configuration fields for the gateway
+            credential_1: <credential_1_value>
+            credential_2: <credential_2_value>
+```
+
+## Workflow mapping
+
+In [[= product_name =]], the default payment workflow has certain places, such as `pending`, `failed`, `paid`, or `cancelled`, and their corresponding transitions.
+However, for your application to use other transitions and places, for example, `authorized`, `notified`, `refunded` etc., and to present them in the user interface, you need to:
+- override the default payment workflow
+- create a custom workflow and enable it by using semantic configuration
+
+For more information, see [Custom payment workflows](configure_payment.md#custom-payment-workflows).
+
+For these places to be supported by the Payum integration, you have to map Payum statuses on the existing or additional places in the workflow, for example:
+
+```yaml
+ibexa_connector_payum:
+    status_mapping:
+        refunded: cancelled
+        captured: pending
+        authorized: authorized
+[...]
+```
+
+## Payment service name translations
+
+Within the `ibexa_payment_type` namespace in your translation files, add translations for each payment service that you configure.
+For language translations of payment service names, structure the translation files as follows:
+
+```yaml
+ibexa:
+    payment_method:
+        type:
+            <service_identifier>:
+                name: "Translated payment service name"
+
+```
+
+!!! note
+
+    Replace `<service_identifier>` with the identifier used in the Payum configuration.
+
+## Implementation
+
+When you implement the online payment solution, take the following consideration into account:
+
+- To learn what credentials must be provided and what specific settings must be made, refer to the each payment service gateway's specific documentation.
+- To customize the online payment UI, see [Creating custom views](https://github.com/Payum/Payum/blob/master/docs/symfony/custom-payment-page.md) in Payum documentation.
+- When you modify the payment process, you may need to subscribe to events dispatched by Payum.
+For a list of events, see [Event dispatcher](https://github.com/Payum/Payum/blob/master/docs/event-dispatcher.md) in Payum documentation.
+
+
+!!! caution
+
+    In certain cases, depending on the payment processing service, when a customer closes the payment page in a browser and the bank has not processed the payment yet, the payment status can remain unchanged.
+    Depending on how your checkout process is configured, it may result in unwanted effects, for example, cause that the cart does not purge after the purchase.
+    Make sure that you account for this fact in your implementation.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -322,7 +322,7 @@ nav:
         - Enable purchasing products: pim/enable_purchasing_products.md
         - Prices: pim/prices.md
         - Price API: pim/price_api.md
-        - Customize PIM: 
+        - Customize PIM:
             - Customize PIM: pim/customize_pim.md
             - Create custom attribute type: pim/create_custom_attribute_type.md
             - Create product code generator: pim/create_product_code_generator.md
@@ -352,6 +352,10 @@ nav:
             - Payment method API: commerce/payment/payment_method_api.md 
             - Payment method filtering: commerce/payment/payment_method_filtering.md
             - Payment API: commerce/payment/payment_api.md
+            - Online payment methods:
+                - Payum integration: commerce/payment/payum_integration.md
+                - Enable PayPal payments: commerce/payment/enable_paypal_payments.md
+                - Enable Stripe payments: commerce/payment/enable_stripe_payments.md
         - Shipping management:
             - Shipping management: commerce/shipping_management/shipping_management.md
             - Configure shipping: commerce/shipping_management/configure_shipment.md