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

# Setting up the integration

> A complete guide to configuring the Pix Indirect Plugin (BTG) — from licensing and authentication to Midaz, CRM, BTG connectivity, and worker setup.

The Pix Indirect Plugin (BTG) connects to multiple Lerian services and external providers to process Pix payments. Setting it up involves configuring the plugin's connection to each service and preparing the data those services need to operate.

The plugin runs as two main layers — an **Application** that exposes the Pix API and processes business logic, and a set of **Workers** that handle inbound webhooks from BTG, outbound event delivery to your system, and DICT reconciliation with BACEN. Both layers share the same foundational configuration (license, Midaz, CRM, BTG) but have their own service-specific settings.

# Prerequisites

***

Before you begin, make sure you have:

* Your **ISPB** (Identificador do Sistema de Pagamentos Brasileiro) — the 8-digit identifier derived from your institution's CNPJ
* Access to your **Midaz** and **CRM** instances (deployed and running)
* Access to **BTG** provider services (BTG provides the credentials)

```bash theme={null}
# Your institution's ISPB (8 digits)
PIX_ISPB=12345678
```

<Note>
  `PIX_ISPB` is also used to detect **intra-PSP (P2P) transfers**: when a transfer's destination ISPB matches this value, the plugin settles it internally instead of routing it to BTG, while still reporting it to BACEN. See [Intra-PSP transfers](/en/midaz/plugins/pix/indirect/indirect-pix-intra-psp).
</Note>

# 1. License

***

The plugin is an enterprise solution and requires a valid license to operate. Lerian provides the license key during onboarding.

```bash theme={null}
# License key provided by Lerian
LICENSE_KEY=

# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=
```

