# Payment method icons

Bundled SVGs referenced by the payment catalog (`payment_methods.icon` slug
in the backend). The customer app's `PaymentIcon` widget resolves
`<slug>.svg` from this directory and falls back to `placeholder.svg` when the
file isn't bundled — see `client_app/lib/features/payment/widgets/payment_icon.dart`.

## Naming convention

One SVG per slug, lower-case, hyphens not underscores. Currently bundled
slugs (match the migrate.js seed):

| Slug | Method | Source filename in `idn-finlogos/icons/` |
|---|---|---|
| `qris` | QRIS | `qris.svg` |
| `ovo` | OVO | `ovo-new.svg` |
| `dana` | DANA | `dana.svg` |
| `shopeepay` | ShopeePay | `shopee-pay.svg` |
| `gopay` | GoPay (seeded inactive) | `gopay.svg` |
| `bca` | BCA Virtual Account | `bca.svg` |
| `mandiri` | Mandiri Virtual Account | `mandiri.svg` |
| `bni` | BNI Virtual Account | `bni.svg` |
| `bri` | BRI Virtual Account | `bri.svg` |
| `permata` | Permata Virtual Account | `permata.svg` |

## Sourcing — idn-finlogos

We pull individual SVGs from
[github.com/hafidznoor/idn-finlogos](https://github.com/hafidznoor/idn-finlogos)
rather than installing the Flutter package (`idn_finlogos` on pub.dev). The
package bundles all 572 SVGs as Flutter assets — Flutter doesn't tree-shake
assets, so adding the package ships ~4-6 MB of marks we never use. Manual
copy keeps the APK lean: 10 marks ≈ 80 KB on-disk.

See `NOTICE_IDN_FINLOGOS.txt` for the upstream licensing terms (MIT for build
tooling, CC BY-NC 4.0 for the SVG assets, plus the project's note that
individual brand marks require permission from each brand holder for
commercial use).

## Adding a new method

1. **Catalog row** (control center → Payment Catalog):
   - Add a method with `payment_code` set to the Xendit channel code
     (uppercase, e.g. `LINKAJA`) and `icon` set to the desired slug
     (lowercase, e.g. `linkaja`).
   - Method renders immediately with the generic placeholder icon.
2. **Branded SVG** (one-time, requires an app release):
   ```sh
   cd client_app/assets/payment_icons
   curl -sS https://raw.githubusercontent.com/hafidznoor/idn-finlogos/main/icons/<source>.svg -o <slug>.svg
   ```
   (Browse the repo's `icons/` directory if the source filename isn't an
   exact match — e.g. `ovo-new.svg` for the modern OVO mark.)
3. **Append the slug** to `_kBundledSlugs` in
   `client_app/lib/features/payment/widgets/payment_icon.dart` so the widget
   stops falling back to the placeholder for that slug.
4. **Cut a release.** Assets ship with the APK; new icons need a binary update.

## Why the explicit `_kBundledSlugs` list?

Flutter's asset system throws if a referenced asset is missing — there's no
"file exists?" check at runtime without round-tripping the AssetManifest.
Keeping the bundled-slugs list in code makes "what we ship" explicit and
keeps the icon widget cheap.

## When to migrate to the pub package

The manual-copy approach beats `idn_finlogos` as long as we bundle fewer
than ~50 icons (where the ~4-6 MB whole-library payload starts looking
reasonable compared to per-file curl-and-commit overhead). If we cross that
threshold, switch:

```yaml
dependencies:
  idn_finlogos: ^2.3.0
```

…and delete this directory's per-icon SVGs (keep `placeholder.svg` + the
slug allowlist).