providers

Operator banking-partner configuration: provider connections (write-only credentials), routing rules, KYC connections, inbound provider webhooks and the provider event log.

Markdown version: providers.md

List provider connections

GET /v1/provider-connections

listProviderConnections
API key scope integration:read
Tenant operator

API key scope: integration:read (operator-level keys only, X-Tenant-Id = the operator id).

Parameters

Name	In	Type	Description
`X-Tenant-Id`required	header	Uuid	Tenant context: the operator tenant id (staff operations) or customer tenant id (customer operations). Validated against the caller's memberships; mismatch → `403`. For API keys it must equal the key's customer id (customer-level keys are bound to one customer) or, for operator-level keys (P9-T08b), the operator id.
`X-Request-Id`	header	string	Client-supplied correlation id. Generated by the server when absent; always echoed in the response and in problem details.
`cursor`	query	string	Opaque cursor from `page.nextCursor` or `page.prevCursor`. Must be used with the same `sort` and `filter` as the request that produced it (`400 invalid-cursor` otherwise).
`limit`	query	integer	Page size (max 100).
`sort`	query	string	Sort order; prefix `-` for descending. Cursor stability is guaranteed only for the default sort.
`filter`	query	object	Filters as `filter[field]=value`. Multiple values for one field are comma-separated (OR); different fields combine with AND. Date ranges use `filter[createdFrom]`/`filter[createdTo]` (inclusive, RFC 3339 or date).

Responses

200 OK application/json
Schema ProviderConnectionPage
Cursor-paginated list of ProviderConnection.
- data array of ProviderConnectionrequired
- page PageInforequired
400 Malformed request: unparseable JSON, or an invalid header, path or query parameter (`errors[].field` is `header.X`, `path.x` or `query.x`). Body validation failures are 422 `validation-error`. application/problem+json
Body Problem; see the error catalogue.
401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json
Body Problem; see the error catalogue.
403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json
Body Problem; see the error catalogue.
429 Rate limit exceeded. application/problem+json
Body Problem; see the error catalogue.
default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json
Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/provider-connections" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/provider-connections", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/provider-connections",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()

Get provider connection (no secrets)

GET /v1/provider-connections/{connectionId}

getProviderConnection
API key scope integration:read
Tenant operator

API key scope: integration:read (operator-level keys only, X-Tenant-Id = the operator id).

Parameters

Name	In	Type	Description
`connectionId`required	path	Uuid	Identifier (connectionId).
`X-Tenant-Id`required	header	Uuid	Tenant context: the operator tenant id (staff operations) or customer tenant id (customer operations). Validated against the caller's memberships; mismatch → `403`. For API keys it must equal the key's customer id (customer-level keys are bound to one customer) or, for operator-level keys (P9-T08b), the operator id.
`X-Request-Id`	header	string	Client-supplied correlation id. Generated by the server when absent; always echoed in the response and in problem details.
`If-None-Match`	header	string	Conditional GET; `304` when unchanged.

Responses

200 OK application/json
Schema ProviderConnection
Per-tenant provider connection (ARCHITECTURE §6). Secrets are write-only. One active banking connection per operator and environment (D-32).
- id Uuidrequiredread-only
  Fields of id
  Uuid
- operatorId Uuidrequiredread-only
  Fields of operatorId
  Uuid
- customerId Uuid | null
- provider ProviderIdrequired
- environment ProviderEnvironmentrequired
- name stringrequired
  max length 100
- config ProviderConnectionConfigrequired
- credentialsSet booleanrequiredread-only
  Whether credentials are stored. Credentials are never returned.
- credentialsKid string | nullread-only
- credentialsUpdatedAt Timestamp | null
- credentialsFingerprint string | nullread-only
  Salted HMAC fingerprint (fp_ + 12 hex) so staff can tell credential sets apart without seeing them.
- webhookSecretSet booleanread-only
- webhookUrl string (uri)requiredread-only
  Register this URL with the provider.
- status ConnectionLifecyclerequiredread-only
  Fields of status
  ConnectionLifecycle
- role ConnectionRolerequiredread-only
  Fields of role
  ConnectionRole
- fallbackCurrencies array of CurrencyCoderequiredread-only
  Currencies a fallback connection carries; empty for primaries.
- contractModel ContractModel | nullrequired
- webhookRegistrationState WebhookRegistrationStaterequiredread-only
  Fields of webhookRegistrationState
  WebhookRegistrationState
- healthy boolean | nullread-only
  Health flag from the last health check (error is not a lifecycle state, D-32).
- verifiedAt Timestamp | null
- activatedAt Timestamp | null
- drainingAt Timestamp | null
- retiredAt Timestamp | null
- capabilities objectread-only
  Fields of capabilities
  virtualAccounts boolean
  realAccounts boolean
  sepa boolean
  sepaInstant boolean
  swift boolean
  fasterPayments boolean
  chaps boolean
  bacs boolean
  returns boolean
  statementsCamt053 boolean
  currencies array of CurrencyCode
  fx boolean
  forwards boolean
  heldRates boolean
  cards boolean
  webhooks boolean
  cop boolean
  vop boolean
  directDebit boolean
  bulk boolean
  recalls boolean
- lastHealthAt Timestamp | null
- lastHealth object | nullread-only
  Fields of lastHealth
  ok boolean
  latencyMs integer
  message string | null
- createdAt Timestamprequiredread-only
  Fields of createdAt
  Timestamp
- updatedAt Timestampread-only
  Fields of updatedAt
  Timestamp
304 Not modified (`If-None-Match` matched).
401 Missing, expired or invalid credentials (`unauthenticated`, `session-expired` with `reason` `idle` / `revoked` / `expired`, `invalid-api-key`, `mfa-required`). application/problem+json
Body Problem; see the error catalogue.
403 Authenticated but not allowed: missing capability or scope, tenant not in memberships, `step-up-required`, IP not allow-listed, impersonation restriction. application/problem+json
Body Problem; see the error catalogue.
404 Resource does not exist in this tenant (cross-tenant ids also return 404), or feature disabled (`feature-disabled`). application/problem+json
Body Problem; see the error catalogue.
429 Rate limit exceeded. application/problem+json
Body Problem; see the error catalogue.
default Unexpected error (`500 internal-error`, `501 not-implemented`, `502 provider-error`, `503 service-unavailable`, `504 provider-timeout`). Money operations that time out at the provider are never retried blindly; their state becomes `exception`/unknown and is reconciled. application/problem+json
Body Problem; see the error catalogue.

Code samples

Against the sandbox (https://bank.wirebloom.com/v1).

curl -X GET "https://bank.wirebloom.com/v1/provider-connections/{connectionId}" \
  -H "Authorization: Bearer $WIREBLOOM_API_KEY" \
  -H "X-Tenant-Id: $WIREBLOOM_CUSTOMER_ID"

const response = await fetch("https://bank.wirebloom.com/v1/provider-connections/{connectionId}", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.WIREBLOOM_API_KEY}`,
    "X-Tenant-Id": process.env.WIREBLOOM_CUSTOMER_ID!,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const result = await response.json();

import os

import requests

response = requests.request(
    "GET",
    "https://bank.wirebloom.com/v1/provider-connections/{connectionId}",
    headers={
        "Authorization": f"Bearer {os.environ['WIREBLOOM_API_KEY']}",
        "X-Tenant-Id": os.environ["WIREBLOOM_CUSTOMER_ID"],
    },
    timeout=30,
)
response.raise_for_status()