Integrate Unzer Glue API

Last updated:
Edit on GitHub

This document describes how to integrate Unzer Glue API into a Spryker project.

Install feature core

Follow the steps below to install the Unzer Glue API feature core.

Prerequisites

Install the required features:

NAME INSTALLATION GUIDE
Unzer Unzer feature integration
Glue API: Checkout Install the Checkout Glue API
Glue API: Payments Install the Payments Glue API

1) Install the required modules

Install the required modules using Composer:

composer require spryker-eco/unzer-rest-api
Verification

Make sure the following modules have been installed:

MODULE EXPECTED DIRECTORY
UnzerRestApi vendor/spryker-eco/unzer-rest-api

2) Set up configuration

Put all the payment methods available in the shop to PaymentsRestApiConfig:

src/Pyz/Glue/PaymentsRestApi/PaymentsRestApiConfig.php

<?php

namespace Pyz\Glue\PaymentsRestApi;

use Spryker\Glue\PaymentsRestApi\PaymentsRestApiConfig as SprykerPaymentsRestApiConfig;
use SprykerEco\Shared\Unzer\UnzerConfig;

class PaymentsRestApiConfig extends SprykerPaymentsRestApiConfig
{
    /**
     * @var array<string, int>
     */
    protected const PAYMENT_METHOD_PRIORITY = [
        UnzerConfig::PAYMENT_METHOD_KEY_CREDIT_CARD => 1,
        UnzerConfig::PAYMENT_METHOD_KEY_SOFORT => 2,
        UnzerConfig::PAYMENT_METHOD_KEY_BANK_TRANSFER => 3,
    ];

     /**
     * @var array<string, array<string, array<string>>>
     */
    protected const PAYMENT_METHOD_REQUIRED_FIELDS = [
        UnzerConfig::PAYMENT_PROVIDER_NAME => [
            UnzerConfig::PAYMENT_METHOD_KEY_CREDIT_CARD => [
                'unzerPayment.paymentResource.id',
            ],
            UnzerConfig::PAYMENT_METHOD_KEY_SOFORT => [
                'unzerPayment.paymentResource.id',
            ],
        ],
    ];
}
Verification

Make sure that calling Pyz\Zed\Payment\PaymentConfig::getSalesPaymentMethodTypes() returns an array of the payment methods available in the shop grouped by the payment provider.

3) Set up transfer objects

Generate transfers:

console transfer:generate
Verification

Ensure the following transfers have been created:

TRANSFER TYPE EVENT PATH
RestCheckoutData class created src/Generated/Shared/Transfer/RestCheckoutDataTransfer
Quote class created src/Generated/Shared/Transfer/QuoteTransfer
UnzerCredentials class created src/Generated/Shared/Transfer/UnzerCredentialsTransfer
UnzerKeypair class created src/Generated/Shared/Transfer/UnzerKeypairTransfer
RestCheckoutDataResponseAttributes class created src/Generated/Shared/Transfer/RestCheckoutDataResponseAttributesTransfer
CheckoutResponse class created src/Generated/Shared/Transfer/CheckoutResponseTransfer
CheckoutData class created src/Generated/Shared/Transfer/CheckoutDataTransfer
RestCheckoutRequestAttributes class created src/Generated/Shared/Transfer/RestCheckoutRequestAttributesTransfer
RestPayment class created src/Generated/Shared/Transfer/RestPaymentTransfer
RestUnzerPayment class created src/Generated/Shared/Transfer/RestUnzerPaymentTransfer
UnzerPaymentResource class created src/Generated/Shared/Transfer/UnzerPaymentResourceTransfer

4) Set up behavior

Enable the following behaviors by registering the plugins:

PLUGIN SPECIFICATION PREREQUISITES NAMESPACE
UnzerCheckoutDataResponseMapperPlugin Maps RestCheckoutDataTransfer.unzerCredentials.unzerKeypair.publicKey to RestCheckoutDataResponseAttributesTransfer.unzerPublicKey while RestCheckoutDataTransfer.unzerCredentials is specified. None SprykerEco\Glue\UnzerRestApi\Plugin\CheckoutRestApi
UnzerCheckoutDataExpanderPlugin Expands the RestCheckoutDataTransfer.quote transfer property with UnzerCredentialsTransfer according to added items. None SprykerEco\Zed\UnzerRestApi\Communication\Plugin\CheckoutRestApi
UnzerNotificationResource Adds Unzer notification resource. None SprykerEco\Glue\UnzerRestApi\Plugin\GlueJsonApiConventionExtension

src/Pyz/Glue/CheckoutRestApi/CheckoutRestApiDependencyProvider.php

namespace Pyz\Glue\CheckoutRestApi;

use Spryker\Glue\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use SprykerEco\Glue\UnzerRestApi\Plugin\CheckoutRestApi\UnzerCheckoutDataResponseMapperPlugin;

