11.9 Reconciliation

POST /api/v1/reconciliation/sync

Purpose. Queues an import of settlement data from a provider and matching against ledger records.
Authentication. Session cookie, X-DFFMS-Tenant-Id, Origin, Content-Type: application/json. Session must be created within 5 minutes. MFA enrolment is required only if the tenant policy requires it (no step-up check on this route).
Role. CSA, PA, FA, AC (or PSA).
Body.

Field	Type	Required	Rules
`provider`	enum	Yes	`FLUTTERWAVE` or `PAYSTACK`
`from`	date	No	ISO date
`to`	date	No	ISO date; must be on or after `from`

curl -s -X POST https://dffms.org/api/v1/reconciliation/sync \
  -H 'Cookie: __Secure-dffms.session_token=<session-cookie>' \
  -H 'X-DFFMS-Tenant-Id: <tenantId>' \
  -H 'Origin: https://dffms.org' \
  -H 'Content-Type: application/json' \
  -d '{"provider":"PAYSTACK","from":"2026-10-01","to":"2026-10-25"}'

Response (202): the integration job record, with id and status (queued).

{
  "data": { "id": "0190f2c4-6b3e-7a1d-8c2f-000000000090", "status": "QUEUED" },
  "error": null,
  "requestId": "<request-id>"
}

Errors:

HTTP	Code	Meaning
401	`UNAUTHENTICATED`	No session, or session older than 5 minutes.
403	`FORBIDDEN`	Role not permitted.
401	`MFA_REQUIRED`	Tenant requires MFA enrolment.
422	`VALIDATION_ERROR`	Provider not allowed, or date range invalid.
500	`INTERNAL_ERROR`	Job could not be scheduled.

Side effects: inserts an integration job, enqueues finance.settlement.sync_requested, writes audit SETTLEMENT_SYNC_SCHEDULED. When the worker completes, it writes SETTLEMENT_SYNC_COMPLETED. Not idempotent: each call creates a new job.

POST /api/v1/reconciliation/sync​

POST /api/v1/reconciliation/sync