ACP-3507 APIs to enable projects embed payment elements to frontends based on Glue API

.gitignore

@@ -41,6 +41,7 @@ src/Generated/
 /src/Orm/Zed/
 tests/_data/app_payment_db
 /data/cache
+/data/DE/logs/ZED/propel.log
 
 # tools
 .phpstorm.meta.php

README.md

@@ -51,13 +51,13 @@ This plugin provides the routes for the AppPaymentBackendApi module.
 ###### Routes provided
 
 - /private/initialize-payment - Used from the Tenant side to initialize a payment.
-
+- /private/confirm-pre-order-payment - Used from the Tenant side to confirm pre-order payment after the order was persisted.
 
 ### AppKernel
-- \Spryker\Glue\AppPaymentBackendApi\Plugin\AppKernel\PaymentConfigurationValidatorPlugin
+- \Spryker\Zed\AppPayment\Communication\Plugin\AppKernel\ConfigurePaymentMethodsConfigurationAfterSavePlugin
 - \Spryker\Zed\AppPayment\Communication\Plugin\AppKernel\DeleteTenantPaymentsConfigurationAfterDeletePlugin
 - \Spryker\Zed\AppPayment\Communication\Plugin\AppKernel\SendAddPaymentMethodMessageConfigurationAfterSavePlugin
-- \Spryker\Zed\AppPayment\Communication\Plugin\AppKernel\SendDeletePaymentMethodMessageConfigurationAfterDeletePlugin
+- \Spryker\Zed\AppPayment\Communication\Plugin\AppKernel\SendDeletePaymentMethodMessagesConfigurationAfterDeletePlugin
 
 ### AppWebhook
 - \Spryker\Zed\AppPayment\Communication\Plugin\AppWebhook\PaymentWebhookHandlerPlugin
@@ -70,7 +70,44 @@ This plugin provides the routes for the AppPaymentBackendApi module.
 ### MessageBrokerAws
 - \Spryker\Zed\AppPayment\Communication\Plugin\MessageBrokerAws\ConsumerIdHttpChannelMessageReceiverRequestExpanderPlugin
 
-### Configure the MessageBroker
+## Extensions
+
+- \Spryker\Zed\AppPayment\Dependency\Plugin\AppPaymentPlatformMarketplacePluginInterface
+- \Spryker\Zed\AppPayment\Dependency\Plugin\AppPaymentPlatformPaymentMethodsPluginInterface
+- \Spryker\Zed\AppPayment\Dependency\Plugin\AppPaymentPlatformPaymentPagePluginInterface
+- \Spryker\Zed\AppPayment\Dependency\Plugin\AppPaymentPlatformPluginInterface
+- \Spryker\Zed\AppPayment\Dependency\Plugin\AppPaymentPlatformPreOrderPluginInterface
+- \Spryker\Zed\AppPayment\Dependency\Plugin\PaymentTransmissionsRequestExtenderPluginInterface
+
+### AppPaymentPlatformMarketplacePluginInterface
+
+You can implement this plugin when your PSP App supports Marketplace capabilities.
+
+### AppPaymentPlatformPaymentMethodsPluginInterface
+
+This plugin must be implemented to provide the payment methods that the PSP App supports.
+
+### AppPaymentPlatformPaymentPagePluginInterface
+
+This plugin can be implemented to provide a payment page that the PSP App supports. This is only needed when using the redirect flows after the order was created.
+
+### AppPaymentPlatformPluginInterface
+
+This is the root plugin which must be implemented to provide the PSP App capabilities from the project level.
+
+### AppPaymentPlatformPreOrderPluginInterface
+
+This plugin can be implemented to provide the pre-order capabilities that the PSP App supports.
+
+When using the pre-order payment flow, the InitializePayment API endpoint is used before the order gets persisted and it returns the needed data for an headless approach to add the payment page on project side. Usually, this is done via a provided JavaScript that is send to the frontend in the InitializePayment API call response.
+
+On project side the customer than makes the Payment via the provided JavaScripts and the payment page provided by the PSP provider. After the order is persistzed on the project side a call to the ConfirmPreOrderPayment API endpoint is made to confirm the payment and connect it with the orderReference.
+
+### PaymentTransmissionsRequestExtenderPluginInterface
+
+This plugin can be implemented to extend the request data that is send to the PSP App when doing payouts to Merchants. This is usually only needed when the PSP App supports Marketplace capabilities.
+
+## Configure the MessageBroker
 
 Add this to your project configuration:
 
