This documentation outlines how additional Payment Service Providers (PSP) can be integrated into Billwerk+ Transform using the Billwerk+ Transform API. The integration can be facilitated through an intermediary layer called the Integrator, which manages communication between Billwerk+ Transform and the PSPs, ensuring seamless transaction processing and data management. Alternatively, using a similar contract, PSPs can integrate directly with Billwerk+ Transform without the additional Integrator layer.

To satisfy the growing demand for external integration, we decided to offer it as a separate product with its pricing. Our Support will gladly answer your questions.

Roles and Responsibilities

• Billwerk+ Transform: Manages customer interactions, processes data, and initiates transaction requests.
• Integrator: Acts as an intermediary, handling specific flows with PSPs and managing transaction data.
• PSP: Processes payment requests, responds with transaction details, and notifies of changes.

This structure ensures a clear, efficient, and secure integration process using an Integrator or direct integration.

Alternatively, PSPs can integrate directly with Billwerk+ Transform without needing an additional Integrator layer. The Payment Service Provider must follow a similar contract to directly handle the communication, endpoints, and data structures with Billwerk+ Transform.

Communication Process

The communication process describes the sequence of operations and interactions between Billwerk+ Transform, the Integrator, and the PSPs. The flow ensures that all transactions are handled efficiently and securely.

1. Customer Initiation

   • The customer starts the payment process in Billwerk+ Transform.
   • Billwerk+ Transform handles the initial communication without involving the Integrator.

2. Data Processing and Delegation

   • Billwerk+ Transform processes the initial customer data.
   • The payment or refund request is then delegated to the Integrator.

3. Integrator's Role

   • The Integrator establishes a connection with the PSP.
   • It processes the specific flow (e.g., preauthorisation, payment, refund) with the PSP.

4. PSP Response Handling

   • The PSP responds to the Integrator with the required transaction details.
   • The Integrator formats the response and sends it back to Billwerk+ Transform.

5. Data Management

   • The Integrator stores transaction data from both Billwerk+ Transform and the PSP.
   • This includes necessary payment data for future transactions.

6. Notification Flow

   • The PSP sends notifications to the Integrator about transaction updates or changes.
   • Integrator process changes
   • The Integrator notify the Billwerk+ Transform about changes via webhooks.
   • Billwerk+ Transform request recent changes from the Integrator

Billwerk+ Transform expects specific endpoints to be developed on the Integrator side, which it will trigger to initiate payments and refunds. Additionally, third-party PSPs can notify the Billwerk+ Transform product via webhooks about changes in payment status, automatically triggering a fetch from the third-party PSP.

Flows Overview

Final integration should cover the following scenarios:

1. Integration Flow:

   • Allow Billwerk+ Transform to ensure that we are able to use this integration
   • Allow us to get a specific configuration so we know how we can use Integrator

2. Preauthorization Flow:

   • Initial verification of customer payment data.
   • Can involve redirecting customers to PSP checkout pages.
   • Can involve preauthorisation transaction cancellation

3. Payment Flow:

   • Includes both capture and recurring payments.
   • Handles the charging of funds from the customer.

4. Refund Flow:

   • Processing refunds to customers.
   • Updating transaction states accordingly.

5. Notification Flow:

   • Handling updates and changes to payment transactions.
   • Utilizes webhooks for real-time notifications.

REST Approach and Communication

The integration with Billwerk+ Transform uses a REST architectural style, with request and response data formatted in JSON. The API Contract is designed with predictable, resource-oriented URLs and leverages standard HTTP methods and headers. This ensures a consistent and easy-to-use interface for developers.

You can find a list of expected API Implemented on Integratore or PSP side in our API Reference, section External PSP Integration

API Endpoints

Below is a table of the essential endpoints used to integrate Billwerk+ Transform and the PSPs through the Integrator. These endpoints cover the entire transaction lifecycle, from initiation and management to updates and cancellations.

In addition to this endpoints, you may like to receive notifications from PSP, and for this, you can create additional endpoints to handle it that Billwerk+ Transform would not call

Endpoint Usage

Each endpoint should be implemented with security measures such as HTTPS, authentication tokens, and necessary validations to ensure the integrity and confidentiality of the data exchanged. Implementing these endpoints will facilitate smooth and secure interactions between Billwerk+ Transform, Integrators, and PSPs.