> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started

> Configure and deploy the FIS Zelle Connector with Grand Central.

export const VendorApiVersionTag = ({versions, label = "Supports"}) => {
  useEffect(() => {
    if (!versions || versions.length === 0) {
      return undefined;
    }
    const findAndSegmentStart = (reference, target) => {
      let i = 0;
      while (i < reference.length && i < target.length && reference[i] === target[i]) {
        i += 1;
      }
      let start = i;
      while (start > 0 && (/[0-9.vR]/).test(target[start - 1])) {
        start -= 1;
      }
      return start;
    };
    const formatText = () => {
      const suffix = " operations";
      if (versions.length === 1) {
        return `${label} ${versions[0]}${suffix}`;
      }
      const [first, ...rest] = versions;
      const last = rest[rest.length - 1];
      const andStart = findAndSegmentStart(first, last);
      const lead = first.slice(0, andStart);
      if (versions.length === 2) {
        return `${label} ${first} and ${last.slice(andStart)}${suffix}`;
      }
      const stems = versions.map(version => version.slice(andStart));
      return `${label} ${lead}${stems.slice(0, -1).join(", ")}, and ${stems[stems.length - 1]}${suffix}`;
    };
    const text = formatText();
    const mountCallout = () => {
      const title = document.querySelector("#page-title");
      const header = title?.closest("header") ?? document.querySelector("#header");
      if (!title || !header || !header.contains(title)) {
        return null;
      }
      let titleBlock = title;
      while (titleBlock.parentElement && titleBlock.parentElement !== header) {
        titleBlock = titleBlock.parentElement;
      }
      let callout = header.querySelector("[data-vendor-api-version-callout='true']");
      if (!callout) {
        callout = document.createElement("div");
        callout.dataset.vendorApiVersionCallout = "true";
        callout.className = "vendor-api-version-callout";
        titleBlock.insertAdjacentElement("afterend", callout);
      }
      callout.replaceChildren();
      const textEl = document.createElement("span");
      textEl.className = "vendor-api-version-text";
      textEl.textContent = text;
      callout.appendChild(textEl);
      return callout;
    };
    let callout = mountCallout();
    if (callout) {
      return () => {
        callout?.remove();
      };
    }
    const observer = new MutationObserver(() => {
      callout = mountCallout();
      if (callout) {
        observer.disconnect();
      }
    });
    observer.observe(document.body, {
      childList: true,
      subtree: true
    });
    return () => {
      observer.disconnect();
      callout?.remove();
    };
  }, [versions, label]);
  return null;
};

export const vendorApiVersions = ["FIS Zelle REST API v4", "FIS PeoplePay SOAP v1.6.0"];

<VendorApiVersionTag versions={vendorApiVersions} />

Complete the following prerequisites and configuration to start using the FIS Zelle Connector.

## Prerequisites

Before you begin, make sure you meet the following requirements:

