> ## 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 and deploy the Feedzai Connector with Grand Central

Complete the following prerequisites and configuration to start using the Feedzai Connector.

## Prerequisites

Before you begin, make sure that the following requirements are met:

* You have completed the steps in the [Get started](/connectors/getting-started).
* You have integrated the Feedzai SDK on your frontend system.
* You have an active Feedzai account. Register your company ID in the Feedzai environment and configure it under the connector configuration.
* You have valid authentication and authorization credentials from Feedzai.
* For private hosting, ensure that the IP address of the cluster or the IP address of the root machine server is on the Feedzai allowlist.

## Configuration

To configure your connector, follow these steps:

1. Set your APIM subscription key in the header as follows:
   * Key: `api-key`
   * Value: `<your subscription key>`

2. Configure the following details in `gc-applications-live`, in the `values.yaml` file. For example:

   ```text theme={"system"}
   ├── iPaaS
   └── azure/runtimes
       ├── dev-v2
       └── test-v2
           └── values
               ├── gc-feedzai
                   └── fraud-v0.values.yaml
   ```

3. Configure the environment details for user activity analysis in the `values.yaml` file:
   * `feedzai.request.orgId` - Company ID issued by Feedzai.
   * `feedzai.base.url` - Feedzai URL.

4. To configure the environment details for New Account Fraud in the `values.yaml` file, use the following:

   * `feedzaiNaf.base.url` - Feedzai NAF URL.

5. Configure the risk score thresholds for the level of assurance (LOA):

   ```properties theme={"system"}
   retryFlag=true
   levelOfAssuranceMin=30
   levelOfAssuranceMid=60
   levelOfAssuranceMax=90
   ```

<Info>
  Set the risk score threshold in consultation with Feedzai based on the business rule definition in the Feedzai engine.
</Info>

The following values are configurable for user-activity-analysis:

* `levelOfAssuranceMin` - The connector returns `LOA_LOW` if the risk score falls below the defined threshold.
* `levelOfAssuranceMid` - The connector returns `LOA_SUBSTANTIAL` if the risk score is below the defined threshold but exceeds the minimum threshold specified in `levelOfAssuranceMin`.
* `levelOfAssuranceMax` - The connector returns `LOA_HIGH` if the risk score exceeds the minimum threshold specified in `levelOfAssuranceMid`. The connector returns `BLOCK` if the risk score exceeds the maximum threshold specified in `levelOfAssuranceMax`.

Optional: To enable retry between Grand Central and Feedzai, set `retryFlag` to true.

## Streaming prerequisites

Before you use Feedzai Digital Trust streaming, complete these additional prerequisites:

* Obtain a Feedzai Digital Trust for Account Monitoring license that includes Streaming API access.
* Assign the Streaming role to a Feedzai API user.
* Request OAuth 2.0 client credentials for the Streaming endpoint. If your tenant uses distinct API users, these credentials are separate from your synchronous scoring credentials.
* Enable outbound HTTPS from the Grand Central connector cluster to the region-specific Feedzai Digital Trust streaming host (EU or US).
* Configure IP allowlisting on both sides of the streaming connection.
* Activate the Feedzai SDK on your web and mobile channels, so that `user_id` and `session_id` are supplied during data gathering and echoed on streamed events.

## Streaming configuration

Configure the following streaming properties on the connector:

```properties theme={"system"}
streaming.upstream.url=https://api.digitaltrust.eu-03.feedzai.cloud/v5/analysis/streaming/session/{orgId}

# SSE reconnect tunables
# Initial back-off delay (ms) before the first reconnect attempt after a failure
sse.reconnect.initialDelayMs=1000
# Maximum back-off delay (ms); the delay is capped at this value
sse.reconnect.maxDelayMs=30000
# Multiplier applied to the current delay after every failed attempt (exponential back-off)
sse.reconnect.backOffMultiplier=2.0
```

**Request filters** (optional, on `POST /stream/session-events`):

* `filter.dataSource`: `web`, `android_sdk`, or `ios_sdk`
* `filter.alertType`: standard Feedzai alert type name
* `filter.numberOfStream`: parallel stream replicas (Feedzai supports up to 3)

