# Aurora Gateway – Simulated Card Payouts

Aurora is a dev/test-only card payout gateway with the same gRPC contract as `mntx`, but it never sends real funds.

## Runtime entry points
- gRPC: `MntxGatewayService.CreateCardPayout`, `CreateCardTokenPayout`, `CreateCardToken`, `GetCardPayoutStatus`, `ListGatewayInstances`
- Callback HTTP server (optional): `:8084/aurora/callback`
- Metrics: Prometheus on `:9405/metrics`

## Behavior
- Card payouts are resolved locally by PAN scenario mapping.
- Token payouts resolve the scenario from the tokenized PAN (or fallback to masked PAN last4).
- No outbound payout/tokenization HTTP calls are made.

## Built-in test cards
- Every scenario has multiple generated PANs (8 per case), all Luhn-valid.
- PANs are generated from scenario prefixes in [`scenario_simulator.go`](./internal/service/gateway/scenario_simulator.go) via `generatePANSeriesWithLuhn`.
- Scenario prefixes:
  - `22000011`: approved instantly (`success`, code `00`)
  - `22000022`: pending issuer review (`waiting`, code `P01`)
  - `22000033`: insufficient funds (`failed`, code `51`)
  - `22000044`: issuer unavailable retryable (`failed`, code `10101`)
  - `22000055`: stolen card (`failed`, code `43`)
  - `22000066`: do not honor (`failed`, code `05`)
  - `22000077`: expired card (`failed`, code `54`)
  - `22000088`: provider timeout transport error
  - `22000098`: provider unreachable transport error
  - `22000097`: provider maintenance (`failed`, code `91`)
  - `22000096`: provider system malfunction (`failed`, code `96`)
- Any other valid PAN defaults to queued processing (`waiting`, code `P00`).

### Auxiliary PAN Table (Generated, Luhn-valid)

| Scenario | Prefix | PANs |
|---|---|---|
| approved_instant | `22000011` | `2200001100000001`<br>`2200001100000019`<br>`2200001100000027`<br>`2200001100000035`<br>`2200001100000043`<br>`2200001100000050`<br>`2200001100000068`<br>`2200001100000076` |
| pending_issuer_review | `22000022` | `2200002200000008`<br>`2200002200000016`<br>`2200002200000024`<br>`2200002200000032`<br>`2200002200000040`<br>`2200002200000057`<br>`2200002200000065`<br>`2200002200000073` |
| insufficient_funds | `22000033` | `2200003300000005`<br>`2200003300000013`<br>`2200003300000021`<br>`2200003300000039`<br>`2200003300000047`<br>`2200003300000054`<br>`2200003300000062`<br>`2200003300000070` |
| issuer_unavailable_retryable | `22000044` | `2200004400000002`<br>`2200004400000010`<br>`2200004400000028`<br>`2200004400000036`<br>`2200004400000044`<br>`2200004400000051`<br>`2200004400000069`<br>`2200004400000077` |
| stolen_card | `22000055` | `2200005500000008`<br>`2200005500000016`<br>`2200005500000024`<br>`2200005500000032`<br>`2200005500000040`<br>`2200005500000057`<br>`2200005500000065`<br>`2200005500000073` |
| do_not_honor | `22000066` | `2200006600000005`<br>`2200006600000013`<br>`2200006600000021`<br>`2200006600000039`<br>`2200006600000047`<br>`2200006600000054`<br>`2200006600000062`<br>`2200006600000070` |
| expired_card | `22000077` | `2200007700000002`<br>`2200007700000010`<br>`2200007700000028`<br>`2200007700000036`<br>`2200007700000044`<br>`2200007700000051`<br>`2200007700000069`<br>`2200007700000077` |
| provider_timeout_transport | `22000088` | `2200008800000009`<br>`2200008800000017`<br>`2200008800000025`<br>`2200008800000033`<br>`2200008800000041`<br>`2200008800000058`<br>`2200008800000066`<br>`2200008800000074` |
| provider_unreachable_transport | `22000098` | `2200009800000007`<br>`2200009800000015`<br>`2200009800000023`<br>`2200009800000031`<br>`2200009800000049`<br>`2200009800000056`<br>`2200009800000064`<br>`2200009800000072` |
| provider_maintenance | `22000097` | `2200009700000008`<br>`2200009700000016`<br>`2200009700000024`<br>`2200009700000032`<br>`2200009700000040`<br>`2200009700000057`<br>`2200009700000065`<br>`2200009700000073` |
| provider_system_malfunction | `22000096` | `2200009600000009`<br>`2200009600000017`<br>`2200009600000025`<br>`2200009600000033`<br>`2200009600000041`<br>`2200009600000058`<br>`2200009600000066`<br>`2200009600000074` |
| default_processing (example) | `22000999` | `2200099900000007` |

## Notes
- PAN is masked in logs.
- Provider settings should be configured under `aurora:` (legacy `mcards:` key is still accepted for backward compatibility).
- `gateway.id` defaults to `mcards` to preserve orchestrator compatibility.