@@ -89,8 +126,10 @@ $config[MessageBrokerAwsConstants::MESSAGE_TO_CHANNEL_MAP] = [
     CapturePaymentTransfer::class => 'payment-commands',
     RefundPaymentTransfer::class => 'payment-commands',
     AddPaymentMethodTransfer::class => 'payment-method-commands',
+    UpdatePaymentMethodTransfer::class => 'payment-method-commands',
     DeletePaymentMethodTransfer::class => 'payment-method-commands',
     PaymentCreatedTransfer::class => 'payment-events',
+    PaymentUpdatedTransfer::class => 'payment-events',
     // App event
     AppConfigUpdatedTransfer::class => 'app-events',
 ];
@@ -112,3 +151,105 @@ $config[MessageBrokerAwsConstants::CHANNEL_TO_RECEIVER_TRANSPORT_MAP] = [
     'payment-commands' => MessageBrokerAwsConfig::SQS_TRANSPORT,
 ];
 ```
+
+### Configure Payment Methods
+
+Each PSP implementation has different Payment Methods available. Through the `\Spryker\Zed\AppPayment\Dependency\Plugin\AppPaymentPlatformPaymentMethodsPluginInterface` you can provide the available Payment Methods.
+
+Each Payment Method can also have different configuration details.
+
+Add the plugin interface to your implementation and you can configure the payment methods.
+
+#### Payment Method default configuration
+
+This package adds endpoints to be used from the SCOS side to each of the configured Payment Methods. The default configuration for each Payment Method is:
+
+- The base URL - This is the URL that the SCOS side will use to call the PSP App.
+- Endpoints - The endpoints that the SCOS side will call on the PSP App.
+  - `authorization` - The endpoint to initialize a Payment, `/private/initialize-payment`
+  - `pre-order-confirmation` - The endpint to confirm a PreOrder payment,  `/private/confirm-pre-order-payment`
+  - `pre-order-cancellation` - The endpint to cancel a PreOrder payment,  `/private/cancel-pre-order-payment`
+  - `transfer` - The endpoint to transfer money to a Merchant, `/private/transfers`
+
+These are used on the SCOS side by their names. F.e. when the SCOS side wants to initialize a payment it will call the `authorization` endpoint on the PSP App.
+
+#### Payment Service Provider with only one Payment Method
+
+A simple example for a PSP with only one Payment Method could look like this:
+
+```
+public function configurePaymentMethods(PaymentMethodConfigurationRequestTransfer $paymentMethodConfigurationRequestTransfer): PaymentMethodConfigurationResponseTransfer
+{
+    $paymentMethodConfigurationResponseTransfer = new PaymentMethodConfigurationResponseTransfer();
+
+    $checkoutConfigurationTransfer = new CheckoutConfigurationTransfer();
+    $checkoutConfigurationTransfer->setStrategy('embedded');
+    $checkoutConfigurationTransfer->setScripts([
+        ...
+    ]);
+
+    $paymentMethodAppConfigurationTransfer = new PaymentMethodAppConfigurationTransfer();
+    $paymentMethodAppConfigurationTransfer
+        ->setCheckoutConfiguration($checkoutConfigurationTransfer);
+
+    $paymentMethodTransfer = new PaymentMethodTransfer();
+    $paymentMethodTransfer
+        ->setName('Foo')
+        ->setProviderName('Bar')
+        ->setPaymentMethodAppConfiguration($paymentMethodAppConfigurationTransfer);
+
+    $paymentMethodConfigurationResponseTransfer->addPaymentMethod($paymentMethodTransfer);
+
+    return $paymentMethodConfigurationResponseTransfer;
+}
+```
+
+Here we configure exactly one payment method. The payment method is named "Foo" and the provider is named "Bar". The Payment method also has a configuration that will be persisted on the SCOS side.
+
+The strategy is set to "embedded" which means that the payment page will be embedded in the SCOS checkout. The scripts are the scripts that are needed to embed and run the payment page in the SCOS checkout.
+
+This code runs when the PSP App gets configured. After this method call the so configured methods will be persisted on the App sides database, enriched with default configurations, and via the AddPaymentMethod message sent to the SCOS side.
+
+When the App gets reconfigured and a different number of Payment Methods are configured, the DeletePaymentMethod message will be sent to the SCOS side and the previously configured Payment Methods for the current Tenant will be deleted from the database.
+
+When the PaymentMethod configuration has changed the UpdatePaymentMethod message will be sent to the SCOS side.
+
+#### Payment Service Provider with multiple Payment Methods
+
+In case you have multiple payment methods, you can add multiple PaymentMethodTransfer objects to the PaymentMethodConfigurationResponseTransfer object. For this, you can get the AppConfigTransfer from the PaymentMethodConfigurationRequestTransfer. An example could look like this:
+
+```
+public function configurePaymentMethods(PaymentMethodConfigurationRequestTransfer $paymentMethodConfigurationRequestTransfer): PaymentMethodConfigurationResponseTransfer
+{
+    $appConfigTransfer = $paymentMethodConfigurationRequestTransfer->getAppConfig();
+
+    // Contains ['bar'] which was the only one selected through the configuration page
+    $configuredPaymentMethods = $appConfigTransfer->getPaymentMethods();
+
+    // These are all methods you can provide which are configurable through the AppStore Catalogs App configuration page
+    $availablePaymentMethods = [
+        'foo',
+        'bar',
+        'baz',
+    ];
+
+    $paymentMethodConfigurationResponseTransfer = new PaymentMethodConfigurationResponseTransfer();
+
+    foreeach ($availablePaymentMethods as $paymentMethodName) {
+        if (!isset($configuredPaymentMethods[$paymentMethodName])) {
+            continue;
+        }
+
+        $paymentMethodTransfer = new PaymentMethodTransfer();
+        $paymentMethodTransfer
+            ->setName($paymentMethodName)
+            ->setProviderName('PaymentProviderName');
+
+        $paymentMethodConfigurationResponseTransfer->addPaymentMethod($paymentMethodTransfer);
+    }
+
+    return $paymentMethodConfigurationResponseTransfer;
+}
+```
+
+In thie example you would get one PaymentMethod added to SCOS via the AddPaymentMethod message. The PaymentMethod is named "bar" and the provider is named "PaymentProviderName".

composer.json

@@ -4,16 +4,22 @@
     "description": "AppPayment module",
     "license": "proprietary",
     "require": {
-        "php": ">=8.1",
+        "php": ">=8.2",
+        "spryker/app-kernel": "^2.0.0",
+        "spryker/app-webhook": "dev-feature/acp-3507/acp-3746-persist-webhooks-and-allow-to-run-them-later as 1.1.0",
+        "spryker/event-dispatcher": "^1.6.0",
         "spryker/glue-application-extension": "^1.0.0",
+        "spryker/glue-backend-api-application": "^1.7.0",
+        "spryker/glue-json-api-convention": "^1.3.0",
         "spryker/kernel": "^3.30.0",
         "spryker/log": "^3.0.0",
         "spryker/message-broker": "^1.11.0",
+        "spryker/router": "^1.19.0",
         "spryker/symfony": "^3.0.0",
-        "spryker/transfer": "^3.33.0"
+        "spryker/transfer": "^3.33.0",
+        "spryker/translator": "^1.13.0"
     },
     "require-dev": {
-        "spryker/app-webhook": "^1.0.0",
         "codeception/codeception": "^5.0",
         "codeception/module-asserts": "^3.0.0",
         "codeception/module-cli": "^2.0.0",
@@ -22,27 +28,20 @@
         "codeception/module-rest": "^3.0.0",
         "codeception/module-webdriver": "^3.0.0",
         "codeception/phpunit-wrapper": "^9.0.0",
-        "galbar/jsonpath": "^3.0",
+        "galbar/jsonpath": "^3.0.0",
         "infection/codeception-adapter": "^0.4.3",
         "infection/infection": "^0.29.6",
         "phpstan/phpdoc-parser": "1.25.0",
         "phpstan/phpstan": "1.10.66",
         "rector/rector": "^0.19.0",
         "spryker-sdk/async-api": "dev-master as 0.3.1",
-        "spryker/app-kernel": "^1.0.0",
         "spryker/code-sniffer": "*",
-        "spryker/container": "*",
         "spryker/development": "^3.34.0",
-        "spryker/event-dispatcher": "^1.6",
-        "spryker/glue-backend-api-application": "*",
-        "spryker/glue-json-api-convention": "^1.3",
-        "spryker/http": "^1.11",
+        "spryker/http": "^1.11.0",
         "spryker/message-broker-aws": "*",
         "spryker/propel": "*",
-        "spryker/router": "^1.19",
         "spryker/testify": "*",
-        "spryker/testify-async-api": "*",
-        "spryker/translator": "^1.13"
+        "spryker/testify-async-api": "*"
     },
     "autoload": {
         "psr-4": {
@@ -66,7 +65,7 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "scripts": {
-        "setup": "tests/bin/console app-payment:setup && tests/bin/console transfer:generate && tests/bin/console transfer:databuilder:generate && tests/bin/console dev:ide-auto-completion:zed:generate && tests/bin/console dev:ide-auto-completion:glue:generate && tests/bin/console propel:install && vendor/bin/codecept build",
+        "setup": "tests/bin/console app-payment:setup && tests/bin/console transfer:generate && tests/bin/console transfer:databuilder:generate && tests/bin/console dev:ide-auto-completion:zed:generate && tests/bin/console dev:ide-auto-completion:glue:generate && tests/bin/console dev:ide-auto-completion:glue-backend:generate && tests/bin/console propel:install && vendor/bin/codecept build",
         "cs-check": "phpcs -p src/ tests/",
         "cs-fix": "phpcbf -p src/ tests/",
         "stan": "phpstan analyze src/Spryker/ --memory-limit=1G",

config/Shared/config_default.php

@@ -5,6 +5,7 @@
  */
 
 use Generated\Shared\Transfer\AddPaymentMethodTransfer;
+use Generated\Shared\Transfer\UpdatePaymentMethodTransfer;
 use Generated\Shared\Transfer\AppConfigUpdatedTransfer;
 use Generated\Shared\Transfer\CancelPaymentTransfer;
 use Generated\Shared\Transfer\CapturePaymentTransfer;
@@ -18,6 +19,7 @@
 use Generated\Shared\Transfer\PaymentCreatedTransfer;
 use Generated\Shared\Transfer\PaymentRefundedTransfer;
 use Generated\Shared\Transfer\PaymentRefundFailedTransfer;
+use Generated\Shared\Transfer\PaymentUpdatedTransfer;
 use Generated\Shared\Transfer\RefundPaymentTransfer;
 use Ramsey\Uuid\Uuid;
 use Spryker\Shared\AppKernel\AppKernelConstants;
@@ -149,8 +151,10 @@
     CapturePaymentTransfer::class => 'payment-commands',
     RefundPaymentTransfer::class => 'payment-commands',
     AddPaymentMethodTransfer::class => 'payment-method-commands',
+    UpdatePaymentMethodTransfer::class => 'payment-method-commands',
     DeletePaymentMethodTransfer::class => 'payment-method-commands',
     PaymentCreatedTransfer::class => 'payment-events',
+    PaymentUpdatedTransfer::class => 'payment-events',
     // App event
     AppConfigUpdatedTransfer::class => 'app-events',
 ];

phpcs.xml

@@ -36,4 +36,9 @@
         <exclude name="SlevomatCodingStandard.Classes.DisallowConstructorPropertyPromotion.DisallowedConstructorPropertyPromotion"/>
     </rule>
 
+    <!-- PHP 8.0 we will allow the null safe operator -->
+    <rule ref="SlevomatCodingStandard.ControlStructures.DisallowNullSafeObjectOperator">
+        <exclude name="SlevomatCodingStandard.ControlStructures.DisallowNullSafeObjectOperator"/>
+    </rule>
+
 </ruleset>

phpstan.neon

@@ -2,7 +2,3 @@ parameters:
     level: 8
     ignoreErrors:
           - '#Call to an undefined method Spryker\\Shared\\Kernel\\Transfer\\AbstractTransfer::getMessageAttributesOrFail\(\)#'
-          - '#Call to method appPayment\(\) on an unknown class Generated\\GlueBackend\\Ide\\AutoCompletion.#'
-          - '#Call to an undefined method Spryker\\Zed\\AppPayment\\Dependency\\Plugin\\AppPaymentPlatformPluginInterface::transferPayments\(\).#'
-          - '#Method Spryker\\Zed\\AppPayment\\Business\\Payment\\AppConfig\\AppConfigLoader::loadAppConfig\(\) should return Generated\\Shared\\Transfer\\AppConfigTransfer but returns Spryker\\Shared\\Kernel\\Transfer\\TransferInterface.#'
-          - '#Method Spryker\\Zed\\AppKernel\\Business\\AppKernelFacadeInterface::getConfig\(\) invoked with 2 parameters, 1 required.#'

rector.php

@@ -47,12 +47,14 @@
             __DIR__ . '/src/Spryker/Glue/AppPaymentBackendApi/Dependency/Facade/AppPaymentBackendApiToAppPaymentFacadeBridge.php',
             __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Facade/AppPaymentToAppKernelFacadeBridge.php',
             __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Facade/AppPaymentToMessageBrokerFacadeBridge.php',
+            __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Facade/AppPaymentToAppWebhookFacadeBridge.php',
             __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Service/AppPaymentToUtilEncodingServiceBridge.php',
         ],
         AddParamTypeFromPropertyTypeRector::class => [
             __DIR__ . '/src/Spryker/Glue/AppPaymentBackendApi/Dependency/Facade/AppPaymentBackendApiToAppPaymentFacadeBridge.php',
             __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Facade/AppPaymentToAppKernelFacadeBridge.php',
             __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Facade/AppPaymentToMessageBrokerFacadeBridge.php',
+            __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Facade/AppPaymentToAppWebhookFacadeBridge.php',
             __DIR__ . '/src/Spryker/Zed/AppPayment/Dependency/Service/AppPaymentToUtilEncodingServiceBridge.php',
         ],
     ]);