Recipes / Use Cases

End-to-end scenarios that chain the API into real workflows. Each recipe uses synthetic data — substitute your own values.

Recipe 1 — Onboard a new financial institution

The canonical first-run flow, from authentication through to a usable, terminal-enabled FI.

Client                         Onboarding API
  │  POST /onboarding/login/user      │
  │ ────────────────────────────────▶ │   returns JWT in data
  │                                    │
  │  POST /onboarding/financialInstitution
  │ ────────────────────────────────▶ │   FI created (id: 84)
  │                                    │
  │  POST /onboarding/core-connectivity/data
  │ ────────────────────────────────▶ │   core wired
  │                                    │
  │  POST /onboarding/account-types    │
  │ ────────────────────────────────▶ │   account types defined
  │                                    │
  │  POST /onboarding/transaction-capabilities
  │ ────────────────────────────────▶ │   capabilities set
  │                                    │
  │  POST /terminal-key                │
  │ ────────────────────────────────▶ │   terminal registered
  │                                    │
  │  POST /onboarding/roles            │
  │  POST /onboarding/users            │
  │ ────────────────────────────────▶ │   admin user invited

Step-by-step

1. Authenticate. POST /v1/onboarding/login/user → capture data as your token.
2. Create the FI.

   POST /v1/onboarding/financialInstitution
   { "financialInstitutionId": "000100", "bin": "123456", "name": "Example Bank",
     "coreName": "summit-2023", "apiType": "REST", "apiUrl": "https://core.example.com/api/v1",
     "isEnabled": true, "transactionType": "BALANCEINQUIRY,ACCOUNTLOOKUP" }

3. Wire core connectivity. POST /v1/onboarding/core-connectivity/data with host/port/paths and credentials.
4. Define account types. POST /v1/onboarding/account-types (array).
5. Set capabilities. POST /v1/onboarding/transaction-capabilities mapping transaction types to account-type ids.
6. Register a terminal. POST /v1/terminal-key.
7. Create a role & an admin user. POST /v1/onboarding/roles then POST /v1/onboarding/users.
8. Verify. GET /v1/onboarding/financial-institutions/transaction-types/{id} and a transaction query.

Recipe 2 — Invite and activate an admin user

1. Create the user with a role: POST /v1/onboarding/users.
2. User receives an invite and verifies it: POST /v1/onboarding/verify-invite-url (encrypted email).
3. User sets a password: PATCH /v1/onboarding/users/password (encrypted fields).
4. If MFA is enabled: POST /v1/onboarding/login/mfa/status → display QR → POST /v1/onboarding/login/mfa/register.
5. User logs in: POST /v1/onboarding/login/user.

Recipe 3 — Configure transaction capabilities for an FI

1. List account types to obtain their ids: POST /v1/onboarding/account-types/list.
2. Create capabilities mapping transaction types to those ids:

   POST /v1/onboarding/transaction-capabilities
   [ { "financialInstitutionId": 65, "toAccountType": { "CASHWITHDRAWAL": [32, 34] }, "fromAccountType": null } ]

3. Verify: GET /v1/onboarding/transaction-capabilities/65.
4. Adjust a single mapping: PATCH /v1/onboarding/transaction-capability.

Recipe 4 — Daily operations: query & export transactions

1. Pull a date range: POST /v1/onboarding/transactions?fromDate=…&toDate=…&page=1&size=200.
2. Export for reporting: POST /v1/onboarding/transaction/export with selectedColumns.
3. Refresh the dashboard: POST /v1/onboarding/bizops-dashboard/statistics.
4. Check platform health: POST /v1/onboarding/healthstatus with { "fetchAllMicroServiceHealth": true }.