**Related documentation:** [Lerian's License](/en/reference/lerians-license)

# 2. Access Manager (optional)

***

Access Manager handles authentication for the plugin. When enabled, it validates all incoming requests before they reach the plugin's API.

```bash theme={null}
# Require authentication for all plugin requests (true/false)
PLUGIN_AUTH_ENABLED=false

# Access Manager service URL
PLUGIN_AUTH_ADDRESS=
```

When `PLUGIN_AUTH_ENABLED=true`, the plugin validates every request's `Authorization` header to ensure:

* The token belongs to an authorized user or application
* The token grants access to the requested API endpoint and method

<Note>
  You only need to provide client credentials (`CLIENT_ID` / `CLIENT_SECRET`) for Midaz, CRM, and Fee services if those services also have Access Manager authentication enabled.
</Note>

**Related documentation:** [Access Manager](/en/platform/access-manager/access-manager)

# 3. Midaz

***

Midaz is the core ledger for all Pix transactions the plugin processes. The plugin posts every cash-in, cash-out, and refund operation to Midaz as a double-entry transaction.

## Connection

***

```bash theme={null}
# Your organization ID in Midaz
MIDAZ_ORGANIZATION_ID=

# Your ledger ID in Midaz
MIDAZ_LEDGER_ID=

# Midaz Transaction module URL
MIDAZ_TRANSACTION_URL=

# Midaz Onboarding module URL
MIDAZ_ONBOARDING_URL=

# Midaz API credentials (required if Midaz has authentication enabled)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=
```

## Asset requirements

***

Configure an asset in your organization and ledger with these properties:

| Property | Value      |
| -------- | ---------- |
| Type     | `currency` |
| Code     | `BRL`      |

Link all accounts to your ledger using the `BRL` asset. The plugin rejects operations on accounts that don't match this configuration.

## Account setup

***

Before using the plugin, create an account in Midaz for each customer under your ISPB.

Use the **Create an Account** endpoint to set up accounts. Each account must:

* Belong to your configured organization and ledger
* Use the `BRL` asset

## X-Account-Id header

***

Many Pix operations require the `X-Account-Id` header to identify which account is performing the action. This ID corresponds to the **Midaz ledger account ID**.

When you call a plugin endpoint, the `X-Account-Id` value tells the plugin:

* Which account to use for ledger operations
* Which customer data to fetch from CRM
* Which balance to validate and update

### How the plugin uses the account ID

The plugin uses the account ID differently depending on the operation type:

| Flow type                                               | How the plugin uses the account ID                        |
| ------------------------------------------------------- | --------------------------------------------------------- |
| **Non-transactional** (e.g., creating keys or QR codes) | Fetches customer and bank account data from CRM           |
| **Transactional** (e.g., payments, refunds)             | Fetches customer data for payment initiation              |
|                                                         | Validates account data for incoming payment authorization |
|                                                         | Executes the transaction in the ledger                    |

## Account compliance

***

The plugin does **not** enforce business-level account restrictions, such as blocked or suspended accounts. Your application is responsible for validating account status before calling the plugin.

To prevent Pix settlements on a specific account, block it directly in Midaz. The plugin receives a rejection when it attempts to post the transaction.

**Related documentation:**

* [Update an Account](/en/reference/midaz/update-an-account)
* [Update a Balance](/en/reference/midaz/update-a-balance)

# 4. CRM

***

The CRM stores customer (holder) information and their associated bank accounts. Every Midaz account must have a corresponding **holder** and **alias account** in the CRM to perform Pix operations.

The plugin queries CRM data to:

* Register and validate Pix keys
* Build payment messages for BACEN
* Authorize incoming transactions
* Process refund and dispute workflows

## Connection

***

```bash theme={null}
# CRM base URL
PLUGIN_CRM_BASE_URL=

# CRM API credentials (required if CRM has authentication enabled)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=
```

## Holders

***

Holder data represents the customer who owns the account. Create each holder in the CRM before executing any Pix operation for that customer.

### Required fields

| Field      | Requirement                                                                                          | Example              |
| ---------- | ---------------------------------------------------------------------------------------------------- | -------------------- |
| `name`     | Maximum 120 characters                                                                               | `Maria Silva Santos` |
| `document` | For `NATURAL_PERSON`, a CPF with 11 digits; for `LEGAL_PERSON`, a CNPJ with 14 digits (numbers only) | `12345678900`        |
| `type`     | Person type (enum values from CRM)                                                                   | `NATURAL_PERSON`     |

### Optional fields

| Field                   | When to use                                     |
| ----------------------- | ----------------------------------------------- |
| `legalPerson.tradeName` | When associating a trade name with the key data |
| `addresses.primary`     | Required for Due Date collection creation       |

**Related documentation:** [Create a Holder](/en/reference/midaz/crm/create-holder)

## Alias accounts

***

Alias accounts link a Midaz account to its banking details. Each alias account must include the banking information that the Pix ecosystem requires for transaction processing.

### Required fields

| Field                        | Requirement                    | Example                                |
| ---------------------------- | ------------------------------ | -------------------------------------- |
| `accountId`                  | Midaz account ID (UUID)        | `3c90c3cc-0d44-4b50-8888-8dd25736052a` |
| `bankingDetails.branch`      | Exactly 4 digits               | `0001`                                 |
| `bankingDetails.account`     | 1 to 20 digits                 | `123456789`                            |
| `bankingDetails.type`        | Account type (see table below) | `CACC`                                 |
| `bankingDetails.openingDate` | YYYY-MM-DD format              | `2024-01-15`                           |

<Warning>
  The `bankingDetails.branch` field must contain exactly **4 digits**. Pad with leading zeros if necessary. For example, if the branch number is `1`, register it as `0001`. The plugin can only validate the account in the CRM when the branch code follows this format.
</Warning>

### Supported account types

| Code   | Description         |
| ------ | ------------------- |
| `CACC` | Checking account    |
| `SLRY` | Salary account      |
| `SVGS` | Savings account     |
| `TRAN` | Transaction account |

**Related documentation:** [Create an Alias Account](/en/reference/midaz/crm/create-alias-account)

# 5. BTG provider

***

BTG is the direct participant that connects your institution to BACEN's Pix infrastructure. BTG provides the credentials directly when your institution signs up for indirect BACEN integration.

## Connection

***

```bash theme={null}
# BTG API base URL
BTG_BASE_URL=

# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=
```

## mTLS (webhook security)

***

Mutual TLS (mTLS) adds an extra layer of security by validating BTG's certificate on webhook requests. This ensures that incoming webhooks genuinely originate from BTG.

```bash theme={null}
# Enable mTLS validation (true/false)
# Use 'true' in production, 'false' for local development
MTLS_ENABLED=false

# How long to cache the certificate before refreshing
# Format: Go duration (e.g., 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# BTG endpoint that provides the public certificate for signature validation
BTG_CERTIFICATE_URL=

# Timeout for certificate fetch requests
# Format: Go duration (e.g., 10s, 30s)
MTLS_HTTP_TIMEOUT=10s
```

<Warning>
  Always enable mTLS in production environments. Only disable it during local development.
</Warning>

# 6. Fee service (optional)

***

Enable fee calculation to automatically charge and distribute fees on incoming payments. This is optional — if you don't configure it, the plugin processes transactions without fee calculation.

## Connection

***

```bash theme={null}
# Fee calculation method (currently only 'segment' is supported)
CASHIN_FEE_CALCULATION_TYPE=

# Fee service URL
FEE_SERVICE_URL=

# Request timeout in milliseconds
FEE_SERVICE_TIMEOUT=5000

# Fee service API credentials (required if the fee service has authentication enabled)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=
```

## How it works

***

When you set `CASHIN_FEE_CALCULATION_TYPE=segment`, the plugin:

1. **Retrieves the segment** associated with the receiving account
2. **Calculates applicable fees** before processing the transaction in Midaz
3. **Distributes the incoming payment** according to any package rules linked to that segment

## Setup steps

***

1. **Create segments in Midaz** — Define the account segments that determine fee rules
2. **Configure packages in Fee Engine** — Link each segment to its fee calculation rules
3. **Assign segments to accounts** — Create or update Midaz accounts with the appropriate segment ID

**Related documentation:**

* [Fee Engine - Guides](/en/midaz/plugins/fees-engine/fees-engine-overview)
* [Fee Engine - APIs](/en/reference/midaz/plugins/fees-engine/create-package)

# 7. DICT reconciliation (VSync)

***

VSync reconciles your local DICT data with BACEN by processing all key-related events from the day. This ensures your local state stays consistent with BACEN's authoritative records.

```bash theme={null}
# Write block window (24-hour format, UTC)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Allowed network range for reconciliation services
RECONCILIATION_INTERNAL_CIDR=
```

<Warning>
  During reconciliation, the database temporarily blocks write operations to prevent data inconsistencies with BACEN. Plan the write block window during low-traffic periods.
</Warning>

<Note>
  The CIDR range restricts which networks can trigger reconciliation. The plugin automatically rejects requests from outside this range.
</Note>

## Redis cache configuration

***

VSync uses Redis to cache BTG/DICT entries and CRM holders during reconciliation. In Helm deployments the default `REDIS_HOST` points to the built-in Valkey sidecar, so no extra setup is required for a standard install.

```bash theme={null}
# Connection (always used)
REDIS_HOST=<release>-valkey:6379
REDIS_MASTER_NAME=
REDIS_DB=0
REDIS_PROTOCOL=3

# Connection pool and retries (always used)
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2
REDIS_MAX_RETRIES=3
REDIS_MIN_RETRY_BACKOFF=8
REDIS_MAX_RETRY_BACKOFF=512

# Authentication (optional — only used if set)
REDIS_PASSWORD=

# TLS (optional — only used if REDIS_TLS=true)
REDIS_TLS=false
REDIS_CA_CERT=

# GCP IAM authentication (optional — only used if REDIS_USE_GCP_IAM=true)
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
REDIS_TOKEN_LIFETIME=60
REDIS_TOKEN_REFRESH_DURATION=45

# VSync cache TTLs (always used)
CACHE_BTG_ENTRY_TTL=30m
CACHE_CRM_HOLDER_TTL=30m
```

<Note>
  In Helm deployments, the default `REDIS_HOST` points to the built-in Valkey sidecar (`<release-name>-valkey:6379`) — no additional Redis setup is needed unless you connect to an external instance.
</Note>

### Connection (always used)

| Var                 | Type                    | Default                              | Description                                                                                                                                                      |
| ------------------- | ----------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REDIS_HOST`        | string (host:port, CSV) | `<release>-valkey:6379` (Helm chart) | Redis address(es). Default points to the built-in Valkey (`<release-name>-valkey:6379`). Multiple addresses separated by comma define Sentinel/Cluster topology. |
| `REDIS_MASTER_NAME` | string                  | `""`                                 | Sentinel master name. Empty = standalone (direct connection).                                                                                                    |
| `REDIS_DB`          | int                     | `0`                                  | Redis logical database number.                                                                                                                                   |
| `REDIS_PROTOCOL`    | int                     | `3`                                  | RESP protocol version (2 or 3).                                                                                                                                  |

### Connection pool and retries (always used)

| Var                       | Type               | Default | Description                                                                               |
| ------------------------- | ------------------ | ------- | ----------------------------------------------------------------------------------------- |
| `REDIS_POOL_SIZE`         | int                | `10`    | Maximum connections in the pool.                                                          |
| `REDIS_MIN_IDLE_CONNS`    | int                | `0`     | Minimum idle connections kept ready.                                                      |
| `REDIS_READ_TIMEOUT`      | int (seconds)      | `3`     | Read operation timeout.                                                                   |
| `REDIS_WRITE_TIMEOUT`     | int (seconds)      | `3`     | Write operation timeout.                                                                  |
| `REDIS_DIAL_TIMEOUT`      | int (seconds)      | `5`     | Timeout to establish the initial connection.                                              |
| `REDIS_POOL_TIMEOUT`      | int (seconds)      | `2`     | Timeout waiting for a free connection from the pool.                                      |
| `REDIS_MAX_RETRIES`       | int                | `3`     | Maximum retries for a failed command.                                                     |
| `REDIS_MIN_RETRY_BACKOFF` | int (milliseconds) | `8`     | Minimum delay between retries.                                                            |
| `REDIS_MAX_RETRY_BACKOFF` | int (seconds)      | `512`   | Maximum delay between retries. Note: stored in seconds in code (different unit from min). |

### Authentication (optional — only used if set)

| Var              | Type            | Default | Description                                         |
| ---------------- | --------------- | ------- | --------------------------------------------------- |
| `REDIS_PASSWORD` | string (secret) | `""`    | Redis password. Empty = no password authentication. |

### TLS (optional — only used if `REDIS_TLS=true`)

| Var             | Type                | Default | Description                                                                 |
| --------------- | ------------------- | ------- | --------------------------------------------------------------------------- |
| `REDIS_TLS`     | bool                | `false` | Enables TLS. Required `true` in `DEPLOYMENT_MODE=saas` (validated at boot). |
| `REDIS_CA_CERT` | string (PEM base64) | `""`    | CA certificate (base64) to validate the server when TLS is active.          |

### GCP IAM authentication (optional — only used if `REDIS_USE_GCP_IAM=true`)

| Var                              | Type          | Default | Description                                                                          |
| -------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------------ |
| `REDIS_USE_GCP_IAM`              | bool          | `false` | Enables GCP IAM authentication (Memorystore) instead of password.                    |
| `REDIS_SERVICE_ACCOUNT`          | string        | `""`    | GCP service account that generates the access token.                                 |
| `GOOGLE_APPLICATION_CREDENTIALS` | string        | `""`    | GCP credentials path (read via CredentialsBase64FromEnvValue) to generate the token. |
| `REDIS_TOKEN_LIFETIME`           | int (minutes) | `60`    | Lifetime of the generated IAM token.                                                 |
| `REDIS_TOKEN_REFRESH_DURATION`   | int (minutes) | `45`    | Token refresh interval (must be less than lifetime).                                 |

### VSync cache TTLs (always used)

| Var                    | Type        | Default | Description                                                                 |
| ---------------------- | ----------- | ------- | --------------------------------------------------------------------------- |
| `CACHE_BTG_ENTRY_TTL`  | Go duration | `30m`   | Cache TTL for BTG/DICT entries in Redis. Negative value reverts to default. |
| `CACHE_CRM_HOLDER_TTL` | Go duration | `30m`   | Cache TTL for CRM holders in Redis. Negative value reverts to default.      |

# 8. Internal webhook security

***

The plugin uses an internal communication channel between the Worker and Application services. **HMAC-SHA256 signatures** secure this channel to prevent tampering and replay attacks.

```bash theme={null}
# Shared secret for signing internal requests (Worker -> Application)
# Must be at least 32 characters
# Generate one with: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validate signatures on incoming internal webhooks (true/false)
# Always use 'true' in production
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Maximum age (in seconds) for request timestamps before rejection
# Default: 300 (5 minutes)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300
```

<Warning>
  Use the exact same `INTERNAL_WEBHOOK_SECRET` value in both the Application and Worker services. A mismatch causes the plugin to reject all internal webhooks.
</Warning>

# 9. Worker layers

***

The plugin operates with three worker layers, each handling a different part of the Pix lifecycle. All workers run as separate services alongside the main application.

## Inbound worker

***

The inbound worker receives webhook notifications from BTG and forwards them to your application for processing.

```bash theme={null}
# URL where the application receives internal webhooks
WEBHOOK_INBOUND_BASE_URL=

# Shared secret for signing requests (must match the application's INTERNAL_WEBHOOK_SECRET)
INTERNAL_WEBHOOK_SECRET=
```

## Outbound worker

***

The outbound worker sends event notifications from the plugin to your application via webhooks. This is how your system stays informed about Pix events (transfers, refunds, claims, disputes).

### URL resolution priority

The plugin resolves webhook URLs in this order, using the first match:

1. **Entity URL** — A URL specific to the event type (e.g., `WEBHOOK_DICT_CLAIM_URL`)
2. **Flow URL** — A URL for the broader category (e.g., `WEBHOOK_DICT_URL`)
3. **Default URL** — The fallback URL (`WEBHOOK_DEFAULT_URL`)

```bash theme={null}
# Default fallback URL
WEBHOOK_DEFAULT_URL=

# DICT-related events
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# MED 2.0 Funds Recovery events (DICT flow)
# These route under the DICT flow and fall back to WEBHOOK_DICT_URL,
# then WEBHOOK_DEFAULT_URL, if no entity-specific URL is set.
WEBHOOK_DICT_FUNDS_RECOVERY_URL=
WEBHOOK_DICT_FUNDS_RECOVERY_EVENT_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=
```

<Tip>
  You can start with just `WEBHOOK_DEFAULT_URL` to receive all events at a single endpoint, then gradually split into entity-specific URLs as your system evolves.
</Tip>

For a deep dive into webhook event types, payloads, retry behavior, and best practices, see the [Webhooks guide](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks).

## Reconciliation worker

***

The reconciliation worker needs the same credentials as the Application layer for these services:

* **CRM** — URL and credentials
* **BTG** — URL and credentials
* **Midaz** — Organization ID

See the corresponding sections above for details on each configuration.

You can restrict when the worker operates by configuring a specific time window. This is especially useful for scheduling reconciliation tasks during off-peak hours. The plugin supports time windows that span midnight.

```bash theme={null}
# Start time in HH:MM format (24-hour). Example: "23:00" for 11 PM
RECONCILIATION_START_TIME=

# End time in HH:MM format (24-hour). Example: "05:00" for 5 AM
RECONCILIATION_END_TIME=
```

<Note>
  If you leave both fields empty, the worker runs without time restrictions — 24/7.
</Note>

<Warning>
  The reconciliation operational window is anchored to the **`America/Sao_Paulo`** timezone. On minimal/distroless container images that ship without timezone data, the runtime falls back to UTC and the configured window can drift by up to 3 hours relative to the DICT write-block. Set `TZ=America/Sao_Paulo` (and ensure tzdata is available) in the reconciliation worker container to keep the window aligned with BACEN.
</Warning>

<Note>
  Indirect Pix cashout and refund endpoints support idempotency through the `X-Idempotency` request header, with configurable TTL via `X-TTL`. For retry strategies and implementation details, see [Retries and idempotency](/en/reference/retries-idempotency).
</Note>

# 10. Observability (OpenTelemetry)

***

The plugin ships with full **OpenTelemetry** instrumentation (traces, metrics, and logs) across the Application and Worker layers. Every Pix flow is traced end to end — **transfers** (cash-in and cash-out), **refunds**, inbound and outbound **webhooks**, DICT **reconciliation**, and **intra-PSP** settlement — so you can follow a single payment across the plugin, Midaz, CRM, and BTG calls.

Telemetry is disabled by default. Enable it and point the OTLP exporter at your collector:

```bash theme={null}
# Master switch — telemetry is off until this is true
ENABLE_TELEMETRY=true

# Resource attributes that identify this service in your backend
OTEL_RESOURCE_SERVICE_NAME=plugin-br-pix-indirect-btg
OTEL_LIBRARY_NAME=github.com/LerianStudio/plugin-br-pix-indirect-btg
OTEL_RESOURCE_SERVICE_VERSION=${VERSION}
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=${ENV_NAME}

# OTLP collector endpoint (gRPC, default port 4317)
OTEL_EXPORTER_OTLP_ENDPOINT_PORT=4317
OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:${OTEL_EXPORTER_OTLP_ENDPOINT_PORT}
```

<Note>
  When `ENABLE_TELEMETRY=true`, `OTEL_EXPORTER_OTLP_ENDPOINT` is required. Set the same OTel variables on the Application and on each Worker so traces correlate across services.
</Note>

## Exporter: gRPC and TLS

***

The plugin exports traces, metrics, and logs over **OTLP/gRPC**. The endpoint scheme controls transport security:

| Endpoint value                      | Transport       | Security                            |
| ----------------------------------- | --------------- | ----------------------------------- |
| `https://collector:4317`            | gRPC over TLS   | Secure (recommended for production) |
| `http://collector:4317`             | gRPC, plaintext | Insecure — inferred automatically   |
| `collector:4317` (bare `host:port`) | gRPC, plaintext | Insecure — inferred automatically   |

<Warning>
  Insecure (plaintext) exporters are rejected outside development environments. In staging or production, use an `https://` endpoint, or explicitly acknowledge the risk via the lib-commons insecure-OTEL allowance only when you fully control the network path to the collector.
</Warning>

## Example: collector endpoint

***

Point the plugin at any OTLP-compatible collector (the OpenTelemetry Collector, Grafana LGTM/Alloy, etc.) listening on the gRPC port:

```bash theme={null}
# Local / development (plaintext gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Production (TLS gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317
```

The collector then fans telemetry out to your tracing, metrics, and logging backends.

# 11. Health and readiness

***

The Application and Workers expose a readiness probe at **`/readyz`** (alongside the standard liveness checks). Point your orchestrator's readiness probe at this endpoint so traffic is only routed once the service and its dependencies are ready.

# Transfer purpose (MED 2.0)

***

The cashout endpoint accepts an optional `X-Purpose` header that identifies the transaction purpose, used for MED 2.0 refund transfers. When omitted, it defaults to `TRANSFER`.

```bash theme={null}
# Example: a MED 2.0 refund transfer
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND
```

Supported values are `TRANSFER` and `INSTANT_PAYMENT_REFUND`. See [MED 2.0 — Funds Recovery](/en/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) for details.

# Next steps

***

With the plugin fully configured, you're ready to start operating Pix. Explore these topics to go deeper:

* [Webhooks](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Event types, payloads, retries, and best practices
* [MED 2.0 — Funds Recovery](/en/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) — Cross-account fraud recovery and the X-Purpose header
* [Refund operations](/en/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Distributed partial refunds and unblocking
* [Intra-PSP transfers](/en/midaz/plugins/pix/indirect/indirect-pix-intra-psp) — Internal P2P settlement and TRCK002 reporting
* [Main domains: DICT](/en/midaz/plugins/pix/main-domains-dict) — Understanding Pix key management
* [Main domains: transactions](/en/midaz/plugins/pix/main-domains-transactions) — Transaction flows and lifecycle
* [Main domains: QR Codes](/en/midaz/plugins/pix/main-domains-qrcodes) — Static and dynamic QR code generation
* [API reference](/en/reference/midaz/plugins/indirect-pix/create-entry) — Full API documentation for DICT, Claims, Transactions, QR Codes, and MED operations