# SAP Commerce Cloud SAP Commerce Cloud Connector integrates seamlessly with the SAP B2C Accelerator. The Connector for SAP Commerce Cloud (formerly Hybris) enables you to implement a global payment strategy through a single integration in a secure, compliant, and unified approach. We currently support: - SAP CC 1905, 2005, 2011, 2105, 2205, and 2211, including B2C Accelerator - SAP Spartacus 3.2 front end with server-side rendering (SSR) support, which is compatible with SAP CC 1905, 2005, and 2011 - SAP Spartacus 4.2 front end with SSR support, which is compatible with SAP CC 2011 and later This guide explains how to integrate with our plugin. --- ## Supported features - All available payment methods supported by Flow. See [Supported Payment Methods](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website.md#Supported_payment_methods) for more information. - SAP Commerce Fulfillment process – With our APIs for authorization, capture, refund and void. The same functionality has been brought onto our Spartacus v3.2 storefront connector. - SAP Commerce Backoffice – The connector provides specific customizations for the back office to ease the administration, configuration and management of all the operations related to the integration with our payment solution. - 3DS 2.0 (PSD2) – In case of a non-frictionless interaction, the user must enter additional information related to Strong Customer Authentication (SCA). - SAP Web Content Management System (WCMS) – The connector enables business users to add cards and alternative payment methods using CMS components. - Express checkout – One-click payments with Apple Pay and Google Pay from the Product details page and Cart page. - Co-branded cards – Full support for co-branded cards like Cartes Bancaires. - Level 2 or Level 3 Data – If you provide Level 2 or Level 3 data with your transactions, you may qualify for reduced interchange rates. Cardholders also benefit from the additional data, as they receive more detailed transaction information in their card statements. --- ## Before you start ### Create a test account If you haven't already, [create a test account with us](https://www.checkout.com/get-test-account). ### Get your API keys To set up our SAP CC plugin, you'll need four API keys: a secret key, a public key, a signature key, and an authorization header key. You can create your [secret and public keys](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) in the [Dashboard](https://dashboard.checkout.com?fromURI=www.checkout.com). The signature key and authorization header key are generated when you create a webhook for your business. --- ## Install the plugin 1. [Download the latest Checkout.com SAP Commerce Cloud Connector](https://www.sap.com/products/crm/partners/checkout-technology-ltd-checkoutcom-payments-for-sap-commerce-cloud.html). This contains the installer recipes and connector extensions. 2. Unzip the Connector .zip file. 3. Copy the extracted folders to the `HYBRIS_ROOT` of your Hybris installation. 4. Remove the SAP Commerce fulfillment extension `yacceleratorfulfilmentprocess` from `localextensions.xml`, because the connector handles the fulfillment using the `checkoutfulfilmentprocess` extension. 5. Run the `ant clean` command from your Hybris `bin/platform` directory. 6. Edit your `localextensions.xml` and add the following: ```html ``` The extensions do not rely on any absolute paths, so you can place the extensions in a different location, such as `${HYBRIS_BIN_DIR}/custom`. 7. Run the following commands to install the add-ons to `yaccelatorstorefront`. You can replace `yaccelatorstorefront` with your custom storefront. ``` ant addoninstall -Daddonnames="checkoutaddon" DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront" ``` ### Add our sample data add-on (optional) Our optional sample data add-on allows you to add fields to the checkout page, which can be used to gather information from your customers or upsell services and products. 1. Run the following code: ``` ant addoninstall -Daddonnames="checkoutsampledataaddon" -DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront" ``` 2. Run the `ant clean all` command from your Hybris bin/platform directory. 3. Run the `hybrisserver.sh` command to start up the Hybris server. 4. Update your running system using `ant updatesystem`. After setting up the hosts file, the connector will work initially without any external setup needed, because our sample data add-on will provide all the required data for the accelerator’s electronics and apparel stores. The add-ons are independent and can be installed on separate server instances. ### Install the add-on using the provided recipes The add-on comes with one Gradle recipe to be used with the Hybris installer. The recipe is `b2c_acc_plus_checkout_com` with b2c and Checkout.com functionality, and it is based on the `b2b_acc_plus` recipes provided by Hybris. The recipe generates the `local.properties` file with the properties defined in the recipe. You can choose to add this file to the `customconfig` folder. To install the add-on using one of the recipes detailed in that folder, run the following commands: ```bash HYBRIS_HOME/installer$ ./install.sh -r [RECIPE_NAME] setup HYBRIS_HOME/installer$ ./install.sh -r [RECIPE_NAME] initialize HYBRIS_HOME/installer$ ./install.sh -r [RECIPE_NAME] start ``` --- ## Configure the global settings of the plugin Our SAP Commerce Cloud Connector supports multiple Checkout.com channels, where a different website is connected to each channel. If you have multiple websites running on SAP Commerce Cloud, you can have a different configuration for each one and keep the payment transaction separate. 1. In the _Secret keys_ tab, set _Use NAS_ to _True_, and enter your public key, secret key, signature key, and authorization header key in the corresponding fields. When you enter your secret key, it must contain the `Bearer` prefix. 2. Set _Use NAS Authorisation Header key_ and _Use NAS Signature key_ to _True_. 3. In the _Global Settings_ tab, set the environment to _Test_, so you can start testing payments. You'll need to change this to _Production_ when you're ready to go live. 4. Select the _Payment Action_: - The _Authorize and Capture_ option means that the charge is authorized and captured (that is, the money due from the customer's account is moved into your account) at the same time. - The _Authorize_ option will only authorize the charge. You'll have to capture the payment manually. 5. Set the following fields according to your preference: - _Review transactions at risk_: If set to _True_, payment events coming from Checkout.com that have the risk flag set to `true` will be created with transaction status _REVIEW_. Otherwise, the payment status will be _ACCEPTED_. - _Authorization amount validation threshold_: This field is used to determine whether the authorization amount reflects the value of the order. The threshold is the allowed difference in the amounts that may exist due to the way the amounts are calculated. Increase it if you observe false positives in your integration. - _Billing descriptor_: If set to _True_, the payment requests made will contain the billing descriptor name and city you have specified. Otherwise, no billing descriptor will be sent. ### Subscribe to webhooks We send payment events for all webhooks configured in the Dashboard. Create at least one webhook per environment pointing to the webhook event receiver. See [Receive webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks.md) for more information. The connector requires the following events to be sent: - `payment_approved` - `payment_pending` - `payment_declined` - `payment_expired` - `payment_canceled` - `payment_voided` - `payment_void_declined` - `payment_captured` - `payment_capture_declined` - `payment_refunded` - `payment_refund_declined` This reflects your `checkoutComPaymentEventTypes` configuration property. If the webhook in the Dashboard sends more events, the event receiver will ignore them. To set up your webhooks, start by creating them in the Dashboard: 1. Sign in to the [Dashboard](https://dashboard.checkout.com). 2. Go to _Developers_ > _Webhooks_. 3. Select _Create configuration_. 4. Enter a name for your webhook. 5. Set up your endpoint URL, using the following example: `https://:/checkoutevents/receive-event`. 6. Generate an _Authorization Header Key_ and a _Signature Key_. 7. Copy and store both values. 8. Select all _Gateway_ type events. 9. Select the entity that you want to generate the webhooks for. 10. Select _Create webhook_. In your SAP Commerce Cloud's Administration Cockpit: 1. In the left-side navigation menu, select _Checkout.com_ > _Merchant Configuration_, and select the storefront that you want to configure the webhooks endpoint for. 2. Locate the _Secret Keys_ section, and add the _Authorization Header key_ and _Signature Key_ values you copied earlier. 3. Select _Save_. --- ## Extend your configuration There are a number of ways you can extend your SAP Commerce Cloud integration to suit your business needs. In this section, you'll learn how to: - [Enable 3D Secure payments](#Enable_3D_Secure_payments) - [Enable Apple Pay](#Enable_Apple_Pay) - [Enable Google Pay](#Enable_Google_Pay) ### Additional payment methods > **Information** > > To start accepting an alternative payment method, we first need to enable it on your account. Contact your account manager or our [Sales team](https://checkout.com/contact-sales) to get started. We currently support the following payment methods on SAP CC: - [Apple Pay](https://www.checkout.com/docs/payments/payment-methods/apple-pay.md) - [Bancontact](https://www.checkout.com/docs/payments/payment-methods/bancontact.md) - [EPS](https://www.checkout.com/docs/payments/payment-methods/electronic-payment-standard-eps.md) - [Google Pay](https://www.checkout.com/docs/payments/payment-methods/google-pay.md) - [iDEAL](https://www.checkout.com/docs/payments/payment-methods/ideal.md) - [KNET](https://www.checkout.com/docs/payments/payment-methods/knet.md) - [PayPal](https://www.checkout.com/docs/payments/payment-methods/paypal.md) - [Przelewy24](https://www.checkout.com/docs/payments/payment-methods/przelewy24.md) - [QPay](https://www.checkout.com/docs/payments/payment-methods/qpay.md) - [Sofort](https://www.checkout.com/docs/payments/payment-methods/sofort.md) Check the individual payment method pages to see which ones you can support. Availability will depend on your location, as well as your customer's billing address and currency. ### Enable Apple Pay 1. Sign in to your SAP CC Administration Console and go to _Apple Pay Payments > ApplePay Configuration_. 2. Enter your merchant name. 3. Enter your merchant ID. You can find this in your Apple Developer account. 4. Enter your [two-letter country code](https://www.checkout.com/docs/resources/codes/country-codes.md). 5. Select which payment capabilities you want to support. Read the [Apple documentation](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/merchantcapabilities) for more information. 6. Select the payment networks you wish to support. Read the [Apple documentation](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/supportednetworks) for more information. 7. Enter the private key from your merchant identity certificate. You can find this in the contents of the `.key` file in your Apple Developer account. 8. Enter the public key from your merchant identity certificate. You can find this in the contents of the `.pem` file in your Apple Developer account. See our [Apple Pay documentation](https://www.checkout.com/docs/payments/payment-methods/apple-pay.md) for more information. ### Enable Google Pay 1. Sign in to your SAP CC Administration Console and go to _Google Pay Payments > GooglePay Configuration_. 2. Select which card networks you want to support through Google Pay with the allowed card networks setting. See [Google's documentation](https://developers.google.com/pay/api/web/guides/tutorial#supported-card-networks) for more information. 3. Select which card authorization methods you want to support through Google Pay with the allowed card authentication methods setting. See [Google's documentation](https://developers.google.com/pay/api/web/guides/tutorial#supported-card-networks) for more information. 4. Select the environment used for processing payments – either _Test_ or _Production_. This is not the same as the Checkout.com environment setting. 5. The payment gateway defines which gateway Google Pay uses. This should be left as `checkoutltd`. 6. Enter your gateway merchant ID. You can find it in your [Dashboard](https://dashboard.checkout.com) account. 7. Enter your merchant name. 8. Enter your merchant identifier. You can find this in your Google payments profile. 9. Set _Type_ to _CARD_. This defines the payment methods supported by Google Pay. See our [Google Pay documentation](https://www.checkout.com/docs/payments/payment-methods/google-pay.md) for more information. ### Payment method configuration The availability of the payment methods in SAP Commerce Cloud is defined by three attributes: | Attribute | Description | | --- | --- | | CMS Component | For a payment method to be visible, the CMS component related to the payment needs to be added to the _CheckoutComPaymentButtonsSlot_ content slot. If you have multiple sites, the payment should be added for each site.

