Plaid reference

The Plaid Connector calls Plaid Enrich synchronously and publishes enrichment results to Sync Hub. For the environment details you send to Backbase, see Get started.

Configuration properties

Values to obtain from the vendor

Obtain the following values from Plaid and send them to your Backbase support team. Backbase sets them in the connector values files for your runtime. The following table lists each property and its purpose.

Property	Description
`api.plaid.url`	Plaid Enrich API URL for your environment (sandbox or production).
`api.plaid.clientId`	Plaid client ID. Resolves from the `PLAID_CLIENT_ID` environment variable. Banking OS sends this value as the `PLAID-CLIENT-ID` header.
`api.plaid.secret`	Plaid secret. Resolves from the `PLAID_SECRET` environment variable. Banking OS sends this value as the `PLAID-SECRET` header.

gc-plaid-transaction-enrichment-connector

The following table lists Azure Service Bus (ASB) producer properties that gc-plaid-transaction-enrichment-connector uses:

Property	Description	Default
`asb.producer.apiUri`	Callback URI of the Sync Hub ASB producer that receives outgoing events.	No default. Set this value at deployment.
`asb.event.topic`	Topic for enrichment result events.	No default. Set this value at deployment.
`asb.event.source`	Source identifier for outgoing messages.	No default. Set this value at deployment.
`asb.event.type`	Event type for outgoing messages. Use `transactionsEnriched` for the success path.	No default. Set this value at deployment.
`asb.event.version`	Schema version of the published event.	No default. Set this value at deployment.

SOPS secrets

The connector reads Plaid credentials from PLAID_CLIENT_ID and PLAID_SECRET. Backbase stores those environment variables in a SOPS secret.

Supported operations

For the full contract, see API playground.

Method	Endpoint	Purpose
POST	`/internal/transactions/enrichment`	Accept a batch of transactions for enrichment. Returns `202` with an empty body.

An enrichment request must include a UUID enrichmentRequestId, a partyInformation array, and an accounts array. A request can contain a maximum of 50 accounts and 100 transactions in total.

Events

The connector publishes the following Sync Hub events when Plaid Enrich completes.

Event	When emitted
`transactionsEnriched`	Plaid Enrich succeeds, including partial per-item outcomes where applicable.

Published events use the standard Banking OS envelope. The data payload includes per-transaction category, merchant, and location fields. Downstream services can also align with the transactionsEnrichmentRequested Sync Hub payload shape when they initiate enrichment through internal position-keeping or event-driven flows. For more information about event schemas, see API playground.

Requirements and restrictions

The following table lists request limits and connector behavior:

Requirement or restriction	Detail
Batch size	Maximum of 100 transactions per request across all accounts. This limit is fixed in the connector.
Account count	Maximum of 50 accounts per request.
Synchronous vendor call	The connector calls Plaid `POST /transactions/enrich` before publishing to Sync Hub. There is no webhook callback for completion.
Learn and unlearn	Plaid Enrich does not support learn or unlearn category feedback flows. Use SaltEdge if you need those capabilities.
Category taxonomy	Banking OS preserves Plaid native personal finance categories. It does not remap Plaid categories to other vendor taxonomies.
Mandatory request fields	Each enrichment request requires a UUID `enrichmentRequestId`, a `partyInformation` array, and at least one account with at least one transaction. Confirm remaining transaction fields in the Plaid field mapping sheet.

Field mapping

Banking OS maps Plaid Enrich request and response fields to the unified transaction enrichment model. The mapping sheet lists mandatory and optional fields and canonical target paths such as merchantInformation and category fields. For the authoritative mapping reference, see the Plaid field mapping sheet.

Error mapping

The connector maps Plaid error responses to Banking OS status codes. For the full list of Banking OS codes, see Error codes. The following table shows Plaid error_code values and the corresponding Banking OS codes:

Plaid code	Banking OS code
`MISSING_FIELDS`	`GC439`
`INVALID_FIELD`	`GC025`
`INVALID_BODY`	`GC024`
`INVALID_HEADERS`	`GC025`
`UNKNOWN_FIELDS`	`GC025`
`INCOMPATIBLE_API_VERSION`	`GC025`
`NOT_FOUND`	`GC054`
`NO_LONGER_AVAILABLE`	`GC054`
`INVALID_API_KEYS`	`GC001`
`UNAUTHORIZED_ROUTE_ACCESS`	`GC004`
`UNAUTHORIZED_ENVIRONMENT`	`GC004`
`INVALID_PRODUCT`	`GC004`
`INTERNAL_SERVER_ERROR`	`GC028`
`PLANNED_MAINTENANCE`	`GC064`
`RATE_LIMIT`	`GC031`
`RATE_LIMIT_EXCEEDED`	`GC031`
`INVALID_SANDBOX_TRANSACTION`	`GC415`

The following table shows Plaid error_type fallbacks when a more specific error_code mapping does not apply:

Plaid error type	Banking OS code
`INVALID_REQUEST`	`GC025`
`ENRICH_ERROR`	`GC415`

Get started

Core banking

Payments

Card management

KYC and KYB

Open Banking

CRM

Fraud detection

Financial data aggregation