Get started

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 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.
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 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. 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:

# Sample for device-administration-v2 yaml tietoevry environment configuration
connector:
  existingSecretName: tietoevry-secret
  properties:
    tietoevry.baseUrl: <<X-EVRY-URL>>
    tietoevry.client.clientname: <<X-EVRY-CLIENT-CLIENTNAME>>
    tietoevry.dataownerorgid: <<X-EVRY-DATAOWNERORGID>>
    tietoevry.origin: <<X-EVRY-ORIGIN>>
    tietoevry.userorgid: <<X-EVRY-USERORGID>>
    tietoevry.user.ipaddress: <<Your POD ip address>>

Place the values.yaml file in the following path:

├── 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 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:

# Sample for device-administration-v2 yaml tietoevry environment configuration
connector:
  properties:
    tietoevry.sourceApplication: <<X-EVRY-CLIENT-CLIENTNAME>>
    tietoevry.orgunit: <<X-EVRY-USERORGID>>
    tietoevry.orgid: <<X-EVRY-USERORGID>>
    tietoevry.instId: <<X-EVRY-USERORGID>>

Place the device-administration-v2.values.yaml file in the following path:

├── 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:

# 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:

├── 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 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 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:

# Sample for card-authorization-v1.values.yaml tietoevry environment configuration
connector:
  existingSecretName: tietoevry-secret
  properties:
    api.googlePay.cardAppId: <<VISA_VTS_CARD_APP_ID>>

Place the card-authorization-v1.values.yaml file in the following path:

├── 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	`<YOUR_SUBSCRIPTION_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.

Troubleshooting

If your connector isn’t responding as expected, review the following common scenarios.

5XX: Internal server error / Core system is down

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.

5XX: Timeout from core / Read timeout / SocketTimeoutException

Invalid OAuth token

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.

429: Rate limit exceeded

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?

Contact Support

Reach out to the Grand Central team for assistance with environment setup or rate limit increases.

Overview

Grand Central connectors

Release notes

Prerequisites

Configuration guide

1. Establish connectivity

2. Configure the environment

Define common parameters

Define gc-tietoevry-device-administration-connector parameters

Define gc-tieto-evry-card-ecommerce-gateway-webhooks-connector parameters

3DS Secure Authentication configuration

Define gc-tieto-evry-card-authorization-connector parameters

Test your integration

Troubleshooting

Cause

Solution

Need help?

Contact Support

​Prerequisites

​Configuration guide

​1. Establish connectivity

​2. Configure the environment

​Define common parameters

​Define gc-tietoevry-device-administration-connector parameters

​Define gc-tieto-evry-card-ecommerce-gateway-webhooks-connector parameters

3DS Secure Authentication configuration

​Define gc-tieto-evry-card-authorization-connector parameters

​Test your integration

​Troubleshooting

​Cause

​Solution

​Need help?

Contact Support

Prerequisites

Configuration guide

1. Establish connectivity

2. Configure the environment

Define common parameters

Define gc-tietoevry-device-administration-connector parameters

Define gc-tieto-evry-card-ecommerce-gateway-webhooks-connector parameters

Define gc-tieto-evry-card-authorization-connector parameters

Test your integration

Troubleshooting

Cause

Solution

Need help?