Any payment methods that are not globally accepted by the merchant should not be added to the CMS component, regardless of the customer’s shipping or billing country. | | Billing Country | Card payments are available for all countries.

You can choose to make other payment methods available only for specific billing countries by supplying them in the list. Countries excluded from the list will not be able to use the alternative payment methods.

If the list is empty, no country restrictions are applied. | | Currency | Card payments do not have any currency restrictions applied.

You can choose to make other payment methods available only for specific currencies by supplying them in the list. Currencies excluded from the list will not be able to use the alternative payment methods.

If the list is empty, no currency restrictions are applied. | ### Enable 3D Secure payments 1. Go to card payments. 2. If you want to process all payments as 3D Secure (3DS) payments, set _Use 3D Secure_ to _True_. 3. Select whether you want to attempt non-3D Secure transactions. If you select _True_, any cards that do not support 3DS will go through without a 3DS check. If you select _False_, cards that do no support 3DS will be blocked. This add-on is compliant with the 3DS 2.0 (PSD2) directive. In case of a non-frictionless interaction, where a customer is required to enter additional information related to Strong Customer Authentication (SCA), the customer will be sent to our hosted solution page. Read our [3DS documentation](https://www.checkout.com/docs/risk-management/3d-secure.md) for more information. --- ## Enhanced Level 2 or Level 3 data (US only) The following tables show the checkout fields which you should map each commerce field to. Use the [eligibility criteria](https://www.checkout.com/docs/payments/manage-payments/enhanced-scheme-data/submit-level-2-or-level-3-data.md#Interchange_reduction_(US_only)) to integrate this feature with the connector. ### Enhanced Level 2 data | Commerce field | Additional parameters | Description | Checkout field | | --- | --- | --- | --- | | `customer/taxNumber` | Not applicable | The customer's VAT registration number, as a 13-character `string` value | `customer.tax_number` | | `Incl. Tax` | Not applicable | The taxes calculated for the full order | `processing.tax_amount` | | `paymentReference` | `order/paymentReference` | The invoice number, as a 15-character `string` value | `processing.order_id` | ### Enhanced Level 3 data | Commerce field | Additional parameters | Description | Checkout field | | --- | --- | --- | --- | | `Article Number` | `order/entries/product/code` | The code identifying a commodity for VAT purposes, as a 12-character `string` value | `items[].commodity_code` | | `Article Number` | `order/entries/product/code` | The SAP Commerce product code | `items[].reference` | | `Delivery Address` | `cart/deliveryAddress/Country/isocode` | The shipping address country, as a two-character `string` value (ISO alpha-2 code) | `shipping.address.country` | | `Delivery Address` | `cart/deliveryAddress/postalCode` | The shipping address ZIP code or post code, as a 10-character `string` value. | `shipping.address.zip` | | `Delivery Cost` | `cart/deliveryCost` | The cost of shipping the order | `processing.shipping_amount` | | `Discounts` | `cart/totalDiscounts` | The discount applied to the whole order | `processing.discount_amount` | | `Identifier` | `order/entries/product/name`
(localized attribute) | The cart entry’s product name, translated to the customer’s session language, as a 26-character `string` value | `items[].name` | | `Incl. Tax` | The sum of all tax values of the particular `orderEntry` object | The added tax for the cart entry | `items[].tax_amount` | | `Line item discount` | The sum of all discount values for the particular entry | The discount applied to the cart entry | `items[].discount_amount` | | `Line item Quantity` | `order/entries/quantity` | The quantity of the cart entry, which must be greater than `0` | `items[].quantity` | | `Line item total price` | `entry/totalPrice` | The total cost of the cart entry | `items[].total_amount` | | `Unit of Measure` | `entry/unit/code` | The product’s unit of measure code, as a 12-character `string` value | `items[].unit_of_measure` | | `Unit Price` | `entry/basePrice` | The product cost per each individual unit | `items[].unit_price` | | `[Custom field]` | `customer/dutyAmount` | The charges involved in the import or export duty for the order | `processing.duty_amount` | | `[Custom field]` | Not applicable | The total tax applied to the order shipping costs (including shipping, duties, and handling charges) | `processing.shipping_tax_amount` | | `[Custom field]` | Not applicable | The ZIP code or post code from where the order will be shipped, as a 10-character `string` value. | `shipping.from_address_zip` | > **Information** > > If you're a system integrator, refer to our [interchange reduction](https://www.checkout.com/docs/payments/manage-payments/enhanced-scheme-data/submit-level-2-or-level-3-data.md#Interchange_reduction_(US_only)) content to ensure the correct eligibility rules are applied when processing payments.