Technical Documentation: Payments

Features

1. Set up Truelayer provider

2. Set up Realex provider

3. Set up manual bank transfer

4. Set up basic payment request

5. Make a payment (citizen)

6. Change payment amount - when allowed (citizen)

7. Delete payment request setup

8. Payment Status management (INITIATED, PENDING, SUCCESSFUL)

a. DRAFT Payment request

9. Payment Provider setup status management (CONNECTED, DISCONNECTED)

10. Payment request status management (ACTIVE, INACTIVE)

11. Reconcile a manual bank transfer payment (individual)

12. Reconcile a payment (automatically for Credit and Debit cards)

13. Integrate Payments with MyGovID

14. Integrate Payments with Login System - LogTo (Roles & Permissions)

15. Audit logs

16. Payments APIs

17. Integration between Payments and Journey Builder

18. OpenShift - Migrate compute to ROSA (DEV, STA)

To be determined

1. Worldpay

2. Open Banking

Feature details

Citizens

• Citizens must log in using a valid MyGovID account to access the system and perform payment-related operations.

Public Servants

• Public servants must log in through Microsoft EntraID and be onboarded within their respective departments to access the Building Block.
• Once onboarded, public servants can configure payment providers and manage payment requests.

For citizens: How to perform a payment

A citizen, to perform a payment, will receive a payment link (via Email, on MyDashboard, or as part of a journey) and can select their preferred payment method from the list of allowed payment providers for that request. The process varies depending on the selected payment method. After the payment is completed, the citizen is redirected to the Redirect URL specified in the payment request.

Manual bank transfer

• The citizen is redirected to a new page displaying the necessary payment details in a clear table format:

1. Title: The name of the payment request.

2. Total to Pay: The exact amount required for the transfer.

3. Name on the Account: The recipient’s account name.

4. IBAN: The recipient’s International Bank Account Number.

5. Payment Reference Code: A unique code the citizen must include in their transfer for proper matching.

• After completing the payment, the citizen must click the "I have made the payment" button to confirm the transfer and allow the system to proceed with processing.

Credit card (Stripe or Realex)

• The citizen is redirected to the respective Stripe or Realex page to securely complete the payment within their interfaces. Both Stripe and Realex offer automatic reconciliation, ensuring payments are matched automatically.

Open Banking

• The citizen is redirected to their bank’s page through the Open Banking protocol to complete the payment securely.

Citizen Dashboard: "My Payments"

The "My Payments" page provides a list of all payments made by the user.

The list includes:

• Status: Indicates the current state of the payment (e.g., Initiated, Pending, Successful). Statuses are color-coded for quick identification.
• Date: The date and time when the payment was made.
• Payment Request Title: The title or purpose of the payment.
• Amount: The payment amount in euros (€).
• Actions: Includes a "Details" button that allows the user to view more information about a specific payment.

Users can use this page to:

• Check the status of their payments.
• Click "Details" to view comprehensive information about individual transactions.
• Review their overall payment history in one convenient location.

For Public Servants: Payment providers

The system supports four types of payment providers. Public servants can integrate these providers for processing payments:

1. Open Banking

2. Manual Bank Transfer

3. Stripe

4. Realex

Adding a Payment Provider

To add a payment provider, follow these steps:

1. Log in: Public servants must log in and ensure they are onboarded.

2. Navigate to the Payment Provider Section: Select the type of payment provider to configure.

3. Fill Required Fields: Provide the necessary details based on the chosen payment provider.

Provider Configuration Details

Open Banking

• Name: Internal recognisable name for the payment provider.
• Bank Account Holder Name: Name on the bank account.
• IBAN: International Bank Account Number.

Manual Bank Transfer

• Name: Internal recognisable name for the payment provider.
• Bank Account Holder Name: Name on the bank account.
• IBAN: International Bank Account Number.
• Reconciliation: Is done manually from the Transaction page

Stripe

• Name: Internal recognisable name for the payment provider.
• Live Publishable Key: Public key for live environment.
• Live Secret Key: Secret key for live environment.
• Webhook Signing Key: Used to validate incoming calls from Stripe.
• Automatic Reconciliation: Payments processed through Stripe are automatically matched and reconciled (if the Webhook Signing Key is provided).

Realex