class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
    /**
     * @return array<\Spryker\Glue\CheckoutRestApiExtension\Dependency\Plugin\CheckoutDataResponseMapperPluginInterface>
     */
    protected function getCheckoutDataResponseMapperPlugins(): array
    {
        return [
            new UnzerCheckoutDataResponseMapperPlugin(),
        ];
    }
}

src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiDependencyProvider.php

namespace Pyz\Zed\CheckoutRestApi;

use Spryker\Zed\CheckoutRestApi\CheckoutRestApiDependencyProvider as SprykerCheckoutRestApiDependencyProvider;
use SprykerEco\Zed\UnzerRestApi\Communication\Plugin\CheckoutRestApi\UnzerCheckoutDataExpanderPlugin;

class CheckoutRestApiDependencyProvider extends SprykerCheckoutRestApiDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\CheckoutRestApiExtension\Dependency\Plugin\CheckoutDataExpanderPluginInterface>
     */
    protected function getCheckoutDataExpanderPlugins(): array
    {
        return [
            new UnzerCheckoutDataExpanderPlugin(),
        ];
    }
}

src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php

namespace Pyz\Glue\GlueStorefrontApiApplication;

use Spryker\Glue\GlueStorefrontApiApplication\GlueStorefrontApiApplicationDependencyProvider as SprykerGlueStorefrontApiApplicationDependencyProvider;
use SprykerEco\Glue\UnzerRestApi\Plugin\GlueJsonApiConventionExtension\UnzerNotificationResource;

class GlueStorefrontApiApplicationDependencyProvider extends SprykerGlueStorefrontApiApplicationDependencyProvider
{
    /**
     * @return array<\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceInterface>
     */
    protected function getResourcePlugins(): array
    {
        return [
            new UnzerNotificationResource(),
        ];
    }
}
Verification

Ensure that the following API requests work:

  1. Create a cart by sending the POST https://glue.mysprykershop.com/carts.
  2. Add at least one item to the cart by sending POST https://glue.mysprykershop.com//items.
  3. Check result by sending the POST https://glue.mysprykershop.com/checkout-data?include=payment-methods request.

Request Example:

{
  "data":
  {
    "type": "checkout-data",
    "attributes":
    {
      "idCart": "",
      "payments": [
        {
          "paymentMethodName": "Unzer Sofort",
          "paymentProviderName": "Unzer"
        }
      ]
    }
  }
}
Verification

Ensure that the request body differs for each Unzer payment method:

  • Property paymentMethodName of payments must be replaced by the used method—for example, Unzer Sofort or Unzer Credit Card.
  • Property paymentResource of payments is not required for Unzer Sofort, Unzer Marketplace Sofort, and Unzer Bank Transfer.
Response example: 
{
  "data": {
    "type": "checkout-data",
    "id": null,
    "attributes": {
      "unzerPublicKey": "string",
      ...
    },
    "links": {
      "self": "https://glue.mysprykershop.com/checkout-data?include=payment-methods"
    },
    "relationships": {
      "payment-methods": {
        "data": [
          {
            "type": "payment-methods",
            "id": "1"
          }
        ]
      }
    },
    ...
  },
  "included": [
    {
      "type": "payment-methods",
      "id": "1",
      "attributes": {
        "paymentMethodName": "Unzer Sofort",
        "paymentProviderName": "Unzer",
        "priority": 1,
        "requiredRequestData": [
          "paymentMethod",
          "paymentProvider",
          "unzerPayment.paymentResource.id"
        ]
      },
      "links": {
        "self": "https://glue.mysprykershop.com/payment-methods/1"
      }
    },
    ...
  ]
}
  1. Check result by sending the POST https://glue.mysprykershop.com/checkout request.

Request example:

{
  "data": {
    "type": "checkout",
    "attributes": {
      "idCart": "",
      "payments": [
        {
          "paymentMethodName": "Unzer Credit Card",
          "paymentProviderName": "Unzer",
          "paymentSelection": "unzerCreditCard",
          "unzerCreditCard": {
            "paymentResource": {
              "id": ""
            }
          },
          "amount": ""
        }
      ],
      ...
    }
  }
}
Verification

Ensure that the request body differs for each Unzer payment method:

  • Property paymentMethodName of payments must be replaced by the used method—for example, Unzer Sofort or Unzer Credit Card.
  • Property paymentResource of payments is not required for Unzer Sofort, Unzer Marketplace Sofort, and Unzer Bank Transfer.
  • Property paymentSelection of payments has to be replaced by used method—for example, unzerSofort, unzerCreditCard, or unzerMarketplaceCreditCard.

Response example:

{
    "data": {
        "type": "checkout",
        "id": null,
        "attributes": {
            "redirectUrl": "https://payment.unzer.com/v1/redirect/3ds/",
            "isExternalRedirect": true,
            ...
        },
        "links": {
            "self": "https://glue.mysprykershop.com/checkout"
        }
    }
}