> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get started
> Quick start guide for OBPM payment connector integration
Before you configure the OBPM Connector, make sure you have the following credentials and connectivity in place:
* Complete the steps in [Get started with connectors](/connectors/getting-started) and [Sync Hub](/platform/sync-hub/overview).
* **OBPM access:** An active account in the Oracle Banking Payments Manager environment and the proprietary **wlthint3client.jar license** for connecting to the JMS server.
* **Network connectivity:** Confirmed routing between the Oracle environment and the Grand Central iPaaS. For supported options, see [Network connectivity](/platform/network-connectivity).
* **Environment details:** Obtain the following environment variables from Oracle to configure the connector:
**For OBPM services**
| Environmental Key | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| `soap-obpm-url` | SOAP service URL to access the OBPM environment. |
| `obpm-source` | Unique identifier assigned to the client by OBPM. |
| `obpm-userId` | User ID of the client making the connection to OBPM. |
| `rest-obpm-url` | REST service URL to access the OBPM environment. |
| `jms-obpm-url` | JMS connection URL to the OBPM environment. |
| `jms-queue-name` | JMS queue names for OBPM integration flows, such as payee contact sync, payment status updates, and recurring payment schedules. |
| `jms-connection-factory` | JMS connection factory. |
| `jms-security-principal` | JMS username to authenticate. |
| `jms-security-credentials` | JMS password for the username to authenticate. |
**For Flexcube services**
| Environmental Key | Description |
| :------------------ | :------------------------------------------------------- |
| `soap-flexcube-url` | SOAP service URL to access the Flexcube environment. |
| `flexcube-source` | Unique identifier assigned to the client by Flexcube. |
| `flexcube-userId` | User ID of the client making the connection to Flexcube. |
***
## Configuration guide
Follow these steps to initialize and authorize your OBPM Connector.
### 1. Establish connectivity
Exchange connectivity details between **Grand Central and OBPM** as described on the [Network connectivity](/platform/network-connectivity) page for your chosen network connection.
### 2. OBPM service authentication and authorization mechanisms
You can configure the following authentication and authorization mechanisms based on your security requirements:
* **mTLS for SOAP OBPM services**
* **WS-Security for Flexcube services**
* **OBPM authorization for REST services**
* **SSL server certificate verification for REST services**
* **SSL server certificate trust for JMS connections**
**Certificate and credential security:** To configure all certificates and credentials, create a SOPS secret. For more information, see [How to create SOPS](/platform/developer-guides/build/configure-connector). To share credentials between OBPM and Grand Central, use 1Password.
### 3. Environment configuration
To initialize the OBPM Connector, define specific environment variables in your `gc-applications-live` repository.
Define common variables in `values.yaml`. Define connector-specific variables in the following files:
| Connector | Property | Description |
| :--------------------------------------- | :--------------------------------------- | :---------------------------------------------------------------------------------------- |
| `gc-obpm-payment-connector` | `payments-v0.values.yaml` | Outbound payment connector for all payments, including payee contact creation and update. |
| `gc-obpm-payment-inbound-connector` | `inbound-payments-v0.values.yaml` | Inbound payment connector that receives payment status updates. |
| `gc-obpm-direct-debit-mandate-connector` | `ddmandate-payment-v0.values.yaml` | Outbound payment connector for direct debit mandate search, retrieval, and termination. |
| `gc-flexcube-foreign-exchange-connector` | `foreignexchange-payment-v0.values.yaml` | Outbound payment connector for foreign exchange creation. |
For the full property list for each connector, including defaults and descriptions, see [Reference](/connectors/payments/obpm/reference).
### Define common parameters
The following table lists the variables used across all connectors connecting **Grand Central to OBPM** and **OBPM to Grand Central**.
| values.yaml | Description | Environmental Key |
| :----------------- | :----------------------------------------------------------------------------------- | :------------------ |
| `obpm.baseUrl` | Target API endpoint for the OBPM gateway. | `soap-obpm-url` |
| `obpm.source` | Unique organizational identifier assigned by OBPM. | `obpm-source` |
| `obpm.userId` | User ID of the client making the connection to OBPM. | `obpm-userId` |
| `obpm.branch` | Specific OBPM branch, or defaults to `000`. | N/A |
| `obpm.hostCode` | Host code sent on direct debit mandate retrieval and termination requests. | N/A |
| `obpm.ubsComp` | OBPM Universal Banking Solution (UBS) component identifier. Defaults to `FCUBS`. | N/A |
| `flexcube.baseUrl` | Target API endpoint for the Flexcube gateway. | `soap-flexcube-url` |
| `flexcube.source` | Unique organizational identifier assigned by Flexcube. | `flexcube-source` |
| `flexcube.userId` | User ID of the client making the connection to Flexcube. | `flexcube-userId` |
| `flexcube.branch` | Specific Flexcube branch, or defaults to `000`. | N/A |
| `flexcube.ubsComp` | Flexcube Universal Banking Solution (UBS) component identifier. Defaults to `FCUBS`. | N/A |
Some connectors require only Flexcube or only OBPM properties. For example, the direct debit connector requires only OBPM properties. Skip properties that aren't required for a specific connector. Each connector section lists its requirements.
The following example shows a sample `values.yaml` file:
```yaml theme={"system"}
# Sample OBPM Environment Configuration
connector:
properties:
obpm.baseUrl: "http://wiremock-obpm-payments.gc-obpm.svc.cluster.local:9021"
obpm.source: BACKBASE
obpm.ubsComp: FCUBS
obpm.userId: BACKBASE
obpm.branch: "001"
flexcube.baseUrl: "http://wiremock-flexcube-payments.gc-
flexcube.svc.cluster.local:9021"
flexcube.source: BACKBASE
flexcube.ubsComp: FCUBS
flexcube.userId: BACKBASE
flexcube.branch: "001"
#OBPM Rest Api Configuration
obpm.rest.baseUrl: "http://wiremock-obpm-rest-payments.gc-obpm.svc.cluster.local:9021"
```
Place the `values.yaml` file in the following path:
```
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-obpm
└── values.yaml
```
### Define gc-obpm-payment-connector parameters
Use these variables, along with the common parameters defined earlier, to configure outbound connections for all payments and payee contact synchronization for creation and update from **Grand Central to OBPM**. The following table lists the available parameters:
| payments-v0.values.yaml | Description |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `retryFlag` | Set to `true` to enable automatic request retries on connection failure. |
| `cxf.client.ssl.ca.cert.path` | **Optional:** Server certificate path for mTLS. |
| `cxf.client.ssl.keystore.path` | **Optional:** Client certificate path for mTLS. |
| `cxf.client.ssl.keystore.type` | **Optional:** Client keystore certificate type. |
| `http.client.ssl.ca.cert.path` | **Optional:** Certificate for SSL pinning for REST services. |
| `jmsFlexCubeUrl` | JMS endpoint URL for payee contact sync. |
| `jms.connection.factory` | JMS connection factory name for payee contact sync. |
| `jms.queue.name` | JMS queue name for payee contact sync. |
| `jms.send.persistent.required` | Set to `true` to persist messages for reliability. |
| `jms.send.retry.enabled` | Set to `true` to enable retry logic for sending messages. |
| `obpm.contact.sync.domesticCountryCode` | ISO country code used to route payee sync requests as domestic `` when the payee bank country matches. All other payees are routed as international ``. The connector defaults to `ZZ`; override per tenant in deployment values. |
The connector defaults `obpm.contact.sync.domesticCountryCode` to `ZZ`, a non-assigned ISO code, so no real-world payee is treated as domestic until you configure otherwise. Set this property per tenant in your deployment values, for example `GB` or `US`, once domestic payee routing is signed off for your environment.
Create a SOPS secret for the following variables:
| obpm-outbound-secrets | Description |
| :--------------------------------- | :----------------------------------------------------------------------------------- |
| `server.crt` | **Optional:** Server certificate from OBPM for mTLS or HTTP trust for REST services. |
| `client.p12` | **Optional:** Grand Central certificate for mTLS for SOAP services. |
| `cxf.client.wsse.password` | **Optional:** SOAP WS-Security password. |
| `cxf.client.ssl.keystore.password` | **Optional:** Server certificate keystore password for mTLS. |
Follow [How to create SOPS](/platform/developer-guides/build/configure-connector) to create a SOPS secret for the variables listed in the preceding table.
Create a SOPS secret for the contact sync JMS credentials:
| obpm-contact-sync-jms-secret | Description |
| :---------------------------------- | :--------------------------------------------------------------------- |
| `flexcube.jms.security.principal` | JMS server username to authenticate for payee contact sync. |
| `flexcube.jms.security.credentials` | JMS server password to authenticate for payee contact sync. |
| `server.crt` | **Optional:** Server CA certificate for SSL trust with the JMS server. |
Add the preceding credentials to an `obpm-pushToJms.properties` file in the secret. Follow [How to create SOPS](/platform/developer-guides/build/configure-connector) to create a SOPS secret for these variables.
The following example shows a sample `payments-v0.values.yaml` file:
```yaml theme={"system"}
# Sample OBPM all payment Environment Configuration
connector:
existingSecretName: obpm-outbound-secrets
properties:
retryFlag: false
#Soap Service configuration for additional security
cxf.client.ssl.ca.cert.path: /etc/camel/conf.d/_secrets/obpm-outbound-secrets/server.crt
cxf.client.ssl.keystore.path: /etc/camel/conf.d/_secrets/obpm-outbound-secrets/client.p12
cxf.client.ssl.keystore.type: PKCS12
#OBPM Rest Api Configuration
obpm.rest.fetchBankDetailsByIBANApiUri: /api-gateway/api/s2/obpmrest/payments/IbanValidationService
#Http Configurations for REST Service security
http.client.ssl.ca.cert.path: /etc/camel/conf.d/_secrets/obpm-outbound-secrets/server.crt
# Payee contact sync JMS Configuration
jmsFlexCubeUrl: http://wiremock-obpm-payments.gc-obpm.svc.cluster.local:9021
jms.connection.factory: NotifQCF
jms.queue.name: PAYEE_QUEUE_EXT
jms.send.persistent.required: true
jms.send.retry.enabled: true
jms.security.credentials.file: /etc/camel/conf.d/_secrets/obpm-contact-sync-jms-secret/obpm-pushToJms.properties
traits:
knativeservice:
# IMPORTANT: Cost-related. Keeping minScale >0 causes continuous cost even when idle.
# With minScale: 0, each request grants 30 min uptime (extended if new requests arrive).
# Use >0 only if hot start is required, and reset to 0 afterward to avoid unnecessary cost.
minScale: 0
logging:
# DEBUG adds significant log output during startup and runtime.
# This can noticeably slow down starts due to extra logging work and I/O.
# Use only for troubleshooting and disable when not needed.
level: INFO
```
Place the `payments-v0.values.yaml` file in the following path:
```
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-obpm
└── payments-v0.values.yaml
```
### Define gc-obpm-payment-inbound-connector parameters
Configure how Grand Central receives asynchronous updates from **OBPM**.
Set up the sync-hub component as described in [Sync Hub](/platform/sync-hub/overview). Configure Sync Hub to obtain the ASB variables. Sync Hub is a mandatory component for inbound connectivity.
The following table lists the available parameters:
| `inbound-payments-v0.values.yaml` | Description | Environmental Key |
| :------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `jmsFlexCubeUrl` | JMS URL to connect to OBPM. | `jms-obpm-url` |
| `jms.queue.route.mapping` | Maps inbound JMS queues to their Camel routes. Comma-separated `>direct:` pairs, for example `NOTIFOUTQ_EXT>direct:dispatchPaymentNotification,SI_NOTIF_EXT>direct:processSINotification`. The `direct:dispatchPaymentNotification` route inspects each notification and forwards it to `direct:updatePaymentStatus` for payment status updates or to `direct:processPaymentIngestion` for off-channel payment ingestion. | `jms-queue-name` |
| `obpm.inbound.route.discriminator.xpath.1` | XPath for the first routing discriminator that the `direct:dispatchPaymentNotification` route reads from each notification. Defaults to `NotifTlr/UserId`. | N/A |
| `obpm.inbound.route.discriminator.xpath.2` | XPath for the second routing discriminator. Defaults to `NotifTlr/AuthId`. | N/A |
| `obpm.inbound.route.status.discriminator.value.1` | Expected value of the first discriminator for a payment status update. When both discriminator values match the configured status values, the route forwards to `direct:updatePaymentStatus`; otherwise it forwards to `direct:processPaymentIngestion`. | N/A |
| `obpm.inbound.route.status.discriminator.value.2` | Expected value of the second discriminator for a payment status update. | N/A |
| `jms.provider` | **Optional:** JMS listener provider for the inbound connector. Defaults to `weblogic`, which connects to the OBPM WebLogic JMS queues. | N/A |
| `jms.connection.factory` | JMS connection factory name. | `jms-connection-factory` |
| `jms.ssl.enable` | **Optional:** Set to `true` when your JMS connection needs SSL trust. | N/A |
| `jms.ssl.trustStore` | **Optional:** Trust certificate path for SSL trust. | N/A |
| `asb.producer.apiUri` | Callback URI of the Sync Hub ASB producer that receives outgoing events. | N/A |
| `asb.event.topic` | ASB topic for **payment status update** events emitted by the `direct:updatePaymentStatus` route, such as `payment-status`. | N/A |
| `asb.payment.status.event.type` | ASB event type for payment status updates, for example `com.backbase.payment.event.spec.v1.PaymentOrderStatusEvent`. | N/A |
| `asb.payment.status.event.source` | ASB source for payment status update events, for example `com.backbase.payments`. | N/A |
| `asb.payment.status.event.version` | ASB schema version for payment status update events, for example `1.0.0`. | N/A |
| `asb.event.topic.payments.data` | ASB topic for **recurring payment schedule** events emitted by the `direct:processSINotification` route, **future-dated payment ingestion** events, and **off-channel payment ingestion** events emitted by the `direct:processPaymentIngestion` route, such as `payments-data`. | N/A |
| `asb.payments.data.event.type` | ASB event type for recurring payment schedule events, for example `com.backbase.payment.event.spec.v1.PaymentOrderStatusEvent`. | N/A |
| `asb.payments.data.event.source` | ASB source for recurring payment schedule events, for example `com.backbase.payments`. | N/A |
| `asb.payments.data.event.version` | ASB schema version for recurring payment schedule events, for example `1.0.0`. | N/A |
| `retryFlag` | Set to `true` to enable retries on ASB connection failures. | N/A |
| `jms.recover.exception.http.enable` | Set to `true` to enable retries on JMS connection failures. | N/A |
Inbound connectors don't require the common parameters in `values.yaml`.
Create a SOPS secret for the following variables:
| obpm-inbound-secrets | Description | Environmental Key |
| :---------------------------------- | :--------------------------------------------------------------------------------- | -------------------------- |
| `jms.ssl.trustStorePassword` | **Optional:** Trust certificate password when your JMS connection needs SSL trust. | N/A |
| `flexcube.jms.security.principal` | JMS server username to authenticate. | `jms-security-principal` |
| `flexcube.jms.security.credentials` | JMS server password to authenticate. | `jms-security-credentials` |
Follow [How to create SOPS](/platform/developer-guides/build/configure-connector) to create a SOPS secret for the variables listed in the preceding table.
***
The following example shows a sample `inbound-payments-v0.values.yaml` file:
```yaml theme={"system"}
connector:
existingSecretName: obpm-inbound-secrets
properties:
retryFlag: false
asb.producer.apiUri: http://asb-producer-v0.synchub-producer.svc.cluster.local
# ASB configuration for payment status updates
asb.event.topic: payment-status
asb.payment.status.event.type: com.backbase.payment.event.spec.v1.PaymentOrderStatusEvent
asb.payment.status.event.source: com.backbase.payments
asb.payment.status.event.version: 1.0.0
# ASB configuration for recurring payment schedule ingestion
asb.event.topic.payments.data: payments-data
asb.payments.data.event.type: com.backbase.payment.event.spec.v1.PaymentOrderStatusEvent
asb.payments.data.event.source: com.backbase.payments
asb.payments.data.event.version: 1.0.0
# OBPM JMS configuration
jmsFlexCubeUrl: http://wiremock-obpm-jms-payments.gc-obpm.svc.cluster.local:9021
jms.queue.route.mapping: NOTIFOUTQ_EXT>direct:dispatchPaymentNotification,SI_NOTIF_EXT>direct:processSINotification
jms.provider: weblogic
jms.connection.factory: NotifQCF
# Payment notification dispatch routing. The status discriminator values are environment-specific.
obpm.inbound.route.discriminator.xpath.1: NotifTlr/UserId
obpm.inbound.route.discriminator.xpath.2: NotifTlr/AuthId
obpm.inbound.route.status.discriminator.value.1:
obpm.inbound.route.status.discriminator.value.2:
jms.recover.exception.http.enable: true
jms.recover.exception.http.statuses: 429,500,502,503,504
# Added Security configuration
jms.ssl.enable: true
jms.ssl.trustStore: /etc/camel/conf.d/_secrets/obpm-inbound-secret/obpm-ssl-truststore-secret.jks
traits:
knativeservice:
# IMPORTANT: Cost-related. Keeping minScale >0 causes continuous cost even when idle.
# With minScale: 0, each request grants 30 min uptime (extended if new requests arrive).
# Use >0 only if hot start is required, and reset to 0 afterward to avoid unnecessary cost.
minScale: 0 # MinScale set to 0 because there is no connectivity from test to Flexcube
logging:
# DEBUG adds significant log output during startup and runtime.
# This can noticeably slow down starts due to extra logging work and I/O.
# Use only for troubleshooting and disable when not needed.
level: INFO
```
Place the `inbound-payments-v0.values.yaml` file in the following path:
```
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-obpm
└── inbound-payments-v0.values.yaml
```
### Define gc-obpm-direct-debit-mandate-connector parameters
Use these variables, along with the common parameters in `values.yaml`, to configure direct debit mandate outbound connections from **Grand Central to OBPM**.
The direct debit mandate connector doesn't require the Flexcube URLs defined in the common parameters section of `values.yaml`.
The following table lists the available parameters:
| ddmandate-payment-v0.values.yaml | Description |
| :------------------------------- | :----------------------------------------------------------------------- |
| `obpm.getMandateById` | OBPM SOAP path for mandate retrieval by ID. |
| `obpm.searchMandates` | OBPM SOAP path for mandate search. |
| `obpm.closeMandateById` | OBPM SOAP path for mandate termination. |
| `retryFlag` | Set to `true` to enable automatic request retries on connection failure. |
The following example shows a sample `ddmandate-payment-v0.values.yaml` file:
```yaml theme={"system"}
# Sample OBPM direct debit mandate payment Environment Configuration
connector:
properties:
obpm.getMandateById: PMWeb/PMDebtorMandate
obpm.searchMandates: PMWeb/PMDebtorMandate
obpm.closeMandateById: PMWeb/PMDebtorMandate
retryFlag: false
traits:
knativeservice:
# IMPORTANT: Cost-related. Keeping minScale >0 causes continuous cost even when idle.
# With minScale: 0, each request grants 30 min uptime (extended if new requests arrive).
# Use >0 only if hot start is required, and reset to 0 afterward to avoid unnecessary cost.
minScale: 0
logging:
# DEBUG adds significant log output during startup and runtime.
# This can noticeably slow down starts due to extra logging work and I/O.
# Use only for troubleshooting and disable when not needed.
level: INFO
```
Place the `ddmandate-payment-v0.values.yaml` file in the following path:
```
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-obpm
└── ddmandate-payment-v0.values.yaml
```
### Define gc-flexcube-foreign-exchange-connector parameters
Use these variables, along with the common parameters in `values.yaml`, to configure foreign exchange outbound connections from **Grand Central to OBPM**.
The foreign exchange connector doesn't require the OBPM URLs defined in the common parameters section of `values.yaml`.
The following table lists the available parameters:
| foreignexchange-payment-v0.values.yaml | Description |
| :------------------------------------- | :----------------------------------------------------------------------- |
| `retryFlag` | Set to `true` to enable automatic request retries on connection failure. |
The following example shows a sample `foreignexchange-payment-v0.values.yaml` file:
```yaml theme={"system"}
# Sample OBPM foreign exchange Environment Configuration
connector:
properties:
retryFlag: false
traits:
knativeservice:
# IMPORTANT: Cost-related. Keeping minScale >0 causes continuous cost even when idle.
# With minScale: 0, each request grants 30 min uptime (extended if new requests arrive).
# Use >0 only if hot start is required, and reset to 0 afterward to avoid unnecessary cost.
minScale: 0
logging:
# DEBUG adds significant log output during startup and runtime.
# This can noticeably slow down starts due to extra logging work and I/O.
# Use only for troubleshooting and disable when not needed.
level: INFO
```
Place the `foreignexchange-payment-v0.values.yaml` file in the following path:
```
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-obpm
└── foreignexchange-payment-v0.values.yaml
```
## Testing your integration
To access the Payments Unified API, include your Grand Central subscription key in the request header. If you don't have a key, contact the Grand Central Support Team to have one provisioned. The following table shows the required header:
| Key | Value |
| :-------- | :------------------------ |
| `api-key` | `` |
**Inbound status testing:** The inbound connector automatically fetches the payment status without an external trigger.
Test the API using the [Postman collection](.).
## Troubleshooting
If your connector isn't responding as expected, check these common scenarios.
**Cause:** The Grand Central gateway can't establish a handshake with the OBPM endpoint. This typically indicates an upstream service outage at Oracle or a network routing failure.
**Solution:** Verify the operational status of the OBPM environment with Oracle. If the service is operational, contact [GC Support](mailto:gc_support@backbase.com).
**Cause:** The OBPM endpoint didn't respond before the configured read timeout expired. This typically indicates network latency, an overloaded upstream service, or an incorrectly configured timeout value.
**Solution:** Verify network connectivity and OBPM service performance. If the service is operational, review timeout settings in your connector configuration and contact [GC Support](mailto:gc_support@backbase.com).
**Cause:** The `client_id` or `client_secret` provided during setup is incorrect.
**Solution:** Re-verify your credentials with the Oracle portal and contact the GC team to update the connection.
**Cause:** The number of incoming requests has exceeded the defined threshold for your subscription tier. This "429 Too Many Requests" response is a protective measure to ensure the stability of the Grand Central and Core Banking infrastructure.
**Solution:** Review your application's request patterns to identify unexpected spikes. If your business requirements have evolved and you require a higher throughput, contact the Grand Central Team to request an adjustment to your APIM rate limit policy.
***
## Need more help?
Reach out to the Grand Central team for assistance with environment setup or rate limit increases.