Using the Payment Integration Client Extension
Liferay DXP 2024.Q1+/Portal 7.4 GA112+
You can use a client extension to integrate with a new payment method in Liferay. This client extension from the sample workspace consists of a standalone Spring Boot application that communicates with Liferay using OAuth 2. See Configuring Payment Methods to read more about the payment methods available out-of-the-box with Liferay.
Prerequisites
-
Install a supported version of Java.
NoteSee JVM Configuration for recommended JVM settings.
-
Download and unzip the sample workspace:
Now you have the tools to start and deploy the client extension(s) to Liferay.
Examine the Payment Integration Client Extension
The client-extensions/liferay-sample-commerce-payment-integration/client-extension.yaml
file defines the payment integration client extension in the sample workspace. There are three important blocks in the .yaml
file that you must understand:
The assemble
block specifies that the standalone application/microservice is created with the bootJar
command. This is available from the Spring Boot Gradle Plugin. The application JAR must be included in the LUFFA for deployment in Liferay SaaS.
The liferay-sample-commerce-payment-integration
block contains the key configurations required for a payment integration client extension. See Payment Integration Client Extension YAML Reference for more information on each field.
Another important part of the client-extension.yaml
is in the liferay-sample-commerce-payment-integration-oauth-application-user-agent
definition. The serviceAddress
parameter defines where the service runs locally, and the serviceScheme
parameter defines the protocol. The name
field defines the name of the OAuth application user agent. The scopes
field defines the access given to the headless API. This section sets up Liferay as the authorization server, so that the payment integration you deploy next can invoke the resource server’s secure endpoints and send payloads. See OAuth User Agent YAML Configuration Reference for more information.
Deploy the Payment Integration Client Extension
-
Go to the sample workspace.
-
Run
This downloads a bundle inside the workspace’s
/bundles
folder. -
Go to the
/bundles/tomcat/bin
folder. Run -
Go back to the sample workspace’s
/client-extensions/liferay-sample-commerce-payment-integration
folder. -
Run
-
In Liferay’s log, confirm that the client extension deployed and started:
In addition, messages about the OAuth user agent are logged.
-
Verify that the OAuth Application User Agent was added to Liferay. Go to Control Panel → OAuth2 Administration.
The Liferay Sample Commerce Payment Integration OAuth Application User Agent provides the OAuth 2 authorization needed so that Liferay can access the Spring Boot application’s data through its protected endpoint. All that is needed for Liferay to authorize the application in this case is declaring the external reference code in the application-default.properties
:
Start the Microservice
From the client-extensions/liferay-sample-commerce-payment-integration
folder, run
The Spring Boot application starts and prints messages in the log:
Verifying the Addition of the Payment Integration
-
Log in as an administrator, open the Global Menu (
), and go to Control Panel → Sites.
-
Add a new Minium site.
-
Open the Global Menu (
) and go to Commerce → Channels.
-
Select Minium Portal and scroll down to the Payment Methods section. Verify the addition of the new payment integration here. It is inactive by default.
-
Select the new payment integration and activate it using the Active toggle.
-
Click Save. Two new tabs, Eligibility and Configuration, appear for the payment integration.
The configuration tab contains an input field. You can enter information required by the client extension here instead of hard coding values in the client extension itself. The example contains sample key-value pairs.
You can go to the Eligibility tab to select specific order types or payment terms to be eligible for the payment integration. By default, it is eligible for all order types and payment terms.
-
Click Save.
-
Open the site and use the account selector to create a new account.
-
Add a few items to your cart.
-
Open the mini cart and click Submit. This starts the checkout flow.
-
Continue checking out until you finish placing the order. Open the Global Menu (
) and go to Commerce → Payments to verify the payment’s completion.
Examining the Code
To create a payment integration in Liferay, you must implement controllers for the following payment statuses.
- Set up Payment
- Authorize
- Capture
- Cancel
- Refund
The provided sample client extension contains these controllers invoked by the Spring Boot application to create a new payment integration in Liferay. The key
and name
fields in the client-extension.yaml
file specifies the key and name for the payment integration. You should use a unique key that doesn’t conflict with any of the existing payment methods.
Examining SetUpPaymentRestController.java
The SetUpPaymentRestController
contains a single post method that has two parameters: the JSON Web Token (JWT) and the request body. The token authenticates HTTP calls, and the request body contains data as a string in JSON format. After logging the request body, it uses a JSONObject()
constructor to set the payment status to 18
and returns it as a response entity along with the HTTP status.
Examining AuthorizeRestController.java
The AuthorizeRestController
contains a single post method that has two parameters: the JSON Web Token (JWT) and the request body. The token authenticates HTTP calls, and the request body contains data as a string in JSON format. After logging the request body, it uses a JSONObject()
constructor to set the payment status to 2
and returns it as a response entity along with the HTTP status.
Examining CaptureRestController.java
The CaptureRestController
contains a single post method that has two parameters: the JSON Web Token (JWT) and the request body. The token authenticates HTTP calls, and the request body contains data as a string in JSON format. After logging the request body, it uses a JSONObject()
constructor to set the payment status to 0
and returns it as a response entity along with the HTTP status.
Examining CancelRestController.java
The CancelRestController
contains a single post method that has two parameters: the JSON Web Token (JWT) and the request body. The token authenticates HTTP calls, and the request body contains data as a string in JSON format. After logging the request body, it uses a JSONObject()
constructor to set the payment status to 8
and returns it as a response entity along with the HTTP status.
Examining RefundRestController.java
The RefundRestController
contains a single post method that has two parameters: the JSON Web Token (JWT) and the request body. The token authenticates HTTP calls, and the request body contains data as a string in JSON format. After logging the request body, it uses a JSONObject()
constructor to set the payment status to 17
and returns it as a response entity along with the HTTP status.