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

# Working with Providers

> How to use the providers list, understand provider IDs, subsidiaries, and payment schemes.

## Fetching Providers

Use the [Get providers](/api-reference/endpoint/banks) endpoint to retrieve the list of banks available in your environment.

```http theme={null}
GET /api/v1/capabilities/providers
```

**Example response item:**

```json theme={null}
{
  "id": "3a9f7916-1b45-473c-bf34-3e601b8aae90",
  "name": "Swedbank",
  "countryCode": "LT",
  "logoUrl": "https://kashimi.s3.com/logo.png",
  "iconUrl": "https://kashimi.s3.com/icon.png",
  "paymentSchemes": ["SEPA"],
  "requiredPaymentFields": ["SENDER_ACCOUNT"],
  "subsidiaries": [
    {
      "id": "3a9f7916-1b45-473c-bf34-3e601b8aae90",
      "name": "Swedbank",
      "countryCode": "LT",
      "logoUrl": "https://kashimi.s3.com/logo.png",
      "iconUrl": "https://kashimi.s3.com/icon.png",
      "paymentSchemes": ["SEPA"],
      "requiredPaymentFields": ["SENDER_ACCOUNT"]
    }
  ]
}
```

***

## Required Payment Fields

The `requiredPaymentFields` array tells you which additional fields the bank requires in the payment initiation request that are not universally mandatory.

| Value                                  | Meaning                                                                                                           |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `SENDER_ACCOUNT`                       | The bank requires the sender's IBAN to be provided upfront in the payment request body.                           |
| `SENDER_PROVIDER_CREDENTIALS_ID`       | The bank requires the PSU's online banking username or customer ID to be collected before initiating the payment. |
| `SENDER_PROVIDER_CREDENTIALS_PASSWORD` | The bank requires the PSU's online banking password to be collected before initiating the payment.                |

<Info>
  If any of these fields are present, collect the required data from the PSU **before** calling [Initiate Payment](/api-reference/endpoint/initiatePayments) and include them in the request body. If you omit them, Kashimi will prompt the PSU to enter the missing data mid-flow — but providing them upfront results in fewer steps and a smoother experience.
</Info>

<Warning>
  `SENDER_PROVIDER_CREDENTIALS_PASSWORD` means the bank uses an **embedded flow** — the PSU's credentials are collected by your application and passed through Kashimi to the bank. Ensure your UI handles this securely: use HTTPS, never log credentials, and clear them from memory immediately after the request is sent.
</Warning>

Check `requiredPaymentFields` at provider selection time so your UI can collect any necessary data before the payment is initiated, rather than mid-flow.

***

## Provider IDs

<Warning>
  **Do not hardcode provider IDs.** Always fetch the current list from `/api/v1/capabilities/providers` at runtime, or cache it with a short TTL.
</Warning>

Provider IDs are UUIDs that identify a specific bank in a specific country. While IDs are stable under normal conditions, they **can change** — for example, when a provider is deprecated, renamed, or replaced with an updated integration. If you hardcode an ID, your integration may silently break when the ID is retired.

**Recommended approach:**

* On app start or user bank-selection screen, call `/api/v1/capabilities/providers` to get the current list.
* Store the result in a short-lived cache (e.g. 1 hour) rather than hardcoding values.
* Use the `name` + `countryCode` combination to match providers in your UI.

***

## Providers with Subsidiaries

Some banking groups — such as Sparkasse and Volksbanken Raiffeisen — operate as a network of regional banks under a single parent brand. These appear in the API as a top-level provider with a `subsidiaries` array.

Each subsidiary has its own `id`, `name`, `countryCode`, and `paymentSchemes`. When initiating a payment, pass the **subsidiary's `id`**, not the parent's, to route the payment to the correct regional bank.

***

## Payment Schemes

The `paymentSchemes` field on each provider (and subsidiary) lists the schemes supported for that bank:

| Scheme     | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `SEPA`     | SEPA Credit Transfer — used across eurozone and SEPA-member countries              |
| `DOMESTIC` | Domestic transfer scheme — used for local bank transfers within a specific country |

Both schemes may or may not have instant payments enabled depending on the individual bank.

## Instant vs Standard Payments

When initiating a payment, specify your preference using `paymentScheme.preferences.mode`:

| Value      | Behaviour                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------- |
| `INSTANT`  | Requests instant settlement. The bank will attempt to process the payment as a faster transfer. |
| `STANDARD` | Requests standard settlement, regardless of whether the bank supports instant.                  |

```json theme={null}
{
  "paymentScheme": {
    "name": "SEPA",
    "preferences": {
      "mode": "INSTANT"
    }
  }
}
```

<Info>
  `mode` is a **preference**, not a guarantee. Even if you request `INSTANT`, the bank may fall back to standard processing depending on its internal rules or the payment amount. Always check the final payment status rather than assuming instant settlement occurred.
</Info>