> ## 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.5.0

<Badge color="green">Released</Badge> <Badge color="purple">2026-07-22</Badge>

### Changed

* **New `payment_reason` values (breaking for generated clients).** The
  regulatory `payment_reason` taxonomy used on `POST /v0/settlement-requests`
  has been streamlined to a shorter, clearer set of categories:

  `CHARITABLE_CONTRIBUTIONS`, `CONSULTING_FEES`, `EDUCATION_FEES`,
  `EMPLOYEE_SALARIES_OR_WAGES`, `FAMILY_SUPPORT`, `GIFTS`, `INSURANCE`,
  `INTERCOMPANY_TRANSFER`, `INVESTMENTS`, `LOANS`, `PERSONAL_TRANSFERS`,
  `PURCHASE_OF_GOODS`, `PURCHASE_OF_SERVICES`, `REAL_ESTATE`, `RENT`,
  `TAXES`, `TRAVEL`, `UTILITY_BILLS`.

  Your requests are **not** affected - the previous values still work (see
  Deprecated below). What changes today is the published schema: the OpenAPI
  enum now lists only the values above. If you generate types or clients from
  our spec, regenerating will shrink the `payment_reason` enum and may fail
  compilation wherever your code references a removed constant. Map those call
  sites using the table below.

  The most common fintech values map as: `PERSONAL_TRANSFERS` (cross-border
  consumer transfers), `FAMILY_SUPPORT` (remittances to family),
  `PURCHASE_OF_GOODS` / `PURCHASE_OF_SERVICES` (merchant payments),
  `EMPLOYEE_SALARIES_OR_WAGES` (payroll).

### Deprecated

* **Previous `payment_reason` values.** The older categories (for example
  `REMITTANCES`, `PAYMENT_FOR_GOODS_AND_SERVICES`, `REPAYMENT_OF_LOANS`,
  `OTHER`) are deprecated. They are **still accepted** and are translated
  automatically to the closest new value, so existing integrations keep
  working without any code change. They are no longer advertised in the API
  reference.

  These values are scheduled for removal on **2026-10-31**. After that date,
  sending a deprecated value will return `400`. Migrate before then. Common
  replacements:

  | Deprecated value                                        | Send instead                                 |
  | ------------------------------------------------------- | -------------------------------------------- |
  | `REMITTANCES`                                           | `PERSONAL_TRANSFERS` (or `FAMILY_SUPPORT`)   |
  | `PAYMENT_FOR_GOODS_AND_SERVICES`                        | `PURCHASE_OF_GOODS` / `PURCHASE_OF_SERVICES` |
  | `REPAYMENT_OF_LOANS`, `LOAN_ADVANCES`                   | `LOANS`                                      |
  | `CORPORATE_TAX_PAYMENTS`, `INCOME_TAX_PAYMENTS`         | `TAXES`                                      |
  | `MORTGAGE_PAYMENTS`, `REAL_ESTATE_PURCHASES`            | `REAL_ESTATE`                                |
  | `DOWN_PAYMENTS_FOR_REAL_ESTATE`                         | `REAL_ESTATE`                                |
  | `INSURANCE_PREMIUM_PAYMENTS`, `INSURANCE_CLAIM_PAYOUTS` | `INSURANCE`                                  |
  | `CAPITAL_CONTRIBUTIONS`                                 | `INVESTMENTS`                                |
  | `ROYALTIES`                                             | `PURCHASE_OF_SERVICES`                       |
  | `OTHER`                                                 | the closest specific value                   |

### Notes

* No immediate action required: requests using the old values continue to
  succeed until the removal date above.
* Because a deprecated value is translated on the way through, the reason
  **stored and returned** on the settlement request is the new one, not the
  deprecated value you sent. If you reconcile on `payment_reason`, expect the
  translated value in API responses and webhook payloads. Sending the new
  values directly avoids the mismatch.
* Reasons are used for regulatory categorisation and reporting only. They are
  never visible to the recipient.