From 11e328315f7cd631cd95cdcb193602992ce54cf2 Mon Sep 17 00:00:00 2001 From: Magdalena Dziadosz <35031941+MagdalenaZuba@users.noreply.github.com> Date: Tue, 5 Dec 2023 14:31:52 +0100 Subject: [PATCH 01/10] Payum, Stripe and PayPal base --- docs/commerce/payment/paypal_integration.md | 53 +++++++++++++ docs/commerce/payment/payum_integration.md | 51 +++++++++++++ docs/commerce/payment/stripe_integration.md | 82 +++++++++++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 docs/commerce/payment/paypal_integration.md create mode 100644 docs/commerce/payment/payum_integration.md create mode 100644 docs/commerce/payment/stripe_integration.md diff --git a/docs/commerce/payment/paypal_integration.md b/docs/commerce/payment/paypal_integration.md new file mode 100644 index 0000000000..7524f61f75 --- /dev/null +++ b/docs/commerce/payment/paypal_integration.md @@ -0,0 +1,53 @@ +# Configuring PayPal Payments with Payum + +## Integration via Payum Configuration + +PayPal offers a versatile payment gateway that supports various payment methods, including credit cards, debit cards, Pay Later options, and alternative payment methods like Venmo. +Integrating PayPal allows for a secure and convenient checkout experience. + +## Account setup + +[Create a PayPal business account](https://www.paypal.com/bizsignup/#/singlePageSignup) and obtain API credentials. + +## Configuration setup + +Add the following configuration snippet to your YAML configuration file (`payum.yaml` or similar): + +```yaml +payum: + gateways: + : + factory: paypal_express_checkout + username: + password: + signature: +``` + +Replace `` with a unique identifier for the PayPal payment method. +The username, password, and signature fields should contain your PayPal API credentials obtained from your PayPal business account. + +## Translations for payment methods + +For language translations of PayPal payment method names, use the provided translation key structure within your translation files: + +```yaml +ibexa: + payment_method: + type: + : + name: "Translated PayPal Method Name" + +``` + +Replace `` with the identifier used in the Payum configuration. +Add translations for each PayPal payment method identifier within the `ibexa_payment_type` namespace in your translation files. + +### Implementation + +- Ensure the provided PayPal API credentials (username, password, and signature) are from your PayPal business account and are correctly configured within your application. +- Maintain consistency between the payment method identifiers used in the Payum configuration and the corresponding translations in your language files. + +### Conclusion + +By configuring PayPal payments as described in the Payum documentation and incorporating translations for payment method names, +you can enhance the user experience by presenting a localized interface while securely processing payments using PayPal's reliable platform. \ No newline at end of file diff --git a/docs/commerce/payment/payum_integration.md b/docs/commerce/payment/payum_integration.md new file mode 100644 index 0000000000..b4e0c5b710 --- /dev/null +++ b/docs/commerce/payment/payum_integration.md @@ -0,0 +1,51 @@ +--- +description: Add new payment methods through Payum such as Stripe or PayPal. +edition: commerce +--- + +# Payment gateways + +[Payum](https://payum.gitbook.io/payum/) simplifies the integration of various payment gateways like Stripe and PayPal into your application. +These gateways are vital for secure online transactions, allowing you to accept multiple payment methods and ensure a seamless experience for customers. +By configuring gateways and translating payment methods, Payum streamlines the process, enabling you to offer a diverse payment experience effortlessly. + +## Payum configuration + +In your Payum configuration file (`payum.yaml` or similar), set up the payment gateway by specifying its factory and required credentials: + +```yaml +payum: + gateways: + : + factory: + # Add specific configuration fields for the chosen gateway + credential_1: + credential_2: + # Add more credentials or settings as required by the chosen gateway + +``` + +Replace `` with a unique identifier for the payment method. +Define the factory based on the supported gateway. Include the necessary credentials and settings required by the specific gateway. + +## Translations for payment methods + +For language translations of payment method names, structure your translation files as follows: + +```yaml +ibexa: + payment_method: + type: + : + name: "Translated Payment Method Name" + +``` + +Replace `` with the identifier used in the Payum configuration. +Add translations for each payment method identifier within the ibexa_payment_type namespace in your translation files. + +## Implementation + +Refer to the specific documentation for each payment gateway to obtain the necessary credentials and configuration settings. +Ensure the accuracy of provided credentials and settings within the Payum configuration. + diff --git a/docs/commerce/payment/stripe_integration.md b/docs/commerce/payment/stripe_integration.md new file mode 100644 index 0000000000..50ee972200 --- /dev/null +++ b/docs/commerce/payment/stripe_integration.md @@ -0,0 +1,82 @@ +--- +description: Configuring Stripe payments with Payum. +edition: commerce +--- + +# Configuring Stripe payments with Payum + +Stripe is a comprehensive payment platform offering a suite of tools to handle online and in-person payments, subscriptions, fraud prevention, and more. +Integrating Stripe into your application allows you to securely process payments using credit cards, bank transfers, and alternative payment methods. + +## Account setup + +[Sign up for a Stripe account](https://dashboard.stripe.com/register) to obtain API keys required for integration. + +## Configuration setup + +Add the following configuration snippet to your YAML configuration file (payum.yaml or similar): + +```yaml +payum: + gateways: + : + factory: stripe_checkout + publishable_key: + secret_key: + +``` + +Replace `` with a unique identifier for the payment method. +The `publishable_key` and `secret_key` fields should contain your Stripe API keys, obtained from your Stripe account dashboard. + +### Translations for payment methods + +For language translations of payment method names, use the provided translation key structure within your translation files: + +```yaml +ibexa: + payment_method: + type: + : + name: "Translated Payment Method Name" + +``` + +Replace `` with the identifier used in the Payum configuration. +Add translations for each payment method identifier within the `ibexa_payment_type` namespace in your translation files. + +Example: + +Let's say you have a Stripe payment method configured in Payum with the identifier `stripe_payment`: + +```yaml +payum: + gateways: + stripe_payment: + factory: stripe_checkout + publishable_key: pk_test_your_publishable_key + secret_key: sk_test_your_secret_key + +``` + +For language translations, in your translation files: + +```yaml +ibexa: + payment_method: + type: + stripe_payment: + name: "Stripe Payment Method" + +``` + +Ensure to replace "Stripe Payment Method" with the translated name in the respective language. + +### Implementation + +- Verify that the provided API keys (publishable and secret) are from your Stripe account and are correctly configured within your application. +- Maintain consistency between the payment method identifiers used in the Payum configuration and the corresponding translations in your language files. + +### Conclusion + +By configuring Stripe payments in line with the Payum documentation and incorporating translations for payment method names, you can enhance the user experience by presenting a localized interface while securely processing payments using Stripe's robust platform. \ No newline at end of file From aa651367a38a518b2a9eb3ef88b10bf472579318 Mon Sep 17 00:00:00 2001 From: Magdalena Dziadosz <35031941+MagdalenaZuba@users.noreply.github.com> Date: Thu, 7 Dec 2023 12:58:05 +0100 Subject: [PATCH 02/10] Payment methods added --- docs/commerce/payment/payment.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/commerce/payment/payment.md b/docs/commerce/payment/payment.md index 76cdf9ca06..c81c113bee 100644 --- a/docs/commerce/payment/payment.md +++ b/docs/commerce/payment/payment.md @@ -8,7 +8,10 @@ edition: commerce 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. 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`. +There are few payment method types is available: + +- offline – out of the box +- payment gateways – integration with Payum From the development perspective, the component enables customization of the payment workflow. @@ -18,7 +21,6 @@ The component exposes the following: - [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: From 82b764ae3a1d30a6cbdd7a1dbcd5520018268c0b Mon Sep 17 00:00:00 2001 From: Magdalena Dziadosz <35031941+MagdalenaZuba@users.noreply.github.com> Date: Fri, 8 Dec 2023 11:32:47 +0100 Subject: [PATCH 03/10] payum mentions --- docs/commerce/payment/configure_payment.md | 2 +- docs/commerce/payment/extend_payment.md | 4 ++-- docs/commerce/payment/payum_integration.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/commerce/payment/configure_payment.md b/docs/commerce/payment/configure_payment.md index cf1b85ece5..210acfb9f5 100644 --- a/docs/commerce/payment/configure_payment.md +++ b/docs/commerce/payment/configure_payment.md @@ -52,4 +52,4 @@ 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). +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/extend_payment.md b/docs/commerce/payment/extend_payment.md index df59c49785..353f21b590 100644 --- 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/payum_integration.md b/docs/commerce/payment/payum_integration.md index b4e0c5b710..c90d73eb82 100644 --- a/docs/commerce/payment/payum_integration.md +++ b/docs/commerce/payment/payum_integration.md @@ -7,7 +7,7 @@ edition: commerce [Payum](https://payum.gitbook.io/payum/) simplifies the integration of various payment gateways like Stripe and PayPal into your application. These gateways are vital for secure online transactions, allowing you to accept multiple payment methods and ensure a seamless experience for customers. -By configuring gateways and translating payment methods, Payum streamlines the process, enabling you to offer a diverse payment experience effortlessly. +By configuring gateways and translating payment methods, Payum streamlines the process, enabling you to offer a diverse payment experience. ## Payum configuration From 44d1612c19cdd054eb08fe37dbf430816f0dafa3 Mon Sep 17 00:00:00 2001 From: Magdalena Dziadosz <35031941+MagdalenaZuba@users.noreply.github.com> Date: Fri, 22 Dec 2023 08:47:14 +0100 Subject: [PATCH 04/10] Minor updates --- docs/commerce/payment/configure_payment.md | 2 +- docs/commerce/payment/payment_api.md | 2 +- docs/commerce/payment/payum_integration.md | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/commerce/payment/configure_payment.md b/docs/commerce/payment/configure_payment.md index 210acfb9f5..f410b09f01 100644 --- a/docs/commerce/payment/configure_payment.md +++ b/docs/commerce/payment/configure_payment.md @@ -51,5 +51,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/). +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/payment_api.md b/docs/commerce/payment/payment_api.md index f0683890c0..0909cf85c1 100644 --- a/docs/commerce/payment/payment_api.md +++ b/docs/commerce/payment/payment_api.md @@ -62,5 +62,5 @@ To update payment information, use the `PaymentServiceInterface::updatePayment` To delete a payment from the system, use the `PaymentServiceInterface::deletePayment` method: ``` php -[[= include_file('code_samples/api/commerce/src/Command/PaymentCommand.php', 114, 114) =]] +[[= include_file('code_samples/api/commerce/src/Command/PaymentCommand.php', 114, 115) =]] ``` diff --git a/docs/commerce/payment/payum_integration.md b/docs/commerce/payment/payum_integration.md index c90d73eb82..abaa0d75c9 100644 --- a/docs/commerce/payment/payum_integration.md +++ b/docs/commerce/payment/payum_integration.md @@ -26,7 +26,8 @@ payum: ``` Replace `` with a unique identifier for the payment method. -Define the factory based on the supported gateway. Include the necessary credentials and settings required by the specific gateway. +Define the factory based on the supported gateway. +Include the necessary credentials and settings required by the specific gateway. ## Translations for payment methods From 556c71f595d7c6d4682fb4278ecd26875155e2d2 Mon Sep 17 00:00:00 2001 From: Magdalena Dziadosz <35031941+MagdalenaZuba@users.noreply.github.com> Date: Fri, 22 Dec 2023 10:46:01 +0100 Subject: [PATCH 05/10] proofing --- docs/commerce/payment/configure_payment.md | 1 - docs/commerce/payment/extend_payment.md | 2 +- docs/commerce/payment/payment.md | 2 +- docs/commerce/payment/paypal_integration.md | 13 +++++++++---- docs/commerce/payment/payum_integration.md | 4 ++-- 5 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/commerce/payment/configure_payment.md b/docs/commerce/payment/configure_payment.md index f410b09f01..df0b3b6f61 100644 --- 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 --- diff --git a/docs/commerce/payment/extend_payment.md b/docs/commerce/payment/extend_payment.md index 353f21b590..15ad479342 100644 --- a/docs/commerce/payment/extend_payment.md +++ b/docs/commerce/payment/extend_payment.md @@ -13,7 +13,7 @@ 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, or ones offered by Payum, you can create custom payment method types. +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 index c81c113bee..a0945f8fd8 100644 --- a/docs/commerce/payment/payment.md +++ b/docs/commerce/payment/payment.md @@ -8,7 +8,7 @@ edition: commerce 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. Depending on their role, users can also enable or disable payment methods, modify payment information, as well as cancel payments. -There are few payment method types is available: +Available payment method types : - offline – out of the box - payment gateways – integration with Payum diff --git a/docs/commerce/payment/paypal_integration.md b/docs/commerce/payment/paypal_integration.md index 7524f61f75..683808e04f 100644 --- a/docs/commerce/payment/paypal_integration.md +++ b/docs/commerce/payment/paypal_integration.md @@ -1,8 +1,13 @@ -# Configuring PayPal Payments with Payum +--- +description: Configuring PayPal payments with Payum. +edition: commerce +--- + +# Configuring PayPal payments with Payum ## Integration via Payum Configuration -PayPal offers a versatile payment gateway that supports various payment methods, including credit cards, debit cards, Pay Later options, and alternative payment methods like Venmo. +PayPal offers a versatile payment gateway that supports various payment methods, including credit cards, debit cards, Pay Later options, and alternative payment methods like Venmo. Integrating PayPal allows for a secure and convenient checkout experience. ## Account setup @@ -23,7 +28,7 @@ payum: signature: ``` -Replace `` with a unique identifier for the PayPal payment method. +Replace `` with a unique identifier for the PayPal payment method. The username, password, and signature fields should contain your PayPal API credentials obtained from your PayPal business account. ## Translations for payment methods @@ -39,7 +44,7 @@ ibexa: ``` -Replace `` with the identifier used in the Payum configuration. +Replace `` with the identifier used in the Payum configuration. Add translations for each PayPal payment method identifier within the `ibexa_payment_type` namespace in your translation files. ### Implementation diff --git a/docs/commerce/payment/payum_integration.md b/docs/commerce/payment/payum_integration.md index abaa0d75c9..7f5ff4bd7b 100644 --- a/docs/commerce/payment/payum_integration.md +++ b/docs/commerce/payment/payum_integration.md @@ -25,7 +25,7 @@ payum: ``` -Replace `` with a unique identifier for the payment method. +Replace `` with a unique identifier for the payment method. Define the factory based on the supported gateway. Include the necessary credentials and settings required by the specific gateway. @@ -42,7 +42,7 @@ ibexa: ``` -Replace `` with the identifier used in the Payum configuration. +Replace `` with the identifier used in the Payum configuration. Add translations for each payment method identifier within the ibexa_payment_type namespace in your translation files. ## Implementation From 4e1b999d5edbfc34eb99a4b63ef5df53aaf8f422 Mon Sep 17 00:00:00 2001 From: Magdalena Dziadosz <35031941+MagdalenaZuba@users.noreply.github.com> Date: Fri, 22 Dec 2023 10:59:52 +0100 Subject: [PATCH 06/10] proofing --- docs/commerce/payment/paypal_integration.md | 2 -- docs/commerce/payment/stripe_integration.md | 6 +----- 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/commerce/payment/paypal_integration.md b/docs/commerce/payment/paypal_integration.md index 683808e04f..51badad13b 100644 --- a/docs/commerce/payment/paypal_integration.md +++ b/docs/commerce/payment/paypal_integration.md @@ -5,8 +5,6 @@ edition: commerce # Configuring PayPal payments with Payum -## Integration via Payum Configuration - PayPal offers a versatile payment gateway that supports various payment methods, including credit cards, debit cards, Pay Later options, and alternative payment methods like Venmo. Integrating PayPal allows for a secure and convenient checkout experience. diff --git a/docs/commerce/payment/stripe_integration.md b/docs/commerce/payment/stripe_integration.md index 50ee972200..2a416f4e79 100644 --- a/docs/commerce/payment/stripe_integration.md +++ b/docs/commerce/payment/stripe_integration.md @@ -75,8 +75,4 @@ Ensure to replace "Stripe Payment Method" with the translated name in the respec ### Implementation - Verify that the provided API keys (publishable and secret) are from your Stripe account and are correctly configured within your application. -- Maintain consistency between the payment method identifiers used in the Payum configuration and the corresponding translations in your language files. - -### Conclusion - -By configuring Stripe payments in line with the Payum documentation and incorporating translations for payment method names, you can enhance the user experience by presenting a localized interface while securely processing payments using Stripe's robust platform. \ No newline at end of file +- Maintain consistency between the payment method identifiers used in the Payum configuration and the corresponding translations in your language files. \ No newline at end of file From 0096b22da55d32574e3056856581ca63f93c18e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 4 Mar 2024 21:54:51 +0100 Subject: [PATCH 07/10] Implement changes after implementation --- .../payment/enable_paypal_payments.md | 40 ++++++++++ .../payment/enable_stripe_payments.md | 41 ++++++++++ docs/commerce/payment/payment.md | 12 +-- docs/commerce/payment/paypal_integration.md | 56 ------------- docs/commerce/payment/payum_integration.md | 69 +++++++++++----- docs/commerce/payment/stripe_integration.md | 78 ------------------- mkdocs.yml | 6 +- 7 files changed, 140 insertions(+), 162 deletions(-) create mode 100644 docs/commerce/payment/enable_paypal_payments.md create mode 100644 docs/commerce/payment/enable_stripe_payments.md delete mode 100644 docs/commerce/payment/paypal_integration.md delete mode 100644 docs/commerce/payment/stripe_integration.md diff --git a/docs/commerce/payment/enable_paypal_payments.md b/docs/commerce/payment/enable_paypal_payments.md new file mode 100644 index 0000000000..6de90606cb --- /dev/null +++ b/docs/commerce/payment/enable_paypal_payments.md @@ -0,0 +1,40 @@ +--- +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. + +Then, add the following configuration to your YAML configuration file (`payum.yaml` or similar): + +```yaml +payum: + gateways: + paypal_payment_service: + factory: paypal_express_checkout + username: + password: + signature: +``` + +!!! tip + + You can replace `paypal_payment_service` 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: + paypal_payment_service: + name: "Translated PayPal service name" + +``` \ No newline at end of file diff --git a/docs/commerce/payment/enable_stripe_payments.md b/docs/commerce/payment/enable_stripe_payments.md new file mode 100644 index 0000000000..238463e58f --- /dev/null +++ b/docs/commerce/payment/enable_stripe_payments.md @@ -0,0 +1,41 @@ +--- +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. + +Then, add the following configuration to your YAML configuration file (`payum.yaml` or similar): + +```yaml +payum: + gateways: + stripe_payment_platform: + factory: stripe_checkout + publishable_key: + secret_key: + +``` + +!!! tip + + You can replace `stripe_payment_platform` 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: + stripe_payment_platform: + name: "Translated Stripe platform name" + +``` \ No newline at end of file diff --git a/docs/commerce/payment/payment.md b/docs/commerce/payment/payment.md index a0945f8fd8..2fcf60ab47 100644 --- a/docs/commerce/payment/payment.md +++ b/docs/commerce/payment/payment.md @@ -5,17 +5,17 @@ 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. -Available payment method types : +Available payment method types : - offline – out of the box -- payment gateways – integration with Payum +- online payment services – through [integration with Payum](payum_integration.md) -From the development perspective, the component enables customization of the payment workflow. +From the development perspective, the component enables [customization of the payment workflow](configure_payment.md#custom-payment-workflows). -The component exposes the following: +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 @@ -26,4 +26,4 @@ The component exposes the following: 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` \ No newline at end of file diff --git a/docs/commerce/payment/paypal_integration.md b/docs/commerce/payment/paypal_integration.md deleted file mode 100644 index 51badad13b..0000000000 --- a/docs/commerce/payment/paypal_integration.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -description: Configuring PayPal payments with Payum. -edition: commerce ---- - -# Configuring PayPal payments with Payum - -PayPal offers a versatile payment gateway that supports various payment methods, including credit cards, debit cards, Pay Later options, and alternative payment methods like Venmo. -Integrating PayPal allows for a secure and convenient checkout experience. - -## Account setup - -[Create a PayPal business account](https://www.paypal.com/bizsignup/#/singlePageSignup) and obtain API credentials. - -## Configuration setup - -Add the following configuration snippet to your YAML configuration file (`payum.yaml` or similar): - -```yaml -payum: - gateways: - : - factory: paypal_express_checkout - username: - password: - signature: -``` - -Replace `` with a unique identifier for the PayPal payment method. -The username, password, and signature fields should contain your PayPal API credentials obtained from your PayPal business account. - -## Translations for payment methods - -For language translations of PayPal payment method names, use the provided translation key structure within your translation files: - -```yaml -ibexa: - payment_method: - type: - : - name: "Translated PayPal Method Name" - -``` - -Replace `` with the identifier used in the Payum configuration. -Add translations for each PayPal payment method identifier within the `ibexa_payment_type` namespace in your translation files. - -### Implementation - -- Ensure the provided PayPal API credentials (username, password, and signature) are from your PayPal business account and are correctly configured within your application. -- Maintain consistency between the payment method identifiers used in the Payum configuration and the corresponding translations in your language files. - -### Conclusion - -By configuring PayPal payments as described in the Payum documentation and incorporating translations for payment method names, -you can enhance the user experience by presenting a localized interface while securely processing payments using PayPal's reliable platform. \ No newline at end of file diff --git a/docs/commerce/payment/payum_integration.md b/docs/commerce/payment/payum_integration.md index 7f5ff4bd7b..ced96ff989 100644 --- a/docs/commerce/payment/payum_integration.md +++ b/docs/commerce/payment/payum_integration.md @@ -3,50 +3,77 @@ description: Add new payment methods through Payum such as Stripe or PayPal. edition: commerce --- -# Payment gateways +# Payum integration -[Payum](https://payum.gitbook.io/payum/) simplifies the integration of various payment gateways like Stripe and PayPal into your application. -These gateways are vital for secure online transactions, allowing you to accept multiple payment methods and ensure a seamless experience for customers. -By configuring gateways and translating payment methods, Payum streamlines the process, enabling you to offer a diverse payment experience. +[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. -## Payum configuration +## General Payum configuration -In your Payum configuration file (`payum.yaml` or similar), set up the payment gateway by specifying its factory and required credentials: +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 `` with a unique identifier for the payment service. ```yaml payum: gateways: - : + : factory: - # Add specific configuration fields for the chosen gateway + # Add specific configuration fields for the gateway credential_1: credential_2: - # Add more credentials or settings as required by the chosen gateway - ``` -Replace `` with a unique identifier for the payment method. -Define the factory based on the supported gateway. -Include the necessary credentials and settings required by the specific gateway. +## 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 -## Translations for payment methods +For more information, see [Custom payment workflows](configure_payment.md#custom-payment-workflows). -For language translations of payment method names, structure your translation files as follows: +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: - : - name: "Translated Payment Method Name" + : + name: "Translated payment service name" ``` -Replace `` with the identifier used in the Payum configuration. -Add translations for each payment method identifier within the ibexa_payment_type namespace in your translation files. +!!! note + + Replace `` with the identifier used in the Payum configuration. ## Implementation -Refer to the specific documentation for each payment gateway to obtain the necessary credentials and configuration settings. -Ensure the accuracy of provided credentials and settings within the Payum configuration. +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/docs/commerce/payment/stripe_integration.md b/docs/commerce/payment/stripe_integration.md deleted file mode 100644 index 2a416f4e79..0000000000 --- a/docs/commerce/payment/stripe_integration.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: Configuring Stripe payments with Payum. -edition: commerce ---- - -# Configuring Stripe payments with Payum - -Stripe is a comprehensive payment platform offering a suite of tools to handle online and in-person payments, subscriptions, fraud prevention, and more. -Integrating Stripe into your application allows you to securely process payments using credit cards, bank transfers, and alternative payment methods. - -## Account setup - -[Sign up for a Stripe account](https://dashboard.stripe.com/register) to obtain API keys required for integration. - -## Configuration setup - -Add the following configuration snippet to your YAML configuration file (payum.yaml or similar): - -```yaml -payum: - gateways: - : - factory: stripe_checkout - publishable_key: - secret_key: - -``` - -Replace `` with a unique identifier for the payment method. -The `publishable_key` and `secret_key` fields should contain your Stripe API keys, obtained from your Stripe account dashboard. - -### Translations for payment methods - -For language translations of payment method names, use the provided translation key structure within your translation files: - -```yaml -ibexa: - payment_method: - type: - : - name: "Translated Payment Method Name" - -``` - -Replace `` with the identifier used in the Payum configuration. -Add translations for each payment method identifier within the `ibexa_payment_type` namespace in your translation files. - -Example: - -Let's say you have a Stripe payment method configured in Payum with the identifier `stripe_payment`: - -```yaml -payum: - gateways: - stripe_payment: - factory: stripe_checkout - publishable_key: pk_test_your_publishable_key - secret_key: sk_test_your_secret_key - -``` - -For language translations, in your translation files: - -```yaml -ibexa: - payment_method: - type: - stripe_payment: - name: "Stripe Payment Method" - -``` - -Ensure to replace "Stripe Payment Method" with the translated name in the respective language. - -### Implementation - -- Verify that the provided API keys (publishable and secret) are from your Stripe account and are correctly configured within your application. -- Maintain consistency between the payment method identifiers used in the Payum configuration and the corresponding translations in your language files. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index b56eb360b3..4c77c55312 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -339,7 +339,11 @@ nav: - Extend Payment: commerce/payment/extend_payment.md - 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 + - 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 From 4cc3f471a10b22764c40999e69b4a94061d59bd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Wed, 13 Mar 2024 16:45:18 +0100 Subject: [PATCH 08/10] Add package installation step to integration examples --- docs/commerce/payment/enable_paypal_payments.md | 4 ++++ docs/commerce/payment/enable_stripe_payments.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/commerce/payment/enable_paypal_payments.md b/docs/commerce/payment/enable_paypal_payments.md index 6de90606cb..c909f65442 100644 --- a/docs/commerce/payment/enable_paypal_payments.md +++ b/docs/commerce/payment/enable_paypal_payments.md @@ -9,6 +9,10 @@ By using Payum to integrate PayPal into your application, you can offer your cus 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 diff --git a/docs/commerce/payment/enable_stripe_payments.md b/docs/commerce/payment/enable_stripe_payments.md index 238463e58f..716ff01380 100644 --- a/docs/commerce/payment/enable_stripe_payments.md +++ b/docs/commerce/payment/enable_stripe_payments.md @@ -10,6 +10,10 @@ By using Payum to integrate Stripe into your application, you can securely proce 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 From 971807a7f2d096b9ce685f6666f39aa65a844280 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 19 Mar 2024 14:38:24 +0100 Subject: [PATCH 09/10] Implement reviewer comments --- docs/commerce/payment/enable_paypal_payments.md | 8 ++++---- docs/commerce/payment/enable_stripe_payments.md | 8 ++++---- docs/commerce/payment/payum_integration.md | 4 ++-- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/commerce/payment/enable_paypal_payments.md b/docs/commerce/payment/enable_paypal_payments.md index c909f65442..3da30e7de6 100644 --- a/docs/commerce/payment/enable_paypal_payments.md +++ b/docs/commerce/payment/enable_paypal_payments.md @@ -18,7 +18,7 @@ Then, add the following configuration to your YAML configuration file (`payum.ya ```yaml payum: gateways: - paypal_payment_service: + pp_express_checkout: factory: paypal_express_checkout username: password: @@ -27,7 +27,7 @@ payum: !!! tip - You can replace `paypal_payment_service` with a different unique identifier. + 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. @@ -38,7 +38,7 @@ To do it, within the `ibexa_payment_type` namespace in your translation files, u ibexa: payment_method: type: - paypal_payment_service: - name: "Translated PayPal service name" + pp_express_checkout: + name: "Translated PayPal Express Checkout name" ``` \ No newline at end of file diff --git a/docs/commerce/payment/enable_stripe_payments.md b/docs/commerce/payment/enable_stripe_payments.md index 716ff01380..e05e2c1f0d 100644 --- a/docs/commerce/payment/enable_stripe_payments.md +++ b/docs/commerce/payment/enable_stripe_payments.md @@ -19,7 +19,7 @@ Then, add the following configuration to your YAML configuration file (`payum.ya ```yaml payum: gateways: - stripe_payment_platform: + strp_checkout: factory: stripe_checkout publishable_key: secret_key: @@ -28,7 +28,7 @@ payum: !!! tip - You can replace `stripe_payment_platform` with a different unique identifier. + You can replace `strp_checkout` with a different unique identifier. Ensure that the `publishable_key` and `secret_key` fields contain the Stripe API keys. @@ -39,7 +39,7 @@ To do it, within the `ibexa_payment_type` namespace in your translation files, u ibexa: payment_method: type: - stripe_payment_platform: - name: "Translated Stripe platform name" + strp_checkout: + name: "Translated Stripe Checkout name" ``` \ No newline at end of file diff --git a/docs/commerce/payment/payum_integration.md b/docs/commerce/payment/payum_integration.md index ced96ff989..c6fd3fa5e3 100644 --- a/docs/commerce/payment/payum_integration.md +++ b/docs/commerce/payment/payum_integration.md @@ -12,12 +12,12 @@ By configuring service gateways, mapping workflow actions and translating paymen ## 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 `` with a unique identifier for the payment service. +Replace `` with a unique identifier of the method provided by the payment service. ```yaml payum: gateways: - : + : factory: # Add specific configuration fields for the gateway credential_1: From 75d3971a7b68d2b36c901f2bf444804a50c3ea36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 19 Mar 2024 14:39:48 +0100 Subject: [PATCH 10/10] Typo fix --- docs/commerce/payment/payment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commerce/payment/payment.md b/docs/commerce/payment/payment.md index 2fcf60ab47..269ae27d96 100644 --- a/docs/commerce/payment/payment.md +++ b/docs/commerce/payment/payment.md @@ -8,7 +8,7 @@ edition: commerce 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. -Available payment method types : +Available payment method types: - offline – out of the box - online payment services – through [integration with Payum](payum_integration.md)