* You have completed the steps in [Get started with connectors](/grand-central-connectors/get-started).
* You have an active FIS Zelle arrangement (retail, small business, or both) and sandbox or production access through [FIS CodeConnect](https://codeconnect.fisglobal.com/).
* You have network connectivity between Grand Central and FIS Zelle. For supported options, see [Network connectivity](/platform/network-connectivity).
* You have the environment details in the following table from FIS:

| Parameter | Description |
| :- | :- |
| FIS API gateway base URL | Base URL for small-business REST calls (`zelle.rest.base.url`) |
| Retail SOAP endpoint URL | Endpoint for retail Zelle SOAP calls (`zelle.soap.endpoint`) |
| Frontend, source, and environment identifiers | Values FIS expects on each request (`zelle.fis.fe-id`, `zelle.fis.source-id`, `zelle.fis.environment-id`) |
| Application identifier | Application identity for FIS (`zelle.fis.application-id`) |
| OAuth2 client credentials | Client ID and client secret for the FIS token endpoint |
| Bank secret key (small business) | Secret used in the Zelle sign-in request and related FIS identity configuration |
| Retail SOAP mTLS material | Client PKCS12 keystore, passphrase, and CA certificate for PeoplePay |

<Info>
  The FIS user acceptance testing (UAT) pack usually includes sandbox gateway URLs and non-secret identifiers. Share application secrets and the bank secret key only through a secure channel with Grand Central research and development or Grand Central operations.
</Info>

## Configuration

To configure the connector, follow these steps:

1. Complete any Grand Central APIM or subscription-key setup your environment requires. For the shared connector setup flow, see [Get started with connectors](/grand-central-connectors/get-started).

2. Obtain environment-specific values from FIS. For the property list, see [Reference](/connectors/payments/fis-zelle/reference).

3. Set the connector properties in the `gc-applications-live` repository.

   On ecos-dev, the Argo CD application `gc-fis-zelle` deploys two charts that share the `fis-zelle` SOPS secret:

   The following table lists the charts and values files.

   | Chart | Values file | Domain |
   | :- | :- | :- |
   | `gc-fis-zelle-payment-order-connector` | `payment-order-v2.values.yaml` | Payer and payer account management |
   | `gc-fis-zelle-party-authentication-connector` | `party-authentication-v0.values.yaml` | Zelle sign-in |

   The following example shows a typical file location:

   ```text theme={"system"}
   ├── iPaaS
   └── azure/runtimes
       └── <runtime>
           └── values
               └── gc-fis-zelle
                   ├── payment-order-v2.values.yaml
                   └── party-authentication-v0.values.yaml
   ```

   `<runtime>` is usually `dev`, `test`, and so on.

4. Store credentials and certificates in the `fis-zelle` SOPS secret. Do not put passwords, secret keys, or PKCS12 material in plain values files. For more information, see [Configure a connector](/platform/developer-guides/build/configure-connector).

   Example shape for payment-order values (replace placeholders with values from FIS and the Grand Central team):

   ```yaml theme={"system"}
   connector:
     existingSecretName: fis-zelle
     properties:
       retail.endpointType: soap
       business.endpointType: rest
       zelle.rest.base.url: "https://api-gw-uat.fisglobal.com"
       zelle.soap.endpoint: "<retail-soap-endpoint>"
       zelle.fis.application-id: "<application-id>"
       zelle.fis.source-id: "<source-id>"
       zelle.fis.fe-id: "<fe-id>"
       zelle.fis.environment-id: "uat"
       # OAuth2 client-id/secret, PKCS12 passphrase, and zelle.fis.secret-key
       # belong in the fis-zelle SOPS secret, not in plain text
     traits:
       knativeservice:
         minScale: 0
       logging:
         level: INFO
   ```

5. Include the `Line-Of-Business` header on unified API calls (`Retail` or `Business`). The connector routes to the matching FIS channel.

<Note>
  FIS requires a bank routing number when you register a funding account. When the Grand Central request has no routing-number field, pass the ABA routing number in the `customFields.bankCode` field on that request. When FIS requires the bank name for Retail SOAP, also pass the `customFields.bankName` field on that request.
</Note>

## Test your integration

When you call the unified API, include your Grand Central subscription key in the request header.

The following table shows the required header:

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

Suggested smoke checks in sandbox:

1. **Payer management**: Register a test customer, then search. For `Business`, you can also retrieve by ID. For `Retail`, use search instead of retrieve by ID.
2. **Payer account management**: Register a funding account (include routing number), list accounts, then retrieve one by ID.
3. **Sign in to Zelle**: Initiate sign-in and confirm a usable Zelle URL or redirect payload.

For the full contract, see [API playground](/grand-central-apis/api-playground). For operations and properties, see [Overview](/connectors/payments/fis-zelle/overview) and [Reference](/connectors/payments/fis-zelle/reference).

## Troubleshooting

If the connector does not respond as expected, check these common scenarios.

<AccordionGroup>
  <Accordion icon="key" title="Authentication failure with FIS">
    **Cause:** FIS credentials, application identifiers, or the bank secret key are missing, expired, or wrong for the environment.

    **Solution:** Confirm the values with FIS, update the `fis-zelle` SOPS secret with the Grand Central team, and retry in the same environment (for example UAT only with UAT credentials).
  </Accordion>

  <Accordion icon="wifi-slash" title="Timeout or connectivity error">
    **Cause:** Grand Central cannot reach the FIS gateway or retail SOAP endpoint in time.

    **Solution:** Confirm network routing and that the FIS environment is up. If both look healthy, contact [GC Support](mailto:gc_support@backbase.com).
  </Accordion>

  <Accordion icon="user" title="Payer registration rejected">
    **Cause:** Required customer fields for that channel are missing (small business often needs identifiers such as user ID, date of birth, tax ID, and terms acceptance date).

    **Solution:** Compare the request with the [API playground](/grand-central-apis/api-playground) contract for the operation, supply the missing values for that line of business, and retry.
  </Accordion>

  <Accordion icon="building-columns" title="Funding account rejected">
    **Cause:** The bank routing number or the account details in the request aren't in the format FIS expects.

    **Solution:** Include the ABA routing number in the `customFields.bankCode` field on the request. When FIS requires the bank name for Retail SOAP, add the `customFields.bankName` field on the request. Verify the account number and account type, and confirm that the payer registration ID is valid.
  </Accordion>

  <Accordion icon="right-to-bracket" title="Sign-in does not return a Zelle URL">
    **Cause:** Sign-in prerequisites failed (secret key, return URL, session context, or wrong line of business).

    **Solution:** Verify the return URL and secret key for small business, confirm the customer is already enrolled, and confirm the call uses a channel that supports the sign-in operation.
  </Accordion>

  <Accordion icon="gauge-high" title="429: Rate limit exceeded">
    **Cause:** Request volume exceeded the rate limit for the Grand Central subscription.

    **Solution:** Reduce request volume or ask the Grand Central team to adjust the APIM rate limit for the program.
  </Accordion>
</AccordionGroup>