• Name: Internal recognisable name for the payment provider.
• Merchant ID: Unique identifier for your Realex account.
• Shared Secret: Authentication key for integration.
• Automatic Reconciliation: Payments processed through Realex are automatically matched and reconciled.

Creating a Payment Request

Once a payment provider has been configured, public servants can create a payment request. Below are the field descriptions and their purposes:

1. Title (Required): Specify the title of the payment request. This will be visible from citizens.

2. External Description (Optional): Provide additional details or notes. This will be visible from citizens.

3. Open Banking Account: Select an account or disable this option.

4. Manual Bank Transfer Account: Select an account or disable this option.

5. Card Payment Account: Select an account or disable this option.

6. Reference (Required): Unique identifier for tracking payments.

7. Amount (€) (Required): Set the payment amount in euros.

8. Allow Dynamic Amount: Enable dynamic amount coming from the Journey Builder

9. Allow the User to Pay a Custom Amount: Allow users to input their preferred amount.

10. Redirect URL (Required): URL to redirect the user once the payment is completed.

11. Payment Request Status:

• Active: The request is live and can accept payments.
• Inactive: The request is not live.
• Draft: The request is in draft status and not yet usable.

Managing Payment Requests

• After creating a payment request, users can view all requests in the Payment Requests section.
• By selecting a specific request, users can:

- View all request details.

- Delete the request (only if no transactions are registered).

- Edit the request.

- Copy the sharable payment request link.

• At the bottom of the request details page, public servants can view all transactions executed in the context of the payment request and can click on a specific transaction to view its details.

Transaction Details

In the transaction details page, public servants can find the following information:

1. Payment Request Title: The title or name of the payment request as specified during setup.

2. Amount: The total monetary value of the payment made, displayed in euros (€).

3. External Description: Additional context or notes associated with the payment request.

4. Last Update: The timestamp of the most recent update to the payment request.

5. Status: The current state of the payment (e.g., "Successful," "Pending," "Failed").

6. Provider Name: The name of the payment provider handling the transaction.

7. Provider Type: The type of payment provider (e.g., "Realex").

8. Payment Reference Code: A unique identifier for the transaction, useful for tracking and reconciliation.

9. Payer Name: The name of the individual or entity making the payment.

10. Payer Email: The email address of the payer, used for communication or sending receipts.

For manual bank transfers, public servants will see a "Transaction found with this reference code" button. Clicking this button confirms that funds have been received for the corresponding transaction. This is a manual reconciliation and must be performed by the civil servant.

Payment Dashboard Overview

The Payments dashboard provides an overview of all transactions and includes the following:

1. Status:

- Pending: Awaiting completion or confirmation.

- Successful: Successfully processed.

- Initiated: Started but not yet confirmed.

- Statuses are color-coded for easy identification.

2. Date: Timestamp of when the payment was initiated or updated.

3. Payment Request Title: Name of the associated payment request.

4. Amount (€): Displays transaction amounts.

5. Actions: Includes a link to view detailed information about each transaction.

Audit Logs Page

The Audit Logs page provides a comprehensive record of actions and events within the system, allowing public servants to monitor, track, and review all activity related to payments and other resources. This page is designed to ensure transparency and accountability, helping public servants trace events, identify discrepancies, and maintain accurate records.

How to Use the Audit Logs Page

Public servants can use the filters at the top of the page to narrow down the logs they want to view:

• User: Enter the username or ID to view logs specific to a particular user’s actions.
• Resource: Select a resource (e.g., "Transactions" or "Payments") to focus on specific areas of activity.
• Action: Choose an action type (e.g., "Created" or "Updated") to filter for particular kinds of events.
• Date Range: Use the "From" and "To" fields to specify the time period for which you want to view logs. After selecting the desired filters, click Submit to display the results.

What You Can Find on This Page

The logs are displayed in a table, and each entry includes the following details:

• Event Type: Describes the type of action performed, such as "Transaction created" or "Transaction status updated."
• Creation Date: Displays the exact date and time when the event occurred.
• User: Indicates who performed the action, identified by their username or ID.
• Details: A link to view more information about the specific event. Clicking this provides additional context, such as changes made or parameters involved.

Access and Security

• Citizen Access: Must have a MyGovID account.
• Public Servant Access: Must log in with Microsoft EntraID and be onboarded.
• All data is secured using industry-standard encryption and authentication protocols.