The response includes the `vendorSpecificFields.feedzaiStreaming.countermeasures` object only when Active Defense (`activeDefenseEnabled`) is enabled. This flag gates the countermeasures data and is independent of the request filters.

## Connection lifecycle behavior

Understanding how the streaming connection behaves helps you integrate and monitor correctly:

| Event                                                                                                                                                   | Connector behavior                                                                                                                                   | Recommended action                                                           |
| :------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
| **Clean Feedzai closure** (max connection duration approximately 5 minutes, extendable to 10 minutes on the Grand Central side; or vendor idle timeout) | Expected behavior. Connector does not retry. Open a new stream subscription when you need to continue receiving events.                              | Re-subscribe to `/stream/session-events` if you consume the stream directly. |
| **Grand Central-side connection drop** (pod restart, network reset, load balancer drop)                                                                 | Connector retries the SSE connection with exponential back-off, starting at `sse.reconnect.initialDelayMs` and capped at `sse.reconnect.maxDelayMs`. | None if you consume via a Grand Central-managed subscription.                |

<Info>
  Feedzai replays events within a 5-minute window after reconnect. Disconnects longer than 5 minutes may result in permanent event loss for that period.
</Info>

## Test your integration

To access the Fraud 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.

| Key       | Value                     |
| :-------- | :------------------------ |
| `api-key` | `<your_subscription_key>` |

Test the API using the [Postman collection](https://github.com/bb-ecos-ecos/grandcentral-documentation/blob/main/Postman-Collection/GC%20Fraud%20-%20Unified%20Spec.postman_collection.json).

**Test streaming:** Include the same `api-key` header. Call `POST /stream/session-events` with your subscription filters. Verify session events arrive with expected `sessionID`, `userId`, and `score`. Simulate connector pod restart in a non-production environment to validate reconnect behavior.

## Troubleshooting

If your connector isn't responding as expected, check these common scenarios.

<AccordionGroup>
  <Accordion icon="lock" title="5xx: internal server error or core system down">
    **Cause:** The Grand Central gateway can't establish a handshake with the Feedzai endpoint. This typically indicates an upstream service outage at Feedzai or a network routing failure.

    **Solution:** Verify the operational status of the Feedzai environment with Feedzai. If the service is operational, contact the [GC Support](mailto:gc_support@backbase.com) team.
  </Accordion>

  <Accordion icon="wifi-slash" title="5xx: timeout or sockettimeoutexception">
    **Cause:** The request to Feedzai exceeded the configured timeout threshold. This can occur during high load or network latency issues.

    **Solution:** Verify the operational status of the Feedzai environment with Feedzai. If the service is operational, contact the [GC Support](mailto:gc_support@backbase.com) team to review timeout configurations.
  </Accordion>

  <Accordion icon="key" title="Invalid authentication">
    **Cause:** The credentials provided during setup are incorrect.

    **Solution:** Verify your credentials with Feedzai and contact the GC team to update the connection.
  </Accordion>

  <Accordion icon="gauge-high" title="429: rate limit exceeded">
    **Cause:** The number of incoming requests exceeded the defined threshold for your subscription tier. This response protects the stability of the Grand Central and partner infrastructure.

    **Solution:** Review your application's request patterns to identify unexpected spikes. If you require higher throughput, contact the Grand Central team to request an adjustment to your APIM rate limit policy.
  </Accordion>

  <Accordion icon="clock" title="Stream ended after approximately 5 minutes">
    **Cause:** Normal Feedzai clean connection closure at max connection duration. This is expected vendor behavior, not an error.

    **Solution:** Open a new `/stream/session-events` subscription.
  </Accordion>

  <Accordion icon="hourglass" title="No events for 60+ seconds then disconnect">
    **Cause:** Feedzai idle timeout when no session activity exists.

    **Solution:** Expected when no sessions are active. Re-subscribe when monitoring resumes.
  </Accordion>
</AccordionGroup>

## Need more help?

<Card icon="envelope" href="mailto:support@grandcentral.io" title="Contact support">
  Reach out to the Grand Central team for assistance with environment setup or rate limit increases.
</Card>