How to integrate SAP Digital Payments Add-On into a non-SAP e-commerce solution

[christian_noack]

My client plans to use a variety of digital payment options within a non-SAP e-commerce solution. Some of which will be region specific. SAP Digital Payments Add-On was selected to streamline implementation on both sides: authorization of payments within the e-commerce solution and capturing in S/4HANA.

SAP provides documentation and a library to integrate non SAP ecommerce solutions with DPA, which we will explore.

Overview

SAP Digital Payments Add-On

With SAP Digital Payments Add-On (DPA), SAP offers a SaaS cloud product to securely and efficiently process digital payment transactions. From an integration point of view it serves as a gateway between any consumer application and a variety of participating payment service providers (PSP) without having the hazzle to setup numerous direct integrations in e.g. your e-commerce solution or S/4HANA backend. SAP DPA ensures that transactions are processed PCI compliant.

SAP digital payments add-on context view © help.sap.com

The integration with SAP Commerce Cloud uses other APIs than those recommended for Non-SAP Applications. It is limited to credit card processing and accesses these APIs directly.

Hosted Payment Page

As of March 2024, integration via the hosted payment page is no longer recommended by stripe. Ask your stripe or SAP contact for the best approach.

Among the different integration options of PSP and e-commerce, Hosted Payment Pages are often utilized to lower implementation efforts and leave as much complexity to the PSP as possible. DPA comes with a configurable hosted payment page where the user can enter payment details. Note, this is not the payment page of the actual PSP.

Payment Page Context View © by help.sap.com

If you integrate the payment page of your payment service provider, you will still need to submit these payments to DPA separately in order to benefit from e.g. S/4HANA integration. I recommend using the DPA hosted payment page to avoid that.

E-commerce Integration with the Hosted Payment Page

With the hosted payment page, a user typically navigates the storefront during checkout like this:

User flow with only one DPA payment method available

In a first step the user chooses if he wants to pay with a DPA or a non DPA payment method. If the user chooses to pay with DPA, I skip the payment selection offered by DPA. I only implemented credit card and automatically select this method for the user. The user will then see a button to pay with credit card.

Payment Details Dialog

When the user clicks that "Payment Card" button, a new window or tab opens. There the user can enter payment details. After the user confirms the details, the window closes and a storefront callback is triggered.

DPA Hosted Payment Page for Card Payment

The hosted payment page is currently not customizable for storefront integration. You can configure the displayed fields, but that only applies when used in a S/4HANA context.

Setting up SAP Digital Payment Add-On

You need to setup the add-on with a stripe configuration and a payment page configuration. For that you will also need a stripe account. I used stripe for all my testing, since the DPA to Magnius Integration was still in the certification phase. My client opted for Magnius as they offer huge amounts of connected PSPs and payment cost reduction features.

Integrating a non SAP e-commerce solution

Base Urls for accessing the APIs

From the setup of the Machine 2 Machine communication, you will receive a json service key containing the required information to authenticate and connect to the DPA APIs.

{
  "uri": https://digitalpayments-demo-core.cfapps.eu10.hana.ondemand.com, // API URL
  "uaa": {
   "credential-type": "instance-secret",
    "clientid": "sb-44444444444444444444444444444444444444444444|digitalpayments-demo-m2m!b16",
    "clientsecret": "aaaaaaaaaaaaaaaaaaaaaaaaaaa=",
    "url": https://<your-namespace>.authentication.eu10.hana.ondemand.com, // OAuth URL
    "apiurl": doNotUseThisOne,
  }
}

Authenticate first via the uaa.url and then send requests to uri.

Url for Auth request:

https://<your-namespace>.authentication.eu10.hana.ondemand.com/oauth/token

Sample url for an API request:

https://digitalpayments-demo-core.cfapps.eu10.hana.ondemand.com/core/v1/dpjslib/loader

Implementation

System Setup

As of March 2024, integration via the hosted payment page and DPJSLIB is no longer recommended by stripe. Ask your stripe or SAP contact for the best approach.

To initiate a payment session with SAP DPA, you will need to perform several requests to load a JavaScript library provided by SAP DPA called DPJSLIB. Vue.js and Axios are well-suited for meeting these requirements.

Capabilities of DPJSLIB

• Renders the payment button for the selected payment method into the storefront.
• Opens the DPA hosted payment page and manages inter window communication between the storefront browser window and the DPA hosted payment page browser window.
• Triggers your callback when the user enters payment details and completes payment

The request for configuration to load DPJSLIB can only be triggered by a backend, due to the enforced CORS policies. To handle these requests, I opted to use Node.js and Axios

Here's an overview of my setup:

Simplified Communication Sequence

This sequence is simplified, the whole payment process includes quite some steps.

Call Sequence

The following diagram shows the full payment sequence. Starting from the storefront payment selection page and ending with the finalize payment call that the backend has to perform to get transaction details. If you need more details, you can always check out the POC code on github.

Full payment sequence

Additional Hints

• During implementation, I found it very helpful to log all responses from DPA.
• You will need the API Documentation for DPA Payment Page, which will be publicly available soon. In the meantime, please request it from your SAP Contact.
• At some point you will require the payment page id, which will be the name of the payment page:
  

• There are multiple instances where you'll need to handle potential errors, particularly after each remote call.
  
  

Exporting authorized orders to S/4HANA

Upon the user submitting payment credentials, I create an order in the shop backend and attach the details of the authorized payment. The finalize payment call provides the relevant details.

Smplified finalize payment response:

{
  Authorization: {
    AuthorizationByDigitalPaytSrvc: 'ABCDEFGHIJ',
  },
  Source: {
    Card: {
      PaytCardByDigitalPaymentSrvc: 'AAAAAAAAAAAAAAAAAAAAAAAA'
    },
  },
}

Even when I am not notified by the storefront, I will still regularly check via finalize payment to determine if the user has completed the payment process. This check is necessary in case the user closes the browser before the storefront can send the information.

With this information, I can create an order in S/4HANA with payment details on header level 'Electronic Payments'. I transfer two of the fields obtained from finalize payment, namly AuthorizationByDigitalPaytSrvc and EPaytByDigitalPaymentSrvc, as payment plan entity to S/4HANA via the Sales Order (A2X) API.

S/4HANA utilizes these identifiers to load the payment details from DPA, e.g. authorized amount or card validity. Configure the integration incl. destination in S/4HANA. However no implementation is required to finish the process and settle the payment.

Loaded Payment Details in S/4HANA

Outlook & Source Code

Utilizing SAP Digital Payments Add-On as a broker seems to be a promising approach to streamline PSP integrations plus it supports the whole payment process instead of just focusing on payment authorization in e-commerce.

I am eagerly anticipating the deployment of the integration to production. Feel free to leave a comment for clarification or reach out to exchange experiences.

I published the proof of concept code on github.