> ## 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
> Configure the Tietoevry Card Management Connector by completing the prerequisites, defining environment variables, and testing the integration.
Complete the following prerequisites and configuration steps to integrate the Tietoevry Connector.
## Prerequisites
Before you begin, ensure you have the following credentials and connectivity in place:
* Follow the [Get started with connectors](https://grandcentral.backbase.io/connectors/getting-started) guide.
* **Tietoevry access:** An active account in the Tietoevry environment.
* **Network connectivity:** Confirmed routing between Tietoevry and the Grand Central (GC) iPaaS. For supported options, see [Network connectivity](https://grandcentral.backbase.io/platform/network-connectivity).
* **Environment details:** You need the following environment variables from Tietoevry to configure the connector:
| Key | Description |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **X-EVRY-URL** | The URL to connect to Tietoevry services |
| **X-EVRY-ORIGIN** | Specifies the source platform of the request (for example, Mobile or Web). |
| **X-EVRY-USERORGID** | Defines the institution that the user (X-EVRY-USERID) belongs to. Typically used in combination with X-EVRY-DATAOWNERORGID to manage access control to institution data. |
| **X-EVRY-CLIENT-CLIENTNAME** | Identifies the source sending the request. Used to separate different service consumers. The name should identify the institution and consumer app. |
| **X-EVRY-DATAOWNERORGID** | Identifies the organization that owns the requested data. Used to ensure that the authenticated institution has access to the requested institution's data. Financial institution registered in the banking infrastructure. |
| **HTTP signing material** | RSA private key (**X-SIGNATURE-PRIVATE-KEY-PEM**) and key ID (**X-SIGNATURE-KEYID**) provided by Tietoevry. Used to generate the `Signature` header on outbound requests. Store as `signature.privateKeyPem` and `signature.keyId` in the SOPS secret below. |
The Device Administration Connector and the Card Authorization Connector require a secret file containing the Tietoevry private key that Tietoevry provides. You need this private key to authenticate against and invoke the Tietoevry APIs.
## Configuration guide
Follow these steps to initialize and authorize your Tietoevry Connector.
### 1. Establish connectivity
Share the connectivity details with the Grand Central team as described on the [Network connectivity](https://grandcentral.backbase.io/platform/network-connectivity) page for your chosen connection between **Grand Central** and **Tietoevry**.
### 2. Configure the environment
To initialize the Tietoevry Connector, you must define specific environment variables within your `gc-applications-live` repository.
For the full property list for each connector, including defaults and descriptions, see [Reference](/connectors/card-management/tietoevry/reference).
Common variables are stored in `values.yaml`. Connector-specific variables are stored in the following files:
| Connector | Property | Description |
| :---------------------------------------------- | :----------------------------------- | :--------------------------------------------------------------- |
| `gc-tieto-evry-device-administration-connector` | device-administration-v2.values.yaml | Tietoevry Connector for card number generation and card creation |
| `gc-tieto-evry-card-authorization-connector` | card-authorization-v1.values.yaml | Card authorization connector to sign off the created card |
#### Define common parameters
These common variables apply to the Tietoevry connectors when traffic flows between **Grand Central** and **Tietoevry**.
| **Key** | **Description** | Environmental Key |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- |
| tietoevry.baseUrl | Base URL of Tietoevry. | **X-EVRY-URL** |
| tietoevry.client.clientname | Identifies the source sending the request and separates different service consumers. The name should identify the institution and consumer app. | **X-EVRY-CLIENT-CLIENTNAME** |
| tietoevry.dataownerorgid | Data owner InstId. Identifies the organization that owns the requested data. This property ensures that the authenticated institution can view the requested institution's data. The value represents a financial institution registered in the banking infrastructure. | **X-EVRY-DATAOWNERORGID** |
| tietoevry.origin | Distinguishes request origins between Open Banking third parties, Open Banking third parties under PSD2, and the bank's internal use. | **X-EVRY-ORIGIN** |
| tietoevry.userorgid | Defines the institution that the user identified by X-EVRY-USERID belongs to. Use this property in combination with X-EVRY-DATAOWNERORGID to manage access control to institution data. | **X-EVRY-USERORGID** |
| tietoevry.user.ipaddress | Client IP address or DNS address from the device sending the request. Separates requests from different devices. | N/A — set per pod |
The following is a sample `values.yaml` file:
```yaml theme={"system"}
# Sample for device-administration-v2 yaml tietoevry environment configuration
connector:
existingSecretName: tietoevry-secret
properties:
tietoevry.baseUrl: <>
tietoevry.client.clientname: <>
tietoevry.dataownerorgid: <>
tietoevry.origin: <>
tietoevry.userorgid: <>
tietoevry.user.ipaddress: <>
```
Place the `values.yaml` file in the following path:
```text theme={"system"}
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-tietoevry
└── values.yaml
```
Create a SOPS secret for the following variables:
| tietoevry-secret | Description | Environmental Keys |
| :------------------------ | :---------------------------------------------------------------------- | :--------------------------- |
| `signature.keyId` | The key ID generated from the shared private key. | X-SIGNATURE-KEYID |
| `signature.privateKeyPem` | PEM file generated from the private key to authenticate the connection. | X-SIGNATURE-PRIVATE-KEY\_PEM |
Follow [how to create SOPS](https://grandcentral.backbase.io/platform/development-cycle/build/configure-connector) to create a new SOPS secret for the preceding variables.
#### Define gc-tietoevry-device-administration-connector parameters
Use these variables, together with the common parameters described previously, to configure connections for card creation and number generation services from **Grand Central** to **Tietoevry**.
| `device-administration-v2.values.yaml` | Description |
| :------------------------------------- | :---------------------------------------------------------------- |
| tietoevry.sourceApplication | Identifies the source app sending the request. |
| tietoevry.orgunit | Organization unit identifier included in Tietoevry SOAP requests. |
| tietoevry.orgid | Organization identifier included in Tietoevry SOAP requests. |
| tietoevry.instId | Institution identifier included in Tietoevry SOAP requests. |
The following is a sample `device-administration-v2.values.yaml` file:
```yaml theme={"system"}
# Sample for device-administration-v2 yaml tietoevry environment configuration
connector:
properties:
tietoevry.sourceApplication: <>
tietoevry.orgunit: <>
tietoevry.orgid: <>
tietoevry.instId: <>
```
Place the `device-administration-v2.values.yaml` file in the following path:
```text theme={"system"}
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-tietoevry
└── device-administration-v2.values.yaml
```
#### Define gc-tieto-evry-card-ecommerce-gateway-webhooks-connector parameters
Use these variables to configure the webhook connection from **Tietoevry** to **Grand Central**.
The webhook connector doesn't need the common parameter section under `values.yaml`.
It does need a callback URL from the upstream system. **Grand Central** uses this URL to forward messages received from Tietoevry. The following example shows one from a Backbase EBP upstream system.
**Webhook registration:** to process asynchronous updates, you must share the **Grand Central** webhook URL with Tietoevry, who registers it on their side.
| `card-ecommerce-gateway-webhooks-v1.values.yaml` | Description |
| :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ebp.baseurl | Base URL of the EBP. |
| ebp.challenge.endpoint | Relative path of the authentication challenge endpoint. This endpoint initiates the 3DS authentication flow and generates a challenge for the cardholder. |
| ebp.completion.endpoint | Relative path of the authentication completion endpoint. This endpoint completes or validates the authentication challenge and finalizes the 3DS authentication process. |
The following is a sample `card-ecommerce-gateway-webhooks-v1.values.yaml` file:
```yaml theme={"system"}
# Sample for card-ecommerce-gateway-webhooks-v1.values.yaml tietoevry environment configuration
connector:
properties:
ebp.baseurl: "http://wiremock-tietoevry-cards.gc-tietoevry.svc.cluster.local:9021"
ebp.challenge.endpoint: "/authentication/challenge"
ebp.completion.endpoint: "/authentication/completion"
```
Place the `card-ecommerce-gateway-webhooks-v1.values.yaml` file in the following path:
```text theme={"system"}
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-tietoevry
└── card-ecommerce-gateway-webhooks-v1.values.yaml
```
##### 3DS Secure Authentication configuration
The Card eCommerce Gateway Webhooks connector handles 3DS Secure Authentication flows between Tietoevry and the EBP:
* **Inbound (Tietoevry → Grand Central):** Share the Grand Central webhook URL (obtained from Azure APIM) with Tietoevry, along with the required API key. For the inbound webhook API specification, see the [grandcentral-tieto-evry-card-ecommerce-gateway-webhooks-api](https://github.com/bb-ecos-ecos/grandcentral-tieto-evry-card-ecommerce-gateway-webhooks-api) contract.
* **Outbound (Grand Central → EBP):** Configure the EBP base URL and the challenge and completion endpoint paths above. For the outbound API contract, see the [grandcentral-card-ecommerce-gateway-api](https://github.com/bb-ecos-ecos/grandcentral-card-ecommerce-gateway-api) specification.
#### Define gc-tieto-evry-card-authorization-connector parameters
Use the common parameters described previously, plus the following connector-specific property, to configure the card authorization connector from **Grand Central** to **Tietoevry**.
The following table describes the connector-specific property for the card authorization connector:
| Property | Description | Default |
| :------------------------ | :-------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
| `api.googlePay.cardAppId` | Visa VTS identifier sent as the `cardAppId` query parameter on Google Pay (Android) push-provisioning requests. | `com-evry-android-cardcompanion-wb` |
The following is a sample `card-authorization-v1.values.yaml` file:
```yaml theme={"system"}
# Sample for card-authorization-v1.values.yaml tietoevry environment configuration
connector:
existingSecretName: tietoevry-secret
properties:
api.googlePay.cardAppId: <>
```
Place the `card-authorization-v1.values.yaml` file in the following path:
```text theme={"system"}
├── iPaaS
└── azure/runtimes
├── dev
└── test
└── values
├── gc-tietoevry
└── card-authorization-v1.values.yaml
```
## Test your integration
To call the Cards 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 request one.
| Key | Value |
| :------ | :------------------------ |
| api-key | `` |
**Webhook integration:** share the API key with Tietoevry through 1Password or another standard credential-sharing tool so Tietoevry can call the inbound APIs.
Test the API using the [Device Administration V2 Postman collection](https://github.com/bb-ecos-ecos/grandcentral-documentation/blob/main/Postman-Collection/GC%20Device%20Administration-V2%20-%20Unified%20Spec.postman_collection.json).
## Troubleshooting
If your connector isn't responding as expected, review the following common scenarios.
**Cause:** the Grand Central (GC) gateway can't establish a handshake with the Tietoevry endpoint. This typically indicates an upstream service outage at Tietoevry or a network routing failure.
**Solution:** verify the operational status of the Tietoevry environment with Tietoevry. If the service is operational, contact the **GC Support** team.
**Cause:** the Grand Central (GC) gateway can't establish a handshake with the Tietoevry endpoint. This typically indicates an upstream service outage at Tietoevry or a network routing failure.
**Solution:** verify the operational status of the Tietoevry environment with Tietoevry. If the service is operational, contact the **GC Support** team.
### Cause
Request authentication failed due to an invalid or mismatched HTTP signature or digest. This can occur when one or more of the following conditions apply:
* The RSA signature does not match the signed headers or request payload.
* The digest value was calculated from a request body that differs (even by whitespace or encoding) from the body sent to Tietoevry.
* One or more mandatory X-EVRY-\* headers are missing, incorrectly set, or not included in the signature.
* The `keyId` in the Signature header does not match the public key registered with Tietoevry.
* The `(request-target)` or `(created)` values used during signature generation do not align with the actual request.
* Clock skew between the client and Tietoevry systems causes the `created` timestamp to fall outside the accepted window.
### Solution
* Regenerate the HTTP signature, ensuring that:
* All required headers (X-EVRY-\*, (request-target), (created), and digest) are included and signed in the correct order.
* The digest is computed using the **exact request body bytes** sent over the wire (no formatting or whitespace differences).
* The `keyId` corresponds to the RSA key pair registered with Tietoevry.
* Verify that the request body encoding is UTF-8 and that the `Content-Type` header is correctly set.
* Ensure system clocks are synchronized to avoid timestamp validation issues.
* If the issue persists, verify the encryption and signing logic with Tietoevry. Tietoevry provides or validates the expected signature and digest generation logic as part of the integration support process.
**Cause:** the number of incoming requests exceeds the defined threshold for your subscription tier. This 429 Too Many Requests response protects the stability of the Grand Central and core banking infrastructure.
**Solution:** review your app's request patterns to identify unexpected spikes. If your business requirements change and you need higher throughput, contact the Grand Central team to request an adjustment to your APIM rate limit policy.
## Need help?
Reach out to the Grand Central team for assistance with environment setup or rate limit increases.