Skip to content

Berlin Group docs #2689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
simonredfern merged 3 commits into from
Feb 11, 2026
Merged

Berlin Group docs #2689

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f8dd979
docfix/Add Berlin Group Mandatory Headers to Glossary
constantine2nd Feb 10, 2026
cef4a4c
docfix/Add various Berlin Group related props into Glossary
constantine2nd Feb 10, 2026
21bb040
Merge remote-tracking branch 'upstream/develop' into develop
constantine2nd Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 223 additions & 0 deletions obp-api/src/main/scala/code/api/util/Glossary.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3094,6 +3094,229 @@ object Glossary extends MdcLoggable {
""")


glossaryItems += GlossaryItem(
title = "Berlin Group Mandatory Headers",
description =
s"""
|OBP validates mandatory HTTP request headers for Berlin Group (NextGenPSD2) API endpoints.
|
|When a request targets a Berlin Group endpoint (identified by the Berlin Group URL prefix), OBP checks for the presence of required headers before processing the request.
|
|## Mandatory Headers
|
|The following headers are required on all Berlin Group API requests by default:
|
|* **Content-Type** - The media type of the request body
|* **Date** - The date and time of the request (must be a valid RFC 7231 date)
|* **Digest** - A digest of the request body for integrity verification
|* **PSU-Device-ID** - UUID of the device used by the Payment Service User (PSU)
|* **PSU-Device-Name** - Name of the device used by the PSU
|* **PSU-IP-Address** - IP address of the PSU device
|* **Signature** - Digital signature of the request (keyId must match the serial number from the TPP certificate)
|* **TPP-Signature-Certificate** - The certificate used by the TPP to sign the request
|* **X-Request-ID** - UUID that uniquely identifies the request (must not be reused for POST requests that returned 201)
|
|## Additional Consent Headers
|
|When creating a consent (POST to /consents), the following additional header is required:
|
|* **TPP-Redirect-URI** - URI to redirect the PSU to after consent authorization
|
|## TPP Requests Without PSU Involvement
|
|For background/batch requests where no PSU is directly involved, set:
|
|* PSU-IP-Address: 0.0.0.0
|* PSU-Device-ID: no-psu-involved
|* PSU-Device-Name: no-psu-involved
|
|This enables OBP to apply different consent frequency rules for TPP-initiated requests.
|
|## Configuration
|
|The mandatory headers can be customized in the Props file:
|
|* `berlin_group_mandatory_headers` - Comma-separated list of mandatory header names. Set to empty to disable header checks.
|* `berlin_group_mandatory_header_consent` - Additional headers required for consent creation endpoints.
|
|Example Props configuration:
|
| # Use default mandatory headers
| #berlin_group_mandatory_headers = Content-Type,Date,Digest,PSU-Device-ID,PSU-Device-Name,PSU-IP-Address,Signature,TPP-Signature-Certificate,X-Request-ID
| #berlin_group_mandatory_header_consent = TPP-Redirect-URI
|
| # Disable mandatory header checks (e.g. for testing)
| berlin_group_mandatory_headers =
| berlin_group_mandatory_header_consent =
|
|## Validation Chain
|
|OBP performs the following validation steps on Berlin Group requests in order:
|
|1. **Missing headers check** - Returns HTTP 400 if any mandatory headers are absent
|2. **Date format check** - Validates the Date header conforms to RFC 7231
|3. **X-Request-ID format check** - Validates the X-Request-ID is a valid UUID
|4. **X-Request-ID uniqueness check** - Ensures the X-Request-ID has not been used in a previous successful POST (201) request
|5. **Signature header check** - Parses the Signature header and verifies the keyId serial number matches the TPP certificate
|6. **Consent-ID usage check** - Ensures the Consent-ID header is not sent on consent management endpoints where it is not expected
|
|If any check fails, OBP returns an appropriate error message (OBP-20251 through OBP-20256) with HTTP status 400.
|
""")


glossaryItems += GlossaryItem(
title = "Berlin Group Transaction and Consent Lifecycle",
description =
s"""
|OBP provides background schedulers that automatically manage the lifecycle of Berlin Group transactions and consents.
|
|## Outdated Transactions
|
|Berlin Group payment transactions with status "received" (RCVD) that remain unprocessed beyond a configured time threshold are automatically rejected by a background scheduler task.
|
|* `berlin_group_outdated_transactions_time_in_seconds` - Time in seconds after which a "received" transaction is considered outdated. Default: **300** (5 minutes).
|* `berlin_group_outdated_transactions_interval_in_seconds` - How often (in seconds) the scheduler checks for outdated transactions. Must be set to a value greater than 0 to enable the task. **Not set by default** (task is disabled).
|
|Example:
|
| # Reject transactions stuck in "received" status for more than 5 minutes, checking every 60 seconds
| berlin_group_outdated_transactions_time_in_seconds = 300
| berlin_group_outdated_transactions_interval_in_seconds = 60
|
|## Outdated Consents
|
|Berlin Group consents with status "received" that remain unfinished (e.g. the PSU never completed the SCA flow) beyond a configured time threshold are automatically rejected.
|
|* `berlin_group_outdated_consents_time_in_seconds` - Time in seconds after which an unfinished consent is considered outdated. Default: **300** (5 minutes).
|* `berlin_group_outdated_consents_interval_in_seconds` - How often (in seconds) the scheduler checks for outdated consents. Must be set to a value greater than 0 to enable the task. **Not set by default** (task is disabled).
|
|Example:
|
| # Reject consents stuck in "received" status for more than 5 minutes, checking every 60 seconds
| berlin_group_outdated_consents_time_in_seconds = 300
| berlin_group_outdated_consents_interval_in_seconds = 60
|
|## Expired Consents
|
|Berlin Group consents with status "valid" whose `validUntil` date has passed are automatically transitioned to "expired" status.
|
|* `berlin_group_expired_consents_interval_in_seconds` - How often (in seconds) the scheduler checks for expired consents. Must be set to a value greater than 0 to enable the task. **Not set by default** (task is disabled).
|
|Example:
|
| # Check for expired consents every 120 seconds
| berlin_group_expired_consents_interval_in_seconds = 120
|
""")


glossaryItems += GlossaryItem(
title = "Berlin Group URL and Path Configuration",
description =
s"""
|OBP allows customization of the URL paths used for Berlin Group (NextGenPSD2) API endpoints.
|
|## Canonical Path
|
|* `berlin_group_version_1_canonical_path` - Overrides the version segment of the Berlin Group v1 URL path. By default, the built-in path is `v1.3` (i.e. endpoints are served at `/berlin-group/v1.3/...`). Setting this property changes the version segment.
|
|Example:
|
| # Serve Berlin Group endpoints at /berlin-group/v1.3.12/...
| berlin_group_version_1_canonical_path = v1.3.12
|
|## Alias Path
|
|* `berlin_group_v1_3_alias_path` - Defines an alternative URL prefix under which Berlin Group v1.3 endpoints are also available. The format must be `xxx/yyy`. When set, all Berlin Group v1.3 endpoints are duplicated under this alternative path.
|
|Example:
|
| # Also serve Berlin Group endpoints at /0.6/v1/...
| berlin_group_v1_3_alias_path = 0.6/v1
|
""")


glossaryItems += GlossaryItem(
title = "Berlin Group Response Formatting",
description =
s"""
|OBP provides several configuration options to control how Berlin Group API responses are formatted.
|
|## Account Name Visibility
|
|* `BG_v1312_show_account_name` - Boolean flag that controls whether the `name` field is included in Berlin Group account responses (at `/berlin-group/v1.3/accounts` and `/berlin-group/v1.3/accounts/{accountId}`). Default: **true**.
|
|Some implementations may require omitting the account name for privacy or compliance reasons.
|
|Example:
|
| # Hide account names in Berlin Group responses
| BG_v1312_show_account_name = false
|
|## Amount Sign Removal
|
|* `BG_remove_sign_of_amounts` - Boolean flag that controls whether the sign (positive/negative indicator) is removed from transaction amount values in Berlin Group responses. Default: **false**.
|
|When enabled, amounts such as "-100.00" are returned as "100.00". This can be useful when the sign is conveyed by other means (e.g. booked vs pending lists, or credit/debit indicators).
|
|Example:
|
| # Remove the sign from transaction amounts
| BG_remove_sign_of_amounts = true
|
|## Error Message Path Visibility
|
|* `berlin_group_error_message_show_path` - Boolean flag that controls whether the request URL path is included in Berlin Group error response messages. Default: **true**.
|
|When enabled, error responses include the `path` field showing which URL triggered the error. This can be disabled for privacy or security reasons.
|
|Example:
|
| # Hide the request path in error messages
| berlin_group_error_message_show_path = false
|
""")


glossaryItems += GlossaryItem(
title = "Berlin Group Consent Settings",
description =
s"""
|OBP provides configuration options for Berlin Group consent creation and SCA (Strong Customer Authentication) flows.
|
|## Frequency Per Day Limit
|
|* `berlin_group_frequency_per_day_upper_limit` - Maximum allowed value for the `frequencyPerDay` field when creating a Berlin Group consent. Default: **4**.
|
|When a TPP creates a consent, the requested `frequencyPerDay` must be greater than 0 and less than or equal to this upper limit. For one-off access consents, the frequency must be exactly 1.
|
|Example:
|
| # Allow up to 10 requests per day per consent
| berlin_group_frequency_per_day_upper_limit = 10
|
|## ASPSP SCA Approach
|
|* `berlin_group_aspsp_sca_approach` - Defines the SCA approach advertised by the ASPSP (Account Servicing Payment Service Provider) in the `ASPSP-SCA-Approach` response header for consent creation endpoints. Default: **redirect**.
|
|Possible values include:
|
|* `redirect` - The PSU is redirected to the ASPSP for authentication
|* `embedded` - Authentication is performed within the TPP interface
|* `decoupled` - Authentication is performed on a separate device/channel
|
|This header is returned in the response to POST `/consents` requests to inform the TPP which SCA method the ASPSP supports.
|
|Example:
|
| # Use embedded SCA approach
| berlin_group_aspsp_sca_approach = embedded
|
""")


glossaryItems += GlossaryItem(
title = "API Collection",
description = s"""An API Collection is a collection of endpoints grouped together for a certain purpose.
Expand Down
Loading