{ "openapi": "3.1.0", "info": { "title": "GroundIT — Fintech", "version": "0.1.0", "license": { "name": "Proprietary — GroundIT/Sysmedac internal" }, "description": "**Phase-2 / Later — no operation in this file ships at the India + KSA launch** (features 12 §5; fsd 12 header; db 13 header). GroundIT's workforce-fintech layer: Earned-Wage Access delivered through dhanavega's `PayrollPort` — GroundIT is the payroll/attendance signal source and the at-source deduction executor, never the lender (ADR 0014); the worker's own-money wallet with an append-only ledger (FIN-F02); the KSA→India remittance corridor over the interpay rail (FIN-F03, ADR 0013/0019); and the financial dashboard/eligibility projection that surfaces own-money balances and EWA headroom with a deep link to PayDay+ for borrowed money, never re-homing it (FIN-F04, ADR 0018 money-surface split). This file specs only the product-app-facing `fintech.*` surface — the PayrollPort and interpay wire contracts themselves are deferred to `openapi/ports/`. See ../../00-api-overview-and-conventions.md. **G-14② decided (2026-07-02)**: the ADR 0018 deep-link stands — annotated on the four FIN-S08 EWA operations below.\n" }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerJWT": [] } ], "tags": [ { "name": "fintech", "description": "Workforce-fintech layer — EWA/PayrollPort, worker wallet, India–KSA remittance corridor, financial eligibility. All Phase-2." }, { "name": "ewa_enrolment", "description": "FIN-F01 — EWA enrolment/employer-link, driven by inbound PayrollPort events." }, { "name": "accrued_salary_feed", "description": "FIN-F01 — the append-only earned-wage signal series (the dynamic EWA limit)." }, { "name": "payroll_port_event", "description": "FIN-F01 — the immutable inbound PayrollPort event log (idempotent on provider event id)." }, { "name": "salary_deduction", "description": "FIN-F01 — the at-source SALARY_ADVANCE_REPAYMENT deduction executor/reconciliation." }, { "name": "wallet", "description": "FIN-F02 — the worker own-money wallet." }, { "name": "wallet_transaction", "description": "FIN-F02 — the append-only, partitioned wallet ledger." }, { "name": "remittance_beneficiary", "description": "FIN-F03 — saved, penny-drop-verified India beneficiaries." }, { "name": "fx_rate", "description": "FIN-F03 — short-lived SAR→INR rate quote tokens." }, { "name": "remittance", "description": "FIN-F03 — a worker's KSA→India remittance order." }, { "name": "corridor_transfer", "description": "FIN-F03 — the interpay-rail execution leg(s) beneath a remittance order." }, { "name": "routing_instruction", "description": "FIN-F03 — standing payroll-triggered routing (WPS-delay gated)." }, { "name": "financial_eligibility", "description": "FIN-F04 — the worker's financial dashboard/eligibility projection." } ], "x-reuse-anchors": { "parameters": { "path_id": { "$ref": "#/components/parameters/PathId" }, "page_size": { "$ref": "#/components/parameters/PageSize" }, "page_after": { "$ref": "#/components/parameters/PageAfter" }, "page_before": { "$ref": "#/components/parameters/PageBefore" }, "idempotency_key": { "$ref": "#/components/parameters/IdempotencyKey" }, "if_match": { "$ref": "#/components/parameters/IfMatch" } }, "responses": { "unauthorized": { "$ref": "#/components/responses/Unauthorized" }, "forbidden": { "$ref": "#/components/responses/Forbidden" }, "not_found": { "$ref": "#/components/responses/NotFound" }, "conflict": { "$ref": "#/components/responses/Conflict" }, "unprocessable": { "$ref": "#/components/responses/UnprocessableEntity" }, "locked": { "$ref": "#/components/responses/Locked" }, "too_many": { "$ref": "#/components/responses/TooManyRequests" }, "precondition_required": { "$ref": "#/components/responses/PreconditionRequired" }, "precondition_failed": { "$ref": "#/components/responses/PreconditionFailed" } }, "headers": { "etag": { "$ref": "#/components/headers/ETag" }, "location": { "$ref": "#/components/headers/Location" }, "idem_replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "paths": { "/fintech-overview": { "get": { "operationId": "fintech.overview.get", "summary": "Workforce-fintech overview (Finance/HR home)", "description": "Role-aware aggregate: EWA outstanding, active enrolments, wallet float, remittance MTD, eligibility coverage, and a needs-attention panel across the tenant's fintech layer. Read-only projection, no write table of its own (FIN-S01, fsd 12 §2.1). Phase-2.\n", "tags": [ "fintech" ], "x-token": "fintech.overview.get", "x-realizes-features": [ "FIN-F04", "FIN-F01", "FIN-F02", "FIN-F03" ], "x-screens": [ "FIN-S01" ], "x-touches-entities": [ "fintech.financial_eligibility", "fintech.wallets", "fintech.ewa_enrolments", "fintech.accrued_salary_feed", "fintech.salary_deductions", "fintech.corridor_transfers", "org.legal_entities" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "legal_entity_id", "in": "query", "required": false, "description": "Legal-entity/market selector; omitted = tenant-wide roll-up.", "schema": { "$ref": "#/components/schemas/UuidRef" } } ], "responses": { "200": { "description": "The overview projection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FintechOverview" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ewa-enrolments/admin": { "get": { "operationId": "fintech.ewa_enrolment.list_admin", "summary": "List EWA enrolments (Finance/HR console)", "description": "Employer-link state, KYC identity-match, agreement, and caps across every enrolment (FIN-S02, db 13 §1 ewa_enrolments). Phase-2, KSA-first.", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.list_admin", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S02" ], "x-touches-entities": [ "fintech.ewa_enrolments", "people.employees", "org.legal_entities" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text match on worker name/enrolment_no/provider_borrower_ref.", "schema": { "type": "string" } }, { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "link_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `enrolled_at`, `-enrolled_at`, `link_status`. Default `-enrolled_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of EWA enrolments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolmentPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ewa-enrolments/admin/{id}": { "get": { "operationId": "fintech.ewa_enrolment.get_admin", "summary": "Get one EWA enrolment (Finance/HR detail drawer)", "description": "Agreement, caps, KYC and link state, plus a link to the worker's latest signal/deductions (FIN-S02 detail drawer, db 13 §1). Phase-2.", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.get_admin", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S02" ], "x-touches-entities": [ "fintech.ewa_enrolments", "people.employees", "org.legal_entities" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The EWA enrolment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ewa-enrolments/admin/{id}/sync": { "post": { "operationId": "fintech.ewa_enrolment.sync", "summary": "Re-pull employer-link/enrolment state from PayrollPort", "description": "Jobs-tier `PayrollPort` pull (XC-F08) that lands `EMPLOYER_LINK_STATUS`/`ENROLLMENT_SYNC` events into `payroll_port_events` and idempotently advances `link_status`/`kyc_match_status` — GroundIT projects these, it does not author them (FIN-S02 **Sync**, db 13 §1). Async. Phase-2.\n", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.sync", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S02" ], "x-touches-entities": [ "fintech.ewa_enrolments", "fintech.payroll_port_events" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "fintech.ewa_enrolment.sync_requested", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Sync enqueued; poll `GET` or subscribe to `fintech.ewa_enrolment.link_status_changed`.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ewa-enrolments/admin/{id}/caps": { "patch": { "operationId": "fintech.ewa_enrolment.update_caps", "summary": "Adjust the employer-configured EWA advance cap", "description": "Edits `employer_max_advance_pct`/`employer_limit_amount` — the binding draw cap is `MIN(employer_limit_amount, provider_credit_limit_amount)` applied over the earned-wage signal (FIN-S02 cap edit; maker/checker via the approvals inbox, XC-F12; audited, XC-F06; db 13 §1 check constraints). Sync. Phase-2.\n", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.update_caps", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S02" ], "x-touches-entities": [ "fintech.ewa_enrolments" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "fintech.ewa_enrolment.caps_updated", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaCapUpdate" } } } }, "responses": { "200": { "description": "Caps updated.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accrued-salary-feed/admin": { "get": { "operationId": "fintech.accrued_salary_feed.list_admin", "summary": "List the earned-wage signal feed (Signal feed tab)", "description": "The append-only `accrued_salary.feed` series — computed-at, headroom, and push status per enrolment (FIN-S04 Signal feed tab, db 13 §1 accrued_salary_feed). Phase-2, KSA-first.", "tags": [ "fintech", "accrued_salary_feed" ], "x-token": "fintech.accrued_salary_feed.list_admin", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S04" ], "x-touches-entities": [ "fintech.accrued_salary_feed", "fintech.ewa_enrolments" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "ewa_enrolment_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "feed_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/FeedStatus" } }, { "name": "as_of_date[from]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "as_of_date[to]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `computed_at`, `-computed_at`, `as_of_date`. Default `-computed_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of signal-feed rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccruedSalaryFeedPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accrued-salary-feed/admin/{id}": { "get": { "operationId": "fintech.accrued_salary_feed.get_admin", "summary": "Get one earned-wage signal row", "description": "A single immutable `accrued_salary_feed` computation, incl. the cap/eligibility breakdown (FIN-S04, db 13 §1). Phase-2.", "tags": [ "fintech", "accrued_salary_feed" ], "x-token": "fintech.accrued_salary_feed.get_admin", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S04" ], "x-touches-entities": [ "fintech.accrued_salary_feed" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The signal-feed row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccruedSalaryFeed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accrued-salary-feed/admin/{id}/retry-push": { "post": { "operationId": "fintech.accrued_salary_feed.retry_push", "summary": "Retry a failed signal push to the provider", "description": "Re-queues a `FAILED` `accrued_salary.feed` push on the jobs tier (XC-F08) — no row mutation, the append-only signal row is never edited (FIN-S04 **Retry failed**, db 00 §8). Async. Phase-2.\n", "tags": [ "fintech", "accrued_salary_feed" ], "x-token": "fintech.accrued_salary_feed.retry_push", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S04" ], "x-touches-entities": [ "fintech.accrued_salary_feed" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "fintech.accrued_salary_feed.push_retry_requested", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Retry enqueued.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccruedSalaryFeed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-port-events": { "get": { "operationId": "fintech.payroll_port_event.list", "summary": "List inbound PayrollPort events (Events tab)", "description": "The immutable inbound event log, idempotent on `provider_event_id` (FIN-S04 Events tab, db 13 §1 payroll_port_events). Phase-2.", "tags": [ "fintech", "payroll_port_event" ], "x-token": "fintech.payroll_port_event.list", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S04" ], "x-touches-entities": [ "fintech.payroll_port_events", "fintech.ewa_enrolments", "people.employees" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "event_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PayrollPortEventType" } }, { "name": "process_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PayrollPortProcessStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `received_at`, `-received_at`. Default `-received_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of PayrollPort events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollPortEventPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-port-events/{id}": { "get": { "operationId": "fintech.payroll_port_event.get", "summary": "Get one PayrollPort event (raw payload)", "description": "The verified raw event body, kept for audit — evidence, never queried/joined (FIN-S04 event modal, db 13 §1). Phase-2.", "tags": [ "fintech", "payroll_port_event" ], "x-token": "fintech.payroll_port_event.get", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S04" ], "x-touches-entities": [ "fintech.payroll_port_events" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The PayrollPort event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollPortEvent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payroll-port-events/{id}/retry": { "post": { "operationId": "fintech.payroll_port_event.retry", "summary": "Retry a failed PayrollPort event handler", "description": "Re-queues a `FAILED` event handler on the jobs tier (XC-F08) — no row mutation; unverified events (`signature_valid = false`) are never applied (FIN-S04 **Retry failed**, db 00 §8). Async. Phase-2.\n", "tags": [ "fintech", "payroll_port_event" ], "x-token": "fintech.payroll_port_event.retry", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S04" ], "x-touches-entities": [ "fintech.payroll_port_events" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "fintech.payroll_port_event.retry_requested", "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Retry enqueued.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayrollPortEvent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/salary-deductions/admin": { "get": { "operationId": "fintech.salary_deduction.list_admin", "summary": "List at-source EWA deductions (reconciliation console)", "description": "Scheduled vs recovered `SALARY_ADVANCE_REPAYMENT` lines, post-tax/WPS-SIF flags (FIN-S03, db 13 §1 salary_deductions). Phase-2, KSA-first.", "tags": [ "fintech", "salary_deduction" ], "x-token": "fintech.salary_deduction.list_admin", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S03" ], "x-touches-entities": [ "fintech.salary_deductions", "pay.payroll_runs", "pay.deductions", "people.employees" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text match on worker name/deduction_no/provider_advance_ref.", "schema": { "type": "string" } }, { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SalaryDeductionStatus" } }, { "name": "recovery_period[from]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "name": "recovery_period[to]", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DateOnlyRef" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `recovery_period`, `-recovery_period`, `status`. Default `-recovery_period`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of salary deductions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryDeductionPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/salary-deductions/admin/{id}": { "get": { "operationId": "fintech.salary_deduction.get_admin", "summary": "Get one salary deduction (reconciliation detail)", "description": "The linked payroll run + posted line, shortfall residual, and confirm-back stamp (FIN-S03 detail drawer, db 13 §1). Phase-2.", "tags": [ "fintech", "salary_deduction" ], "x-token": "fintech.salary_deduction.get_admin", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S03" ], "x-touches-entities": [ "fintech.salary_deductions", "pay.payroll_runs", "pay.deductions" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The salary deduction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryDeduction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/salary-deductions/admin/{id}/confirm": { "post": { "operationId": "fintech.salary_deduction.confirm", "summary": "Confirm a recovered deduction back to the provider", "description": "Emits the `deduction.confirm` `PayrollPort` event (XC-F08), `status → CONFIRMED` + `confirmed_at`, logged in `payroll_port_events`; maker/checker via the approvals inbox (XC-F12), audited (XC-F06) (FIN-S03 **Confirm to provider**, db 13 §1). Async. Phase-2.\n", "tags": [ "fintech", "salary_deduction" ], "x-token": "fintech.salary_deduction.confirm", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S03" ], "x-touches-entities": [ "fintech.salary_deductions", "fintech.payroll_port_events" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "fintech.salary_deduction.confirmed", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNoteInput" } } } }, "responses": { "202": { "description": "Confirmation enqueued; poll `GET` or subscribe to `fintech.salary_deduction.confirmed`.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryDeduction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/salary-deductions/admin/{id}/cancel": { "post": { "operationId": "fintech.salary_deduction.cancel", "summary": "Cancel a pre-post scheduled deduction", "description": "Withdraws a `SCHEDULED` row before posting (e.g. de-link / F&F) — `status → CANCELLED` (FIN-S03 **Cancel**, db 13 §1). Sync. Phase-2.", "tags": [ "fintech", "salary_deduction" ], "x-token": "fintech.salary_deduction.cancel", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S03" ], "x-touches-entities": [ "fintech.salary_deductions" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "fintech.salary_deduction.cancelled", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNoteInput" } } } }, "responses": { "200": { "description": "Deduction cancelled.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryDeduction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/admin": { "get": { "operationId": "fintech.wallet.list_admin", "summary": "List worker wallets (reconciliation console)", "description": "Balance/available/held per wallet with a reconciled-vs-ledger badge (FIN-S05, db 13 §2 wallets). Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.list_admin", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S05" ], "x-touches-entities": [ "fintech.wallets", "people.employees" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text match on worker name/wallet_no.", "schema": { "type": "string" } }, { "name": "currency_code", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CurrencyCodeRef" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WalletStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `opened_at`, `-opened_at`, `balance_amount`, `-balance_amount`. Default `-opened_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of wallets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/admin/{id}": { "get": { "operationId": "fintech.wallet.get_admin", "summary": "Get one wallet (Finance reconciliation detail)", "description": "Balance/available/held with the `balance ↔ Σ(signed ledger)` reconciliation line (FIN-S05 detail drawer, db 13 §2). Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.get_admin", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S05" ], "x-touches-entities": [ "fintech.wallets" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The wallet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/admin/{id}/freeze": { "post": { "operationId": "fintech.wallet.freeze", "summary": "Freeze a wallet (no debits)", "description": "`status → FROZEN` + `frozen_reason` (risk/KYC/dispute); no debits while frozen; maker/checker (XC-F12), audited (XC-F06) (FIN-S05 **Freeze**, db 13 §2 check constraints). Sync. Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.freeze", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S05" ], "x-touches-entities": [ "fintech.wallets" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "fintech.wallet.frozen", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFreezeInput" } } } }, "responses": { "200": { "description": "Wallet frozen.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/admin/{id}/unfreeze": { "post": { "operationId": "fintech.wallet.unfreeze", "summary": "Unfreeze a wallet", "description": "`status → ACTIVE`; maker/checker (XC-F12), audited (XC-F06) (FIN-S05 **Unfreeze**, db 13 §2). Sync. Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.unfreeze", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S05" ], "x-touches-entities": [ "fintech.wallets" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "fintech.wallet.unfrozen", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNoteInput" } } } }, "responses": { "200": { "description": "Wallet unfrozen.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/admin/{id}/close": { "post": { "operationId": "fintech.wallet.close", "summary": "Close a wallet (zero balance required)", "description": "`status → CLOSED` + `closed_at`; requires zero balance — a residual must be swept as a ledger debit first; maker/checker (XC-F12), audited (XC-F06) (FIN-S05 **Close**, db 13 §2 Lifecycle). Sync. Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.close", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S05" ], "x-touches-entities": [ "fintech.wallets" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "fintech.wallet.closed", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionNoteInput" } } } }, "responses": { "200": { "description": "Wallet closed.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/admin/{id}/transactions": { "get": { "operationId": "fintech.wallet_transaction.list_admin", "summary": "List a wallet's ledger (Finance drill)", "description": "The append-only, partitioned ledger behind the wallet header (FIN-S05 ledger drill, db 13 §2 wallet_transactions). Phase-2.", "tags": [ "fintech", "wallet_transaction" ], "x-token": "fintech.wallet_transaction.list_admin", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S05" ], "x-touches-entities": [ "fintech.wallet_transactions", "fintech.wallets" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "txn_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WalletTxnType" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `created_at`, `-created_at`. Default `-created_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of ledger rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittances/admin": { "get": { "operationId": "fintech.remittance.list_admin", "summary": "List remittance orders (corridor console — Orders tab)", "description": "KSA→India remittance orders with masked beneficiary, purpose, amounts and status (FIN-S06 Orders tab, db 13 §3 remittances). Phase-2.", "tags": [ "fintech", "remittance" ], "x-token": "fintech.remittance.list_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.remittances", "fintech.remittance_beneficiaries", "people.employees" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Free-text match on worker name/remittance_no.", "schema": { "type": "string" } }, { "name": "legal_entity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UuidRef" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RemittanceStatus" } }, { "name": "purpose", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RemittancePurpose" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `initiated_at`, `-initiated_at`, `status`. Default `-initiated_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of remittance orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittancePage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittances/admin/{id}": { "get": { "operationId": "fintech.remittance.get_admin", "summary": "Get one remittance order (Finance detail drawer)", "description": "The order header; the transfer legs and consumed FX token are read via the nested `transfers` list (FIN-S06 detail drawer, db 13 §3). Phase-2.", "tags": [ "fintech", "remittance" ], "x-token": "fintech.remittance.get_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.remittances" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The remittance order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Remittance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittances/admin/{id}/transfers": { "get": { "operationId": "fintech.corridor_transfer.list_admin", "summary": "List the execution legs of a remittance order (Finance)", "description": "Applied rate, UTR, provider ref, status/failure reason per interpay-rail leg (FIN-S06 legs drawer, db 13 §3 corridor_transfers). Phase-2.", "tags": [ "fintech", "corridor_transfer" ], "x-token": "fintech.corridor_transfer.list_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.corridor_transfers", "fintech.fx_rates", "fintech.remittances" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of transfer legs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorridorTransferPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittance-beneficiaries/admin": { "get": { "operationId": "fintech.remittance_beneficiary.list_admin", "summary": "List remittance beneficiaries (Finance/compliance — Beneficiaries tab)", "description": "Masked destination accounts + penny-drop verification status (FIN-S06 Beneficiaries tab, db 13 §3 remittance_beneficiaries). PII masked (db 00 §14). Phase-2.", "tags": [ "fintech", "remittance_beneficiary" ], "x-token": "fintech.remittance_beneficiary.list_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.remittance_beneficiaries", "people.employees" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "verify_status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BeneficiaryVerifyStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of beneficiaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiaryPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittance-beneficiaries/admin/{id}": { "get": { "operationId": "fintech.remittance_beneficiary.get_admin", "summary": "Get one remittance beneficiary (Finance/compliance, masked)", "description": "Masked account detail + penny-drop reference (FIN-S06, db 13 §3). PII masked (db 00 §14). Phase-2.", "tags": [ "fintech", "remittance_beneficiary" ], "x-token": "fintech.remittance_beneficiary.get_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.remittance_beneficiaries" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The beneficiary (masked).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fx-rates/admin": { "get": { "operationId": "fintech.fx_rate.list_admin", "summary": "List FX rate tokens (FX tokens audit tab)", "description": "The `SAR→INR` quote-token audit trail — rate, status, TTL (FIN-S06 FX tokens tab, db 13 §3 fx_rates). Phase-2.", "tags": [ "fintech", "fx_rate" ], "x-token": "fintech.fx_rate.list_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.fx_rates" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/FxRateStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `quoted_at`, `-quoted_at`. Default `-quoted_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of FX rate tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRatePage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/routing-instructions/admin": { "get": { "operationId": "fintech.routing_instruction.list_admin", "summary": "List standing routing instructions (Routing tab)", "description": "Payroll-triggered standing orders — amount type, WPS-delay, next-run, status (FIN-S06 Routing tab, db 13 §3 routing_instructions). Phase-2.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.list_admin", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S06" ], "x-touches-entities": [ "fintech.routing_instructions", "fintech.remittance_beneficiaries", "people.employees" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RoutingInstructionStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of routing instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstructionPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ewa-enrolments": { "get": { "operationId": "fintech.ewa_enrolment.list", "summary": "List my EWA enrolment(s)", "description": "The worker's own EWA enrolment/link status across providers (own-scope, FIN-S08, db 13 §1). Sync. Phase-2. **G-14② decided — deep-link stands (ADR 0018)** — read-only; the draw is deep-linked to PayDay+, never authored here.", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.list", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S08" ], "x-touches-entities": [ "fintech.ewa_enrolments" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of my EWA enrolments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolmentPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "fintech.ewa_enrolment.enrol", "summary": "Enrol in Earned-Wage Access", "description": "The wizard's finalize step — KYC identity-match kicks off via the inbound `enrollment.sync` `PayrollPort` event (idempotent, `payroll_port_events`), and the worker accepts the current `ujrah`/fee agreement; GroundIT projects the resulting `link_status`/`kyc_match_status`, it does not decide them (FIN-S08 **enrol**, db 13 §1). Async. Phase-2. **G-14② decided — deep-link stands (ADR 0018)** — this creates the enrolment/link only; the draw itself is deep-linked to PayDay+, never authored here (ADR 0018).\n", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.enrol", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S08" ], "x-touches-entities": [ "fintech.ewa_enrolments", "fintech.payroll_port_events" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "fintech.ewa_enrolment.enrolment_requested", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolmentCreate" } } } }, "responses": { "202": { "description": "Enrolment requested; `link_status` starts `PENDING` and advances via inbound PayrollPort events.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/ewa-enrolments/{id}": { "get": { "operationId": "fintech.ewa_enrolment.get", "summary": "Get my EWA enrolment (status header)", "description": "Link/KYC status chips + agreement for the status header (FIN-S08, db 13 §1). Sync. Phase-2. **G-14② decided — deep-link stands (ADR 0018).**", "tags": [ "fintech", "ewa_enrolment" ], "x-token": "fintech.ewa_enrolment.get", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S08" ], "x-touches-entities": [ "fintech.ewa_enrolments" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "My EWA enrolment.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EwaEnrolment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accrued-salary-feed/latest": { "get": { "operationId": "fintech.accrued_salary_feed.get_latest", "summary": "Get my latest earned-wage headroom", "description": "The latest `accrued_salary_feed` row for my active enrolment — the dynamic EWA limit shown on the headroom card, surfaced not re-underwritten (FIN-S08/FIN-S07 headroom, db 13 §1). Sync. Phase-2. **G-14② decided — deep-link stands (ADR 0018)** — read-only headroom; **Get advance** deep-links to PayDay+ (dhanavega = system of record for the draw).\n", "tags": [ "fintech", "accrued_salary_feed" ], "x-token": "fintech.accrued_salary_feed.get_latest", "x-realizes-features": [ "FIN-F01" ], "x-screens": [ "FIN-S08", "FIN-S07" ], "x-touches-entities": [ "fintech.accrued_salary_feed", "fintech.ewa_enrolments" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "responses": { "200": { "description": "My latest earned-wage signal row.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccruedSalaryFeed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/financial-eligibility/me": { "get": { "operationId": "fintech.financial_eligibility.get", "summary": "Get my financial dashboard (money home)", "description": "Own-money wallet balance, earned-wage headroom, remittance MTD, and product-eligibility flags incl. the `payday_plus.deep_link` for borrowed money — never shown as GroundIT's own money (FIN-S07, db 13 §4 financial_eligibility, ADR 0018). Eventually-consistent projection. Sync. Phase-2.\n", "tags": [ "fintech", "financial_eligibility" ], "x-token": "fintech.financial_eligibility.get", "x-realizes-features": [ "FIN-F04", "FIN-F01", "FIN-F02", "FIN-F03" ], "x-screens": [ "FIN-S07" ], "x-touches-entities": [ "fintech.financial_eligibility" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "responses": { "200": { "description": "My financial dashboard projection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialEligibility" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets": { "get": { "operationId": "fintech.wallet.list", "summary": "List my wallet(s)", "description": "The worker's own-money wallet(s) — one per currency (FIN-S09 balance header, db 13 §2 wallets). Sync. Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.list", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S09" ], "x-touches-entities": [ "fintech.wallets" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of my wallets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/{id}": { "get": { "operationId": "fintech.wallet.get", "summary": "Get my wallet", "description": "Balance/available/held for the balance header (FIN-S09, FIN-S07 wallet card, db 13 §2). Sync. Phase-2.", "tags": [ "fintech", "wallet" ], "x-token": "fintech.wallet.get", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S09", "FIN-S07" ], "x-touches-entities": [ "fintech.wallets" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "My wallet.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/wallets/{id}/transactions": { "get": { "operationId": "fintech.wallet_transaction.list", "summary": "List my wallet ledger (transaction history)", "description": "Append-only ledger rows — icon by `txn_type`, signed amount by `direction`, running balance-after (FIN-S09 ledger list, db 13 §2 wallet_transactions). Read-only. Sync. Phase-2.", "tags": [ "fintech", "wallet_transaction" ], "x-token": "fintech.wallet_transaction.list", "x-realizes-features": [ "FIN-F02" ], "x-screens": [ "FIN-S09" ], "x-touches-entities": [ "fintech.wallet_transactions", "fintech.wallets" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": true, "x-entitlement": "fintech.ewa", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "txn_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WalletTxnType" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `created_at`, `-created_at`. Default `-created_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of my ledger rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittance-beneficiaries": { "get": { "operationId": "fintech.remittance_beneficiary.list", "summary": "List my saved beneficiaries", "description": "Own India beneficiaries for the send-money picker (FIN-S10/FIN-S11, db 13 §3 remittance_beneficiaries). Sync. Phase-2, KSA only.", "tags": [ "fintech", "remittance_beneficiary" ], "x-token": "fintech.remittance_beneficiary.list", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.remittance_beneficiaries" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of my beneficiaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiaryPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "fintech.remittance_beneficiary.create", "summary": "Add a remittance beneficiary", "description": "Adds an India bank/IFSC payee; kicks off partner **penny-drop** verification asynchronously — `verify_status` starts `PENDING` and gates any transfer/routing until `VERIFIED` (FIN-S11 **Add beneficiary**, db 13 §3). Sync create, async verification. Phase-2, KSA only.\n", "tags": [ "fintech", "remittance_beneficiary" ], "x-token": "fintech.remittance_beneficiary.create", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11", "FIN-S10" ], "x-touches-entities": [ "fintech.remittance_beneficiaries" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.remittance_beneficiary.added", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiaryCreate" } } } }, "responses": { "201": { "description": "Beneficiary added, `verify_status = PENDING`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittance-beneficiaries/{id}": { "get": { "operationId": "fintech.remittance_beneficiary.get", "summary": "Get one of my beneficiaries", "description": "Masked account detail + verification status (FIN-S11, db 13 §3). Sync. Phase-2, KSA only.", "tags": [ "fintech", "remittance_beneficiary" ], "x-token": "fintech.remittance_beneficiary.get", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.remittance_beneficiaries" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "My beneficiary (masked).", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittance-beneficiaries/{id}/retire": { "post": { "operationId": "fintech.remittance_beneficiary.retire", "summary": "Retire a beneficiary", "description": "`is_active → false` — soft, never hard-deleted, so historical transfers still resolve (FIN-S11 **retire**, db 13 §3 Lifecycle). Sync. Phase-2, KSA only.", "tags": [ "fintech", "remittance_beneficiary" ], "x-token": "fintech.remittance_beneficiary.retire", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.remittance_beneficiaries" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.remittance_beneficiary.retired", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Beneficiary retired.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceBeneficiary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fx-rates/quote": { "post": { "operationId": "fintech.fx_rate.quote", "summary": "Request a live SAR→INR rate quote", "description": "Issues a short-lived (≈5-minute) rate token that locks the quoted rate through confirmation — single-use, expires fast (FIN-S10 step 3 **review & lock**, db 13 §3 fx_rates). Sync. Phase-2, KSA only.\n", "tags": [ "fintech", "fx_rate" ], "x-token": "fintech.fx_rate.quote", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S10" ], "x-touches-entities": [ "fintech.fx_rates" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.fx_rate.quoted", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "A new, `ACTIVE` rate-quote token.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRate" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/fx-rates/{id}": { "get": { "operationId": "fintech.fx_rate.get", "summary": "Get a rate-quote token (countdown poll)", "description": "Poll the token's status/TTL while the worker reviews the locked quote (FIN-S10 step 3 countdown, db 13 §3). Sync. Phase-2, KSA only.", "tags": [ "fintech", "fx_rate" ], "x-token": "fintech.fx_rate.get", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S10" ], "x-touches-entities": [ "fintech.fx_rates" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "The rate-quote token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxRate" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittances": { "get": { "operationId": "fintech.remittance.list", "summary": "List my remittance orders (send history)", "description": "The worker's own send-money-home history (FIN-S10 track / FIN-S07 send-home card, db 13 §3 remittances). Sync. Phase-2, KSA only.", "tags": [ "fintech", "remittance" ], "x-token": "fintech.remittance.list", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S10", "FIN-S07" ], "x-touches-entities": [ "fintech.remittances" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RemittanceStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "sort", "in": "query", "required": false, "description": "Sort whitelist: `initiated_at`, `-initiated_at`. Default `-initiated_at`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of my remittance orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittancePage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "fintech.remittance.create", "summary": "Send money home (confirm a remittance)", "description": "Confirms the send: writes the order (`origin = MANUAL`, `purpose`, `source_amount`), debits the wallet (`wallet_transactions` `REMITTANCE_DEBIT`), and binds the consumed `fx_rates` token to a new `corridor_transfers` leg; execution over the interpay rail is async — the order advances `INITIATED → QUOTED → FUNDED → SUBMITTED → SETTLED` (FIN-S10 step 4 **confirm**, db 13 §3). The beneficiary must be `VERIFIED` at initiation (service gate). Async. Phase-2, KSA only.\n", "tags": [ "fintech", "remittance" ], "x-token": "fintech.remittance.create", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S10" ], "x-touches-entities": [ "fintech.remittances", "fintech.remittance_beneficiaries", "fintech.wallets", "fintech.wallet_transactions", "fintech.fx_rates", "fintech.corridor_transfers" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "async", "x-emits-event": "fintech.remittance.initiated", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceCreate" } } } }, "responses": { "202": { "description": "Remittance handed to the interpay rail; poll `GET` or subscribe to `fintech.remittance.settled`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Remittance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittances/{id}": { "get": { "operationId": "fintech.remittance.get", "summary": "Get one of my remittance orders", "description": "Order header + status for the tracking timeline (FIN-S10 step 5 **track**, db 13 §3). Sync. Phase-2, KSA only.", "tags": [ "fintech", "remittance" ], "x-token": "fintech.remittance.get", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S10" ], "x-touches-entities": [ "fintech.remittances" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "My remittance order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Remittance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/remittances/{id}/transfers": { "get": { "operationId": "fintech.corridor_transfer.list", "summary": "List my remittance's execution legs (tracking timeline)", "description": "UTR + leg status feeding the `status` timeline to `SETTLED` (FIN-S10 step 5 **track**, db 13 §3 corridor_transfers). Sync. Phase-2, KSA only.", "tags": [ "fintech", "corridor_transfer" ], "x-token": "fintech.corridor_transfer.list", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S10" ], "x-touches-entities": [ "fintech.corridor_transfers", "fintech.remittances" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of transfer legs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorridorTransferPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/routing-instructions": { "get": { "operationId": "fintech.routing_instruction.list", "summary": "List my standing routing instructions", "description": "My payroll-triggered auto-remit standing orders (FIN-S11 Routing list, db 13 §3 routing_instructions). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.list", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions", "fintech.remittance_beneficiaries" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RoutingInstructionStatus" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" } ], "responses": { "200": { "description": "Page of my routing instructions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstructionPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "fintech.routing_instruction.create", "summary": "Create a standing routing instruction", "description": "A fixed amount or `% of net` auto-remitted each cycle after the WPS-delay window; requires a `VERIFIED` beneficiary (FIN-S11 Routing editor **create**, db 13 §3 check constraints/service gate). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.create", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions", "fintech.remittance_beneficiaries" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.routing_instruction.created", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstructionCreate" } } } }, "responses": { "201": { "description": "Routing instruction created, `status = ACTIVE`.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstruction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/routing-instructions/{id}": { "get": { "operationId": "fintech.routing_instruction.get", "summary": "Get one of my routing instructions", "description": "Standing-rule detail for the Routing editor (FIN-S11, db 13 §3). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.get", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions" ], "x-idempotent": false, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "My routing instruction.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstruction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "fintech.routing_instruction.update", "summary": "Edit a standing routing instruction", "description": "Edits amount type/fixed amount/`% of net`/WPS-delay/per-cycle cap (FIN-S11 Routing editor, db 13 §3). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.update", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.routing_instruction.updated", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstructionUpdate" } } } }, "responses": { "200": { "description": "Routing instruction updated.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstruction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/routing-instructions/{id}/pause": { "post": { "operationId": "fintech.routing_instruction.pause", "summary": "Pause a routing instruction", "description": "`status → PAUSED` — the standing order stops firing until resumed (FIN-S11 **pause**, db 13 §3 Lifecycle). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.pause", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.routing_instruction.paused", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Routing instruction paused.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstruction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/routing-instructions/{id}/resume": { "post": { "operationId": "fintech.routing_instruction.resume", "summary": "Resume a paused routing instruction", "description": "`status → ACTIVE`; requires the beneficiary still `VERIFIED` (FIN-S11 **resume**, db 13 §3 service gate). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.resume", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions", "fintech.remittance_beneficiaries" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.routing_instruction.resumed", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Routing instruction resumed.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstruction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/routing-instructions/{id}/cancel": { "post": { "operationId": "fintech.routing_instruction.cancel", "summary": "Cancel a routing instruction", "description": "`status → CANCELLED` (terminal) — a cancelled instruction never blocks a new one for the same worker-beneficiary pair (FIN-S11 **cancel**, db 13 §3 Indexes/uniqueness). Sync. Phase-2, KSA only.", "tags": [ "fintech", "routing_instruction" ], "x-token": "fintech.routing_instruction.cancel", "x-realizes-features": [ "FIN-F03" ], "x-screens": [ "FIN-S11" ], "x-touches-entities": [ "fintech.routing_instructions" ], "x-idempotent": true, "x-market": "KSA", "x-sync-async": "sync", "x-emits-event": "fintech.routing_instruction.cancelled", "x-rls-scope": "self", "x-append-only": false, "x-entitlement": "fintech.remittance", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "If-Match", "in": "header", "required": true, "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Routing instruction cancelled.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingInstruction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Product session token. Two mint paths, one contract (ADR 0010): employees/managers authenticate against Keycloak (mobile + web); workspace staff arrive from the One portal via bridge-token SSO (`POST /api/sso/exchange` verifies the platform's Ed25519 token and mints the product session). The token carries IDENTITY ONLY — `sub`, `tenantUid`, `principal_class`, MFA level, session ref, `exp`. Roles/permissions are re-resolved server-side per request. Enforcement is layered: gateway (TLS/WAF/routing only — NEVER trusted for auth) → NestJS auth guard (validates token, builds the request auth-context) → entitlement middleware (subscription-status → feature-flag → numeric-limit, ADR 0009) → `SET LOCAL app.tenant_id` / `app.user_id` → Postgres FORCED RLS. `tenantUid` is NEVER a path, query, or body parameter.\n" } }, "schemas": { "UuidRef": { "$ref": "#/components/schemas/Uuid" }, "DateOnlyRef": { "$ref": "#/components/schemas/DateOnly" }, "TimestampRef": { "$ref": "#/components/schemas/Timestamp" }, "RateRef": { "$ref": "#/components/schemas/Rate" }, "MoneyRef": { "$ref": "#/components/schemas/Money" }, "CurrencyCodeRef": { "$ref": "#/components/schemas/CurrencyCode" }, "BusinessNoRef": { "$ref": "#/components/schemas/BusinessNo" }, "AuditMetaRef": { "$ref": "#/components/schemas/AuditMeta" }, "AppendOnlyMetaRef": { "$ref": "#/components/schemas/AppendOnlyMeta" }, "CursorPageRef": { "$ref": "#/components/schemas/CursorPage" }, "EwaProvider": { "type": "string", "enum": [ "DHANAVEGA" ], "description": "fintech.ewa_enrolments.provider — the EWA system-of-record partner (db 13 §1); extensible." }, "LinkStatus": { "type": "string", "enum": [ "PENDING", "ACTIVE", "SUSPENDED", "UNLINKED" ], "description": "fintech.ewa_enrolments.link_status (db 13 §1)." }, "KycMatchStatus": { "type": "string", "enum": [ "PENDING", "MATCHED", "MISMATCH", "EXPIRED" ], "description": "fintech.ewa_enrolments.kyc_match_status (db 13 §1)." }, "FeedStatus": { "type": "string", "enum": [ "COMPUTED", "PUSHED", "ACK", "FAILED" ], "description": "fintech.accrued_salary_feed.feed_status (db 13 §1)." }, "SalaryDeductionStatus": { "type": "string", "enum": [ "SCHEDULED", "POSTED", "RECOVERED", "PARTIALLY_RECOVERED", "CONFIRMED", "CANCELLED" ], "description": "fintech.salary_deductions.status (db 13 §1)." }, "PayrollPortEventType": { "type": "string", "enum": [ "EMPLOYER_LINK_STATUS", "ENROLLMENT_SYNC", "SALARY_POSTED", "DEDUCTION_CONFIRM" ], "description": "fintech.payroll_port_events.event_type (db 13 §1)." }, "PayrollPortProcessStatus": { "type": "string", "enum": [ "RECEIVED", "PROCESSED", "IGNORED", "FAILED" ], "description": "fintech.payroll_port_events.process_status (db 13 §1)." }, "WalletStatus": { "type": "string", "enum": [ "ACTIVE", "FROZEN", "CLOSED" ], "description": "fintech.wallets.status (db 13 §2)." }, "WalletTxnType": { "type": "string", "enum": [ "SALARY_CREDIT", "EWA_DRAW", "REMITTANCE_DEBIT", "REMITTANCE_REFUND", "HOLD", "HOLD_RELEASE", "FEE", "ADJUSTMENT", "REVERSAL" ], "description": "fintech.wallet_transactions.txn_type (db 13 §2)." }, "WalletTxnDirection": { "type": "string", "enum": [ "CREDIT", "DEBIT" ], "description": "fintech.wallet_transactions.direction (db 13 §2)." }, "WalletTxnSourceType": { "type": "string", "enum": [ "SALARY", "EWA", "REMITTANCE", "HOLD", "FEE", "ADJUSTMENT" ], "description": "fintech.wallet_transactions.source_type — polymorphic provenance (db 13 §2)." }, "BeneficiaryRelationship": { "type": "string", "enum": [ "SELF", "SPOUSE", "PARENT", "CHILD", "SIBLING", "OTHER" ], "description": "fintech.remittance_beneficiaries.relationship (db 13 §3)." }, "BeneficiaryVerifyStatus": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED" ], "description": "fintech.remittance_beneficiaries.verify_status — penny-drop outcome (db 13 §3)." }, "InterpayProvider": { "type": "string", "enum": [ "INTERPAY" ], "description": "fintech.fx_rates.provider / fintech.corridor_transfers.provider — the FX/settlement rail partner (db 13 §3)." }, "FxRateStatus": { "type": "string", "enum": [ "ACTIVE", "CONSUMED", "EXPIRED" ], "description": "fintech.fx_rates.status (db 13 §3)." }, "RemittanceOrigin": { "type": "string", "enum": [ "MANUAL", "ROUTING", "EWA_DISBURSE" ], "description": "fintech.remittances.origin (db 13 §3)." }, "RemittancePurpose": { "type": "string", "enum": [ "FAMILY_MAINTENANCE", "SAVINGS", "EDUCATION", "MEDICAL", "GIFT", "OTHER" ], "description": "fintech.remittance_purpose — declared purpose-of-remittance for AML/regulatory capture (db 13 §3, added this round per fsd 12 gap 3a)." }, "RemittanceStatus": { "type": "string", "enum": [ "INITIATED", "QUOTED", "FUNDED", "SUBMITTED", "SETTLED", "FAILED", "CANCELLED", "REFUNDED" ], "description": "fintech.remittances.status (db 13 §3)." }, "CorridorTransferStatus": { "type": "string", "enum": [ "PENDING", "SUBMITTED", "SETTLED", "FAILED", "RETURNED" ], "description": "fintech.corridor_transfers.status (db 13 §3)." }, "RoutingAmountType": { "type": "string", "enum": [ "FIXED", "PCT_OF_NET" ], "description": "fintech.routing_instructions.amount_type (db 13 §3)." }, "RoutingInstructionStatus": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "CANCELLED" ], "description": "fintech.routing_instructions.status (db 13 §3)." }, "ActionNoteInput": { "type": "object", "description": "Generic optional-note body shared by confirm/cancel/unfreeze/close actions in this file.", "additionalProperties": false, "properties": { "note": { "type": "string" } } }, "EwaEnrolment": { "description": "fintech.ewa_enrolments — the worker's link into dhanavega-side EWA; GroundIT holds the enrolment/link, not the advance (db 13 §1).", "allOf": [ { "type": "object", "required": [ "id", "enrolment_no", "employee_id", "legal_entity_id", "provider", "link_status", "kyc_match_status", "employer_max_advance_pct" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "enrolment_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "provider": { "$ref": "#/components/schemas/EwaProvider" }, "provider_borrower_ref": { "type": [ "string", "null" ] }, "link_status": { "$ref": "#/components/schemas/LinkStatus" }, "kyc_match_status": { "$ref": "#/components/schemas/KycMatchStatus" }, "agreement_accepted_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "agreement_version": { "type": [ "string", "null" ] }, "employer_max_advance_pct": { "$ref": "#/components/schemas/RateRef" }, "employer_limit_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "provider_credit_limit_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "min_tenure_months": { "type": "integer", "minimum": 0 }, "salary_floor_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "enrolled_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "suspended_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "unlinked_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "EwaEnrolmentCreate": { "type": "object", "description": "The enrolment wizard's finalize step — accepts the current `ujrah`/fee agreement; `agreement_version` is stamped server-side from the active terms.", "required": [ "legal_entity_id", "agreement_accept" ], "additionalProperties": false, "properties": { "legal_entity_id": { "$ref": "#/components/schemas/UuidRef" }, "agreement_accept": { "type": "boolean", "description": "Must be `true` to proceed." } } }, "EwaCapUpdate": { "type": "object", "description": "Employer-configured cap edit; at least one field required.", "minProperties": 1, "additionalProperties": false, "properties": { "employer_max_advance_pct": { "$ref": "#/components/schemas/RateRef" }, "employer_limit_amount": { "$ref": "#/components/schemas/MoneyRef" } } }, "EwaEnrolmentPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EwaEnrolment" } } } } ] }, "AccruedSalaryFeed": { "description": "fintech.accrued_salary_feed — one immutable row per earned-wage signal computation; the dynamic EWA limit pushed to dhanavega (db 13 §1). Append-only.", "allOf": [ { "type": "object", "required": [ "id", "ewa_enrolment_id", "employee_id", "as_of_date", "pay_period_start", "pay_period_end", "earned_wages_amount", "max_advance_pct", "outstanding_advance_amount", "eligible_amount", "feed_status", "computed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "ewa_enrolment_id": { "$ref": "#/components/schemas/UuidRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "as_of_date": { "$ref": "#/components/schemas/DateOnlyRef" }, "pay_period_start": { "$ref": "#/components/schemas/DateOnlyRef" }, "pay_period_end": { "$ref": "#/components/schemas/DateOnlyRef" }, "earned_wages_amount": { "$ref": "#/components/schemas/MoneyRef" }, "max_advance_pct": { "$ref": "#/components/schemas/RateRef" }, "outstanding_advance_amount": { "$ref": "#/components/schemas/MoneyRef" }, "employer_cap_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "provider_cap_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "eligible_amount": { "$ref": "#/components/schemas/MoneyRef" }, "feed_status": { "$ref": "#/components/schemas/FeedStatus" }, "pushed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "computed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AppendOnlyMetaRef" } ] }, "AccruedSalaryFeedPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccruedSalaryFeed" } } } } ] }, "PayrollPortEvent": { "description": "fintech.payroll_port_events — the immutable inbound PayrollPort event log, idempotent on provider_event_id (db 13 §1). Append-only.", "allOf": [ { "type": "object", "required": [ "id", "provider", "provider_event_id", "event_type", "payload", "signature_valid", "process_status", "received_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "provider": { "$ref": "#/components/schemas/EwaProvider" }, "provider_event_id": { "type": "string" }, "event_type": { "$ref": "#/components/schemas/PayrollPortEventType" }, "ewa_enrolment_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "employee_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "payload": { "type": "object", "additionalProperties": true, "description": "The raw verified provider event body, kept for audit (evidence — never queried/joined; shape varies by event_type, db 13 §1)." }, "signature_valid": { "type": "boolean" }, "process_status": { "$ref": "#/components/schemas/PayrollPortProcessStatus" }, "received_at": { "$ref": "#/components/schemas/TimestampRef" }, "processed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AppendOnlyMetaRef" } ] }, "PayrollPortEventPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayrollPortEvent" } } } } ] }, "SalaryDeduction": { "description": "fintech.salary_deductions — the at-source SALARY_ADVANCE_REPAYMENT recovery GroundIT schedules/executes (db 13 §1).", "allOf": [ { "type": "object", "required": [ "id", "deduction_no", "ewa_enrolment_id", "employee_id", "provider_advance_ref", "recovery_period", "scheduled_amount", "recovered_amount", "is_post_tax", "wps_sif_borne", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "deduction_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "ewa_enrolment_id": { "$ref": "#/components/schemas/UuidRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "provider_advance_ref": { "type": "string" }, "payroll_run_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "posted_deduction_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "recovery_period": { "$ref": "#/components/schemas/DateOnlyRef" }, "scheduled_amount": { "$ref": "#/components/schemas/MoneyRef" }, "recovered_amount": { "$ref": "#/components/schemas/MoneyRef" }, "is_post_tax": { "type": "boolean", "description": "Closed guard — always true; never reduces the India TDS base." }, "wps_sif_borne": { "type": "boolean", "description": "KSA — carried as a deduction line in the WPS SIF." }, "status": { "$ref": "#/components/schemas/SalaryDeductionStatus" }, "confirmed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "SalaryDeductionPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalaryDeduction" } } } } ] }, "Wallet": { "description": "fintech.wallets — a worker's own-money wallet, one per currency; balance is a maintained projection of the ledger (db 13 §2).", "allOf": [ { "type": "object", "required": [ "id", "wallet_no", "employee_id", "balance_amount", "available_amount", "held_amount", "status", "opened_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "wallet_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "balance_amount": { "$ref": "#/components/schemas/MoneyRef" }, "available_amount": { "$ref": "#/components/schemas/MoneyRef" }, "held_amount": { "$ref": "#/components/schemas/MoneyRef" }, "status": { "$ref": "#/components/schemas/WalletStatus" }, "frozen_reason": { "type": [ "string", "null" ] }, "opened_at": { "$ref": "#/components/schemas/TimestampRef" }, "closed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "WalletFreezeInput": { "type": "object", "required": [ "frozen_reason" ], "additionalProperties": false, "properties": { "frozen_reason": { "type": "string", "description": "Risk / KYC / dispute — required to freeze." } } }, "WalletPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } ] }, "WalletTransaction": { "description": "fintech.wallet_transactions — one immutable row per wallet money movement; the wallet balance is a sum over these rows (db 13 §2). Append-only, partitioned RANGE by created_at.", "allOf": [ { "type": "object", "required": [ "id", "wallet_id", "txn_no", "txn_type", "direction", "amount", "balance_after_amount", "source_type" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "wallet_id": { "$ref": "#/components/schemas/UuidRef" }, "txn_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "txn_type": { "$ref": "#/components/schemas/WalletTxnType" }, "direction": { "$ref": "#/components/schemas/WalletTxnDirection" }, "amount": { "$ref": "#/components/schemas/MoneyRef" }, "balance_after_amount": { "$ref": "#/components/schemas/MoneyRef" }, "source_type": { "$ref": "#/components/schemas/WalletTxnSourceType" }, "source_ref_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "reversal_of_txn_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] } } }, { "$ref": "#/components/schemas/AppendOnlyMetaRef" } ] }, "WalletTransactionPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTransaction" } } } } ] }, "RemittanceBeneficiary": { "description": "fintech.remittance_beneficiaries — a worker's saved, penny-drop-verified India destination account; PII masked on the wire (db 00 §14, db 13 §3).", "allOf": [ { "type": "object", "required": [ "id", "beneficiary_no", "employee_id", "beneficiary_name", "country_code", "currency_code", "verify_status", "is_active" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "beneficiary_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "nickname": { "type": [ "string", "null" ] }, "beneficiary_name": { "type": "string", "description": "Account-holder name (encrypted at rest; masked in list views)." }, "relationship": { "anyOf": [ { "$ref": "#/components/schemas/BeneficiaryRelationship" }, { "type": "null" } ] }, "country_code": { "type": "string", "description": "ISO-3166 alpha-2 — always `IN` for this corridor." }, "bank_account_no_masked": { "type": "string", "description": "Masked India account number (e.g. `••••1234`); the encrypted value never transits the API." }, "ifsc_code": { "type": "string", "description": "India IFSC routing code." }, "bank_name": { "type": [ "string", "null" ] }, "currency_code": { "$ref": "#/components/schemas/CurrencyCodeRef" }, "verify_status": { "$ref": "#/components/schemas/BeneficiaryVerifyStatus" }, "penny_drop_ref": { "type": [ "string", "null" ] }, "verified_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "is_active": { "type": "boolean" } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "RemittanceBeneficiaryCreate": { "type": "object", "required": [ "beneficiary_name", "bank_account_no", "ifsc_code" ], "additionalProperties": false, "properties": { "nickname": { "type": "string" }, "beneficiary_name": { "type": "string" }, "relationship": { "$ref": "#/components/schemas/BeneficiaryRelationship" }, "bank_account_no": { "type": "string", "writeOnly": true, "description": "Raw India account number; stored encrypted", "never echoed back.": null }, "ifsc_code": { "type": "string" } } }, "RemittanceBeneficiaryPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RemittanceBeneficiary" } } } } ] }, "FxRate": { "description": "fintech.fx_rates — a short-lived (~5-minute), single-use SAR→INR rate-quote token (db 13 §3).", "allOf": [ { "type": "object", "required": [ "id", "rate_token", "base_currency_code", "quote_currency_code", "rate", "provider", "quoted_at", "expires_at", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "rate_token": { "type": "string" }, "base_currency_code": { "$ref": "#/components/schemas/CurrencyCodeRef" }, "quote_currency_code": { "$ref": "#/components/schemas/CurrencyCodeRef" }, "rate": { "$ref": "#/components/schemas/RateRef" }, "provider": { "$ref": "#/components/schemas/InterpayProvider" }, "provider_quote_ref": { "type": [ "string", "null" ] }, "quoted_at": { "$ref": "#/components/schemas/TimestampRef" }, "expires_at": { "$ref": "#/components/schemas/TimestampRef" }, "status": { "$ref": "#/components/schemas/FxRateStatus" }, "consumed_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "FxRatePage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FxRate" } } } } ] }, "Remittance": { "description": "fintech.remittances — a worker's KSA→India remittance order; funded from the wallet or an EWA cross-border disburse (db 13 §3).", "allOf": [ { "type": "object", "required": [ "id", "remittance_no", "employee_id", "beneficiary_id", "origin", "purpose", "source_amount", "fee_amount", "status", "initiated_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "remittance_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "beneficiary_id": { "$ref": "#/components/schemas/UuidRef" }, "wallet_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "routing_instruction_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "origin": { "$ref": "#/components/schemas/RemittanceOrigin" }, "purpose": { "$ref": "#/components/schemas/RemittancePurpose" }, "source_amount": { "$ref": "#/components/schemas/MoneyRef" }, "dest_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "fee_amount": { "$ref": "#/components/schemas/MoneyRef" }, "status": { "$ref": "#/components/schemas/RemittanceStatus" }, "initiated_at": { "$ref": "#/components/schemas/TimestampRef" }, "settled_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "RemittanceCreate": { "type": "object", "required": [ "beneficiary_id", "purpose", "source_amount", "rate_token" ], "additionalProperties": false, "properties": { "beneficiary_id": { "$ref": "#/components/schemas/UuidRef" }, "purpose": { "$ref": "#/components/schemas/RemittancePurpose" }, "source_amount": { "$ref": "#/components/schemas/MoneyRef" }, "rate_token": { "type": "string", "description": "The ACTIVE", "unexpired fintech.fx_rates.rate_token to consume.": null } } }, "RemittancePage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Remittance" } } } } ] }, "CorridorTransfer": { "description": "fintech.corridor_transfers — a single interpay-rail execution leg beneath a remittance order (db 13 §3).", "allOf": [ { "type": "object", "required": [ "id", "remittance_id", "beneficiary_id", "fx_rate_id", "source_amount", "applied_rate", "dest_amount", "fee_amount", "provider", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "remittance_id": { "$ref": "#/components/schemas/UuidRef" }, "beneficiary_id": { "$ref": "#/components/schemas/UuidRef" }, "fx_rate_id": { "$ref": "#/components/schemas/UuidRef" }, "source_amount": { "$ref": "#/components/schemas/MoneyRef" }, "applied_rate": { "$ref": "#/components/schemas/RateRef" }, "dest_amount": { "$ref": "#/components/schemas/MoneyRef" }, "fee_amount": { "$ref": "#/components/schemas/MoneyRef" }, "provider": { "$ref": "#/components/schemas/InterpayProvider" }, "provider_transfer_ref": { "type": [ "string", "null" ] }, "utr_ref": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/CorridorTransferStatus" }, "submitted_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "failure_reason": { "type": [ "string", "null" ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "CorridorTransferPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CorridorTransfer" } } } } ] }, "RoutingInstruction": { "description": "fintech.routing_instructions — a standing payroll-triggered auto-remit rule, gated behind a WPS-delay window (db 13 §3).", "allOf": [ { "type": "object", "required": [ "id", "instruction_no", "employee_id", "beneficiary_id", "amount_type", "wps_delay_hours", "status" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "instruction_no": { "$ref": "#/components/schemas/BusinessNoRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "beneficiary_id": { "$ref": "#/components/schemas/UuidRef" }, "amount_type": { "$ref": "#/components/schemas/RoutingAmountType" }, "fixed_amount": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "net_pct": { "anyOf": [ { "$ref": "#/components/schemas/RateRef" }, { "type": "null" } ] }, "wps_delay_hours": { "type": "integer", "minimum": 0, "default": 48 }, "max_amount_per_cycle": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRef" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/RoutingInstructionStatus" }, "next_run_period": { "anyOf": [ { "$ref": "#/components/schemas/DateOnlyRef" }, { "type": "null" } ] }, "last_run_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "RoutingInstructionCreate": { "type": "object", "required": [ "beneficiary_id", "amount_type" ], "additionalProperties": false, "properties": { "beneficiary_id": { "$ref": "#/components/schemas/UuidRef" }, "amount_type": { "$ref": "#/components/schemas/RoutingAmountType" }, "fixed_amount": { "$ref": "#/components/schemas/MoneyRef" }, "net_pct": { "$ref": "#/components/schemas/RateRef" }, "wps_delay_hours": { "type": "integer", "minimum": 0, "default": 48 }, "max_amount_per_cycle": { "$ref": "#/components/schemas/MoneyRef" } } }, "RoutingInstructionUpdate": { "type": "object", "description": "Partial edit; at least one field required.", "minProperties": 1, "additionalProperties": false, "properties": { "amount_type": { "$ref": "#/components/schemas/RoutingAmountType" }, "fixed_amount": { "$ref": "#/components/schemas/MoneyRef" }, "net_pct": { "$ref": "#/components/schemas/RateRef" }, "wps_delay_hours": { "type": "integer", "minimum": 0 }, "max_amount_per_cycle": { "$ref": "#/components/schemas/MoneyRef" } } }, "RoutingInstructionPage": { "allOf": [ { "$ref": "#/components/schemas/CursorPageRef" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingInstruction" } } } } ] }, "FinancialEligibility": { "description": "fintech.financial_eligibility — the per-worker financial-dashboard projection, rebuilt from FIN-F01–F03 events; own-money surface only (ADR 0018) (db 13 §4).", "allOf": [ { "type": "object", "required": [ "id", "employee_id", "wallet_balance_amount", "earned_wage_headroom_amount", "outstanding_advance_amount", "remittance_mtd_amount", "ewa_eligible", "corridor_eligible", "eligibility_flags", "recomputed_at" ], "properties": { "id": { "$ref": "#/components/schemas/UuidRef" }, "employee_id": { "$ref": "#/components/schemas/UuidRef" }, "wallet_balance_amount": { "$ref": "#/components/schemas/MoneyRef" }, "earned_wage_headroom_amount": { "$ref": "#/components/schemas/MoneyRef" }, "outstanding_advance_amount": { "$ref": "#/components/schemas/MoneyRef" }, "remittance_mtd_amount": { "$ref": "#/components/schemas/MoneyRef" }, "ewa_eligible": { "type": "boolean" }, "corridor_eligible": { "type": "boolean", "description": "KSA only — the corridor is KSA→India by definition." }, "eligibility_flags": { "type": "object", "description": "Sparse per-product detail: `{ ewa: { enrolled, link_status, limit_amount }, corridor: { beneficiary_verified, routing_active }, payday_plus: { deep_link } }`. The `payday_plus.deep_link` points at the borrowed-money PayDay+ surface — never rendered as GroundIT's own money (ADR 0018). Never queried/joined.\n", "additionalProperties": true }, "last_signal_at": { "anyOf": [ { "$ref": "#/components/schemas/TimestampRef" }, { "type": "null" } ] }, "recomputed_at": { "$ref": "#/components/schemas/TimestampRef" } } }, { "$ref": "#/components/schemas/AuditMetaRef" } ] }, "FintechOverview": { "type": "object", "description": "FIN-S01 role-aware aggregate — read-only projection, no write table of its own.", "required": [ "ewa_outstanding_amount", "active_ewa_enrolments_count", "wallet_float_amount", "remittance_mtd_amount", "needs_attention" ], "properties": { "legal_entity_id": { "anyOf": [ { "$ref": "#/components/schemas/UuidRef" }, { "type": "null" } ] }, "ewa_outstanding_amount": { "$ref": "#/components/schemas/MoneyRef" }, "active_ewa_enrolments_count": { "type": "integer", "minimum": 0 }, "wallet_float_amount": { "$ref": "#/components/schemas/MoneyRef" }, "remittance_mtd_amount": { "$ref": "#/components/schemas/MoneyRef" }, "eligibility_coverage_pct": { "anyOf": [ { "$ref": "#/components/schemas/RateRef" }, { "type": "null" } ] }, "needs_attention": { "type": "array", "items": { "$ref": "#/components/schemas/FintechOverviewAlert" } } } }, "FintechOverviewAlert": { "type": "object", "description": "One needs-attention chip (failed feed push, unconfirmed deduction, failed/returned transfer, frozen wallet).", "required": [ "type", "count" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "FEED_PUSH_FAILED", "DEDUCTION_UNCONFIRMED", "TRANSFER_FAILED", "WALLET_FROZEN" ] }, "count": { "type": "integer", "minimum": 0 } } }, "Uuid": { "type": "string", "format": "uuid", "description": "UUIDv7 surrogate primary key (db-docs/00 §3). Never the business identifier." }, "DateOnly": { "type": "string", "format": "date", "description": "Calendar-only value (pay-period date, leave date, due date)." }, "Timestamp": { "type": "string", "format": "date-time", "description": "timestamptz, serialized UTC ISO-8601. Presentation timezone is a client concern." }, "Rate": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,6})?$", "description": "numeric(9,6) fraction as a string, e.g. \"0.120000\" for the 12% EPF rate. Never a float; percentages are stored as fractions." }, "Money": { "type": "object", "description": "Exact decimal money (db-docs/00 §6). `amount` is a STRING so float never enters the wire.", "required": [ "amount", "currency_code" ], "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "numeric(18,2) as a string, e.g. \"45000.00\"." }, "currency_code": { "$ref": "#/components/schemas/CurrencyCode" } } }, "CurrencyCode": { "type": "string", "enum": [ "INR", "SAR" ], "description": "ISO-4217. A legal entity operates in a single currency (db-docs/00 §6)." }, "BusinessNo": { "type": "string", "description": "Tenant-unique, prefixed human reference (`employee_no`, `requisition_no`, `offer_no`, `payslip_no`, `claim_no`, `ticket_no`, `asset_no`, `case_no`). Read-model field; never a path key.\n" }, "AuditMeta": { "type": "object", "description": "Standard mutable-entity columns (db-docs/00 §5). Read-only; present on every mutable read-model.", "readOnly": true, "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ], "description": "null = system/jobs" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "updated_by": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ], "description": "soft-delete marker; live rows are null. Deleted rows are excluded by default scope." }, "version": { "type": "integer", "description": "Optimistic-lock counter (where present); surfaces as the ETag." } } }, "AppendOnlyMeta": { "type": "object", "description": "Standard append-only/immutable columns (db-docs/00 §5/§8). No update/version/delete; corrections are new compensating rows.", "readOnly": true, "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/Uuid" }, { "type": "null" } ] } } }, "CursorPage": { "type": "object", "description": "Generic cursor-pagination envelope. List operations compose it via allOf to type `data`, e.g. `allOf: [ {$ref CursorPage}, { properties: { data: { items: {$ref Employee} } } } ]`.\n", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": {} }, "page": { "type": "object", "required": [ "has_more" ], "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "total_est": { "type": [ "integer", "null" ], "description": "Optional, capped, APPROXIMATE row estimate for grid \"X of Z\" display only — never an exact COUNT(*) on large tables (attend.attendance_records, xc.notifications, audit.*).\n" } } } } }, "Problem": { "type": "object", "description": "RFC 9457 problem detail (application/problem+json). The platform-wide error envelope (03 §1).", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "default": "about:blank", "description": "Problem-type URI." }, "title": { "type": "string", "description": "Short, human-readable summary (stable per type)." }, "status": { "type": "integer", "description": "HTTP status code, duplicated for convenience." }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "description": "URI reference for this specific occurrence." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "correlation_id": { "$ref": "#/components/schemas/Uuid" } } }, "ValidationProblem": { "description": "422 field-level validation failure; extends Problem with a per-field error array. `detail` is ALWAYS present on a 422 (#1251) and is the human summary of `errors[]`: one offending field renders as `\": \"` (`withholding_amount: is required for an India entity`), several as `\"N fields were refused: a, b, c.\"`, capped at five names. It is display copy derived from members already in the same body — clients keep branching on `code` and mapping `errors[].pointer` back to a control, never parsing this sentence.\n", "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "detail", "errors" ], "properties": { "detail": { "type": "string", "description": "Human summary of `errors[]`, always populated on a 422 so a client never has to fall back to generic copy for the one status that names a fixable field.\n", "example": "withholding_amount: is required for an India entity" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "pointer", "rule" ], "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the offending field, e.g. /claim_amount" }, "rule": { "type": "string", "enum": [ "required", "format", "length", "range", "cross-field", "async-server", "consent-gated", "uniqueness-business", "not_found" ], "description": "FSD validation taxonomy rule (fsd-docs/00 §8.2). `not_found` is the server-side-lookup arm: a body field that REFERENCES another resource (e.g. `project_id` on a work entry) and did not resolve for this caller. It is reported here, under the field's pointer, and NOT as a 404 — the request addresses its own resource, so the failure belongs on the form field the client can actually fix (#805).\n" }, "message": { "type": "string" } } } } } } ] }, "ErrorCode": { "type": "string", "description": "Machine-stable error code (paired with the HTTP status; drives client handling, not display copy).", "enum": [ "VALIDATION_FAILED", "IDEMPOTENCY_KEY_REUSE", "VERSION_CONFLICT", "PRECONDITION_REQUIRED", "MAKER_EQUALS_CHECKER", "STEP_UP_REQUIRED", "CONSENT_REQUIRED", "TOKEN_DENIED", "SCOPE_DENIED", "OWNERSHIP_DENIED", "STATE_TRANSITION_INVALID", "FACE_MISMATCH", "FACE_VERIFICATION_REQUIRED", "WITHHOLDING_REVIEW_REQUIRED", "FEATURE_NOT_IN_PLAN", "PLAN_LIMIT_EXCEEDED", "TENANT_PAST_DUE", "TENANT_SUSPENDED", "TENANT_CANCELLED", "RATE_LIMITED", "NOT_FOUND" ] } }, "parameters": { "PathId": { "name": "id", "in": "path", "required": true, "description": "UUIDv7 surrogate key of the target resource. Business numbers (`employee_no`, `claim_no`, …) are read-model fields, never path keys.", "schema": { "$ref": "#/components/schemas/Uuid" } }, "PageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page. Cursor pagination only (03 §2); offset pagination is rejected (ADR 0015).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "PageAfter": { "name": "page[after]", "in": "query", "required": false, "description": "Opaque forward keyset cursor (from a prior page's `page.next_cursor`).", "schema": { "type": "string" } }, "PageBefore": { "name": "page[before]", "in": "query", "required": false, "description": "Opaque backward keyset cursor (from a prior page's `page.prev_cursor`).", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key. REQUIRED on every mutation (this round tightens ADR 0015's \"platform + retryable mutations\" floor to ALL mutations for uniformity — offline punch/leave sync depends on it). Scoped (tenant, principal, route, key); a replay within the ~24h window returns the stored response with `Idempotency-Replayed: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSE (04 §1).\n", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Optimistic-concurrency precondition for mutating a VERSIONED mutable entity (db-docs/00 §5 applies `version` where concurrent edits are likely). Value is the entity's current ETag (the row `version`). Absent → 428; stale → 412 (04 §2). N/A for append-only entities and for unversioned low-contention entities (their update ops simply omit this parameter).\n", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing, expired, or invalid session token (no authenticated principal).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Authenticated but denied — permission token not granted, out of scope (self/team/branch), not the owner, tenant suspended, or an MC-2 operation without a fresh step-up challenge. `code` ∈ TOKEN_DENIED | SCOPE_DENIED | OWNERSHIP_DENIED | MAKER_EQUALS_CHECKER | STEP_UP_REQUIRED | CONSENT_REQUIRED | TENANT_SUSPENDED. A plan feature-flag being off is 402 FEATURE_NOT_IN_PLAN, not 403 (see PaymentRequired).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Resource does not exist OR is masked by RLS (tenant/self/team/branch scope) — the API does not distinguish, so existence is never confirmed across a scope boundary (02 §4 disclosure posture).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "Idempotency-key reuse with a different body, an invalid state transition, or a uniqueness/business-rule violation (fsd 00 §8.2). For database-backed uniqueness rules, detail names the exact violated rule; unmapped constraints are not collapsed into a generic 409.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnprocessableEntity": { "description": "Field-level validation failed. The body carries both `errors[]` (per-field, pointer-addressed) and a `detail` summarising them — never an empty `detail` (#1251).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" }, "examples": { "singleField": { "summary": "One refused field — `detail` names it", "value": { "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "VALIDATION_FAILED", "detail": "withholding_amount: is required for an India entity", "errors": [ { "pointer": "/withholding_amount", "rule": "required", "message": "is required for an India entity" } ] } }, "severalFields": { "summary": "Several refused fields — `detail` counts and names them", "value": { "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "VALIDATION_FAILED", "detail": "2 fields were refused: effective_from, cap_amount.amount.", "errors": [ { "pointer": "/effective_from", "rule": "cross-field", "message": "Overlaps an existing version." }, { "pointer": "/cap_amount/amount", "rule": "range", "message": "Must be a non-negative decimal string." } ] } } } } } }, "Locked": { "description": "Tenant subscription `past_due` (ADR 0009): WRITES are blocked (423), reads still succeed. `code` = TENANT_PAST_DUE. Mutations return this; list/get operations do not.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Per-principal/route rate limit exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionRequired": { "description": "If-Match header absent on a mutation of a versioned mutable entity (428).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionFailed": { "description": "If-Match / ETag mismatch — the row changed since it was read (412, VERSION_CONFLICT).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "headers": { "ETag": { "description": "Strong validator of the row `version` (e.g. `\"v7\"`). Use as `If-Match` on the next mutation.", "schema": { "type": "string" } }, "Location": { "description": "URI of the created/affected resource.", "schema": { "type": "string", "format": "uri-reference" } }, "IdempotencyReplayed": { "description": "`true` when a stored idempotent response was replayed rather than freshly computed.", "schema": { "type": "boolean" } }, "RetryAfter": { "description": "Seconds to wait before retrying (on 429 / 503).", "schema": { "type": "integer" } } } } }