Payment Page (or shortly P2 or p2) is a piece of functionality that allows to integrate with your web-application different payment methods that a client can use to pay money for a target service or product.
The Builder editor allows to create a layout of P2 by using some predefined components. Builder allows to generate both front-end and back-end code to make the designed P2 operational.
Using the builder web-application is possible to create and design many Payment pages with different payment methods, connected Payment Service Providers (PSP), etc. to integrate them in various applications or scenarios of the same target application. E.g. it might be different layout and payment methods for Subscription and for payment by Credit Card, the P2 might be tuned for specific country or user groups, and so on.
Introduction
P2 functionality provided by two parts: front-end application and back-end application. Front-end (FE or P2 FE) consists of plain html-page accompanied by css-file with specific page styles and js-file contains JavaScript code integrated with the html-layout. So, the front-end side of P2 is a static html-page integrated with reactive code.
Page design, styles and themes, chosen components and their configuration settings to specific PSPs defined by customer in Builder editor using visual toolset like Component Palette, Attribute Editors, etc. in each specific P2 project.
P2 BE part consists of the REST API endpoints that P2 FE interacts with to provide integrations with chosen Payment Service Providers (PSP) or providers.
Target application should use configuration capabilities to integrate with P2 functionality and not requires developing code to make P2 workable, although it’s possible to tune some aspects of its business-logic, e.g. adding specific behavior for web-hooks that PSP calls to provide a transaction resulting status.
List of PSPs and examples of P2 includes:
| Provider | Supports | P2 Reference |
|---|---|---|
Apple Pay, Google Pay, Payment links, Credit Card checkout, Default Amount, Custom Amount, layout components |
Credit Card component with Amount |
|
PayPal Button, Klarna, Giropay, SEPA, Default Amount, Custom Amount, layout components |
Components
Components available for visual design inside Builder canvas. They separated to several groups inside Components Palette. Groups might be PSP-specific:
-
Stripe Components
-
PayPal Components
and general (not PSP-specific):
-
Payment Components
-
Form
-
Basic
Front-end & Back-end integration
P2 FE code calls respective PSP API and P2 BE API. The standard flow is (as an example of Stripe Credit Card checkout):
-
Call Stripe endpoint to get one-time unique token;
-
Call P2 BE endpoint providing the one-time token;
-
P2 BE communicates under the hood with Stripe PSP payment service to fulfill the transaction;
-
P2 BE endpoint returns a response to P2 FE with results of the transaction fulfilment;
-
P2 FE based on the BE response forwarded either to successful URL (Confirmation page) or to error URL.
When a user initiates an action (like payment, e.g.) the P2 front-end populates a request both with respective parameters to P2 back-end, which implements specific business-logic to fulfill respective payment transaction.
Authentication
In some scenarios, described in Target application & P2 integration, P2 required to be integrated in a security context of the target application to call P2 back-end with respective authentication information (like user Id, P2 Id, etc.)
To populate authentication information in a secure manner, encrypted parameters used (as described in details below).
Target application & P2 integration
Target application intended to seamlessly navigate to P2 and allows an end-user to be able to pay for a service or product. To make the payment possible different scenarios might be employed.
Scenario 1
User can freely choose predefined amount of money to pay or set up custom amount. Using this scenario, target application just navigates to P2 and after that end-user would pay some amount. Such scenario is applicable for paying donation, tips, etc.
To confirm the payment transaction successfully completed and possible to persist the transaction in local repository, P2 BE expose several REST endpoints which being bundled with the target application can be executed as web-hooks by a respective PSP.
Scenario 2
In this scenario the payer should pay exact predefined amount of money using different payment methods provided by P2. Payer in this scenario cannot choose or change the amount or currency of the transaction. It’s applicable to pay for some services or products that require that exact price being paid.
Then, when navigate to P2 the target application must populate (encrypted) parameters that include amount, currency, authentication information, etc. For rendering purposes the same information should be provided in unencrypted form, but P2 BE decide on encrypted parameters and would reject the transaction in case they are misleading.
The same way, web-hook endpoints exposed by P2 BE should be used to persisting or checking the transaction result.
To implement respective functionality in a flexible way, the target application have to instantiate a bean implementing WebhooksPaymentListener interface. The implementation might simply log the incoming events or delegate it to auditing, or persist, etc. depending on required business-logic.
P2 Parameters
Format of parameters that target application should pass to the P2 is depicted below:
| Optional | Optional | Optional | Mandatory | Mandatory | |
|---|---|---|---|---|---|
Encrypted |
User auth |
P2 Id |
Price Id |
Amount |
Currency |
Unencrypted |
Unit |
Amount |
Currency |
Encrypted parameters provided in base64-encoded string format. All parameters pass to P2 as url-encoded parameters. After the P2 use unencrypted parameters to render the page layout, when user click some action’s button to initiate payment, all these parameters propagates to P2 back-end. P2 back-end decrypt the encrypted values of the parameters and use them to make a respective transaction.
To create encrypted parameters, the target application should
Web-hooks
After the transaction confirmed on PSP side, it sends a confirmation to web-hook endpoints that should be registered upfront for each specific PSP and each specific P2. The web-hooks implemented in a form of REST controller, which endpoints can be registered in PSP as web-hook endpoints. Inside the web-hook controller, each endpoint delegates the specific implementation to the listener-components, that depending on the bound P2 BE Modules and might have different implementation. The most common implementation of the web-hooks is to persist transaction in a local application DB for future reference.
Payment Page (P2) API
P2 BE Modules
Current implementation of P2 back-end made in Java 11 using Spring-boot framework and Maven package manager. It contains 2 custom modules that might be included into the target application to be bound and running in the same application context (e.g. under the same web-application server):
-
Common P2
-
Auditing
-
P2 back-end
Common P2 contains base classes for specific PSP (Stripe, PayPal, etc.) and basic implementation of the web-hook endpoints. To include the module into a target application project:
<dependency>
<groupId>com.p2s2</groupId>
<artifactId>p2-common</artifactId>
<version>1.0.0-RELEASE</version>
</dependency>Auditing module being included in the target application allows to make auditing trail for important user actions. To include the module into a target application project:
<dependency>
<groupId>com.p2s2</groupId>
<artifactId>auditing</artifactId>
<version>1.0.0-RELEASE</version>
</dependency>P2 back-end module provides functionality for all back-end Spring-boot code, that works with front-end code of a designed Payment Page. To include the module into a target application project:
<dependency>
<groupId>com.p2s2</groupId>
<artifactId>api</artifactId>
<version>1.0.0-RELEASE</version>
</dependency>