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

# 0.2.0

<Badge color="green">Live</Badge> <Badge color="purple">04/27/2026</Badge>

<Note>
  Settlement request correlation: `external_id` and `metadata` are now first-class on the create
  payload, the list filter, and every read / webhook echo. Existing `transaction_id` clients keep
  working unchanged.
</Note>

### Added

* **`external_id`** — string identifier you supply on
  `POST /v0/settlement-requests`. Echoed on every read and webhook;
  filterable via `GET /v0/settlement-requests?external_id=...`.
  Recommended pattern: don't persist Superbank's `id`, look up by your
  `external_id` whenever you need the settlement.
* **`metadata`** — free-form key/value object (up to 50 string keys, 40-char
  keys, 500-char values). Echoed on every read and webhook; not filterable.
  Useful for carrying correlation (`user_id`, `card_charge_id`, etc.) without
  needing an extra lookup on your side when handling webhooks.
* **`destination.is_third_party`** is now included in every settlement
  response (previously accepted on create but not echoed back).

### Changed

* **`amount` formatting** is now consistent across `POST`, `GET`, and `PUT`
  responses. All three return the canonical 8-decimal form (e.g.
  `"1.00000000"`). Previously the `POST` response echoed the raw input
  (`"1"`) while reads returned the padded form.

### Fixed

* **`settlement_request.updated` webhooks** triggered by upstream payment
  status changes (e.g. SETTLEMENT\_COMPLETED, payout failures) now carry
  `external_id` and `metadata`, matching the `settlement_request.created`
  payload. Previously these two fields were stripped from the production
  webhook path even though the API documentation stated they were echoed
  on every webhook. No action needed if you already handle missing
  fields gracefully; if you wired logic around their presence, they will
  now be present consistently.

### Deprecated

* **`transaction_id`** — superseded by `external_id`. Both are accepted on
  `POST` / `PUT` and both are echoed in responses today; they map to the
  same underlying value. New integrations should use `external_id`.
  **Removal: 2026-05-25** (4 weeks from this release). After that date,
  requests sending `transaction_id` will be rejected and responses will
  no longer echo it. Migrate by replacing every occurrence of
  `transaction_id` with `external_id` — the values are interchangeable
  today.

### Notes

* `external_id` is **not enforced as unique** on Superbank's side. If you
  send the same value twice, the list endpoint returns every match. Use
  `metadata` (e.g. `metadata.card_charge_id`) for client-side
  disambiguation if needed.