One connected
Celestium
loan journey.

Five interfaces connect one Celestium application to the existing Aarthik journey.

Use four Celestium interfaces and one Aarthik web-hook. Celestium links them to its home-built LOS and LMS dashboards. Aarthik keeps ONDC and the existing provider journeys. Celestium owns credit decisions, disbursement, collections and the loan ledger.

Decision and build boundary

Adopt contract version 2.0 below as the implementation baseline. It replaces the earlier interface proposals. The teams must approve it before production use. These interfaces are specifications, not deployed APIs.

Use one Celestium application, database and delivery worker. The application serves the dashboard and these four routes. Celestium storage remains behind its Documents Upload API. No direct Aarthik write to a Celestium bucket is required.

Two web-hooks move business changes. Dedupe supplies an immediate decision. Status supplies current facts. Documents Upload transfers file bytes. Web-Hook receipt only means that Celestium or Aarthik saved the event.

A dashboard does not replace loan accounting. Celestium must verify schedules, balances, payment allocation and reversals before live disbursement.

Aarthik receives Celestium events at POST /api/celestium/webhook. Add this exact path to the Aarthik host supplied during onboarding. Keep the path spelling unchanged. The proposed Celestium paths have no version prefix. Celestium chooses its final URL structure and versioning. The document and event schema labels do not prescribe URL versioning.

One contract replaces separate lead, offer and servicing APIs.

Keep the useful work

Keep bureau checks, BSA, hosted pages, ONDC mapping, Digio KYC and eSign, and ZipNACH mandate registration. Confirm control of each provider account and its credentials. An unchanged provider name does not prove account access.

Reserve a stable numeric-string loan ID when Celestium registers the lead. This is an application identifier before disbursement. Assign the customer-facing loan account number later. This choice limits changes to the existing Aarthik loan ID reader.

Resolve the offer sequence

Harshil places final borrower acceptance after manual review. Use that order in version 2.0. Lead submission records permission to submit, not final acceptance. If a borrower previously selected an indicative offer, obtain acceptance of the final lender offer. KYC starts only after Celestium records that acceptance.

Use BUSINESS_LOAN with 22 weekly instalments for the initial scope. Do not enable PERSONAL_LOAN or Account Aggregator variants without a separate product decision. Keep both hosted statement upload and buyer-app statement delivery. The existing Account Aggregator route can remain only if approved.

All example identities and amounts are test data. The zero-interest example is for contract testing only. It does not propose a commercial rate.

Celestium controls its cases and accounts through the same stored records that serve the APIs.

Celestium work queues

Show leads, manual review, KYC review, disbursement and collections. Use Aarthik Console to view IGM cases. Celestium does not build an IGM module. Each case page shows its status, owner, accepted offer, evidence, documents and event history. Actions save the business change and outgoing event in one database transaction.

Show failed event deliveries, missing documents, uncertain payment attempts and unmatched receipts. A retry button retries delivery. It must not execute another loan or collection action. Restrict money actions by role and record the operator and reason.

Aarthik support

Aarthik supplies these payloads, a sample journey and the acceptance checklist. Both engineers first prove one lead and one review decision. Aarthik then replaces vendor task calls inside its existing lender adapter. Reuse queues and provider components where their behaviour remains correct.

Each step needs evidence before the next step starts.

A KYC review-ready event does not permit mandate registration. A redirect does not prove an active mandate. An eSign request does not prove signing. An approved loan does not prove disbursement. Keep these states separate.

Celestium must also check the current offer, verified KYC, active mandate when required, signed agreement and required file receipts before disbursement. Preserve Aarthik ONDC order confirmation checks.

Use the same names, types and delivery behaviour across all five interfaces.

Web-Hook signature

X-Sent-At is Unix time in seconds. Compute lowercase hexadecimal HMAC-SHA256 over UTF-8 X-Sent-At, a newline, and the exact raw request bytes. X-Signature is sha256= followed by that digest. Verify with constant-time comparison. Reject attempts more than 300 seconds old or in the future. Use synchronized clocks. Re-sign each retry with a fresh send time. Keep the event unchanged.

Store an incoming event before HTTP 202. Process it in a worker. Save the business change and outgoing event together. Deduplicate by authenticated sender and event_id. Identical duplicates receive HTTP 200 with the original receipt. Different content under the same ID returns HTTP 409.

Set a 10-second event request timeout. Retry transport failures, HTTP 429 and 5xx after 1, 5, 15, 60 and 240 minutes. Respect a longer Retry-After. Then alert operations and retain the event for authorized replay. Never discard an unfinished event automatically.

The transport receipt is separate from the business result.

Complete event example

{
  "event_version": "2.0",
  "event_id": "11111111-1111-4111-8111-000000000003",
  "event_type": "OFFER_DECISION_RECORDED",
  "occurred_at": "2026-09-28T10:00:00Z",
  "sender": "AARTHIK_LABS",
  "entity_type": "CASE",
  "entity_id": "AL-CASE-0001",
  "entity_version": 3,
  "correlation": {
    "external_reference_id": "AL-CASE-0001",
    "celestium_lead_id": "1001",
    "celestium_loan_id": "2001"
  },
  "data": {
    "offer_id": "OFFER-1001-1",
    "decision": "ACCEPT",
    "decided_at": "2026-09-28T10:00:00Z",
    "reason": null
  }
}

HTTP 202 receipt or HTTP 200 duplicate receipt

{
  "event_id": "11111111-1111-4111-8111-000000000003",
  "receipt_status": "RECEIVED",
  "received_at": "2026-09-28T10:00:00Z"
}

receipt_status is RECEIVED for both first receipt and an identical replay. The original received_at stays unchanged. No other business success is implied. A failed business action is returned as EVENT_PROCESSING_FAILED.

external_reference_id is the stable Aarthik case ID. It is not an ONDC transaction ID. Keep ONDC and buyer journey mappings inside Aarthik. For LEAD_SUBMITTED, Celestium IDs are null. Celestium assigns both in LEAD_REGISTERED. Later events must match all three saved IDs.

entity_type is CASE or PAYMENT. entity_id is that object ID. entity_version increases per sender and object. Never compare versions from different senders or unrelated payments. Hold a gap or invalid prerequisite for recovery. Apply duplicates once. Do not order events by arrival time.

Use event_type to route one receiver to the correct handler.

All listed event types use the same envelope and receipt. For all but payment objects, entity_type is CASE and entity_id is external_reference_id. PAYMENT_UPDATED uses PAYMENT and payment_id. Authenticate the sender before accepting its event types.

A match alone is not a credit decision.

POST /dedupe request

{
  "request_id": "22222222-2222-4222-8222-222222222222",
  "external_reference_id": "AL-CASE-0001",
  "product": "BUSINESS_LOAN",
  "applicant": {
    "pan": "ABCDE1234F",
    "mobile": "9999999999",
    "date_of_birth": "1990-01-01",
    "name": "Example Borrower"
  }
}

HTTP 200 response

{
  "request_id": "22222222-2222-4222-8222-222222222222",
  "external_reference_id": "AL-CASE-0001",
  "dedupe_reference_id": "DD-1001",
  "match_status": "NO_MATCH",
  "decision": "PROCEED",
  "reason_code": "NO_BLOCKING_MATCH",
  "reason_message": "No blocking record found",
  "existing_celestium_lead_id": null,
  "existing_celestium_loan_id": null,
  "checked_at": "2026-09-28T10:00:00Z"
}

All keys are required. Existing IDs are nullable. match_status is NO_MATCH, MATCH or AMBIGUOUS. decision is PROCEED, DECLINE or REVIEW_REQUIRED. AMBIGUOUS requires REVIEW_REQUIRED. PROCEED can follow a permitted existing record. Never infer permission from NO_MATCH alone.

Celestium applies its approved matching and product policy. Verify PAN format and compare the same borrower identity on lead submission. Names alone must not decide a match. Return only references that the partner may access.

Use Idempotency-Key equal to request_id. An identical retry returns the saved check. A fresh check needs a new request_id. Celestium must reject a lead if its dedupe decision is missing, stale under its approved policy, or belongs to another borrower. Timeout, invalid response and REVIEW_REQUIRED stop automatic progression.

One event carries the complete lead data. Binary reports use Documents Upload.

LEAD_SUBMITTED data keys and consent object

{
  "dedupe_reference_id": "DD-1001",
  "product": "BUSINESS_LOAN",
  "consents": {
    "bureau": {
      "accepted": true,
      "at": "2026-09-28T10:00:00Z"
    },
    "bank_analysis": {
      "accepted": true,
      "at": "2026-09-28T10:00:00Z"
    },
    "data_sharing": {
      "accepted": true,
      "at": "2026-09-28T10:00:00Z"
    },
    "submission": {
      "accepted": true,
      "at": "2026-09-28T10:00:00Z"
    }
  },
  "documents_expected": [
    {
      "document_reference_id": "DOC-BUR-001",
      "document_type": "BUREAU_REPORT"
    },
    {
      "document_reference_id": "DOC-BSA-001",
      "document_type": "BANK_ANALYSIS_REPORT"
    }
  ]
}

Add the borrower, business, banking, bureau and proposed_offer objects defined on the next pages to this same data object. The downloadable examples contain the complete event. Do not send these objects as separate requests.

Only one lead can exist for authenticated partner plus external_reference_id. A second event ID cannot create another case for that reference. A changed lead after submission needs operator correction and a controlled new review. Do not silently replace the original evidence.

Return a transport receipt first. After case creation, Celestium sends LEAD_REGISTERED with status DOCUMENTS_PENDING or UNDER_REVIEW. All required manifest uploads must be stored before review starts. Submission consent does not mean offer acceptance.

LEAD_REGISTERED data from Celestium

{
  "status": "DOCUMENTS_PENDING",
  "documents_pending": [
    "DOC-BUR-001",
    "DOC-BSA-001"
  ]
}

The LEAD_REGISTERED envelope contains the newly reserved celestium_lead_id and celestium_loan_id. Status also exposes these IDs. Aarthik can read Status if the event is delayed. Never create a second case because a response is missing.

These objects sit inside LEAD_SUBMITTED data.

borrower

{
  "first_name": "Example",
  "middle_name": null,
  "last_name": "Borrower",
  "date_of_birth": "1990-01-01",
  "pan": "ABCDE1234F",
  "mobile": "9999999999",
  "email": "borrower@example.test",
  "employment_type": "SELF_EMPLOYED",
  "monthly_income": null,
  "residential_address": {
    "line1": "Example address",
    "line2": null,
    "city": "Chennai",
    "state": "Tamil Nadu",
    "postal_code": "600001",
    "country": "IND"
  }
}

business

{
  "name": "Example Traders",
  "constitution": "PROPRIETORSHIP",
  "industry": "RETAIL",
  "pan": null,
  "gstin": null,
  "udyam_number": null,
  "annual_turnover": null,
  "address": {
    "line1": "Example address",
    "line2": null,
    "city": "Chennai",
    "state": "Tamil Nadu",
    "postal_code": "600001",
    "country": "IND"
  }
}

Identity fields, SELF_EMPLOYED and both addresses are required for this initial business product. middle_name, email, monthly_income, tax IDs, udyam_number, annual_turnover and address.line2 may be null. Do not infer missing values. Do not send full Aadhaar or bank-login credentials.

constitution and industry are source labels displayed to reviewers. Celestium must not silently convert an unknown label to a different legal form. Validate and map any required internal master values before enabling automatic processing.

Send actual provider data and an explicit no-data state.

banking

{
  "status": "COMPLETED",
  "source": "STATEMENT_UPLOAD",
  "analysis_reference_id": "BSA-001",
  "analyzed_at": "2026-09-28T10:00:00Z",
  "period_from": "2026-03-01",
  "period_to": "2026-08-31",
  "report_data": null,
  "unavailable_reason": null,
  "account": {
    "holder_name": "Example Borrower",
    "account_number": "000000001234",
    "ifsc": "TEST0000001",
    "account_type": "SAVINGS",
    "bank_name": "Example Bank"
  }
}

bureau

{
  "provider": "CIBIL",
  "status": "AVAILABLE",
  "report_reference_id": "BUR-001",
  "pulled_at": "2026-09-28T10:00:00Z",
  "score": 750,
  "report_data": null,
  "unavailable_reason": null
}

proposed_offer

{
  "reference_id": "AL-OFFER-001",
  "currency": "INR",
  "loan_amount": "22000.00",
  "tenure_weeks": 22,
  "installment_frequency": "WEEKLY",
  "bre_reference_id": "BRE-001",
  "bre_decision": "ELIGIBLE"
}

banking.source is STATEMENT_UPLOAD, BUYER_APP or approved ACCOUNT_AGGREGATOR. banking.status is COMPLETED, NOT_PROVIDED or FAILED. bureau.status is AVAILABLE, NO_HIT or FAILED. Non-success requires unavailable_reason. Reference IDs, dates, score and report_data can be null when unavailable.

report_data is the consented native provider JSON object, or null if the report is supplied as a manifest file. Do not fabricate a provider schema. Celestium can first display the uploaded reports without parsing each native report. Its approved policy determines whether no-data cases can proceed.

proposed_offer is an Aarthik recommendation. It is not final sanction. BRE results remain ELIGIBLE, INELIGIBLE or REVIEW_REQUIRED. Only a permitted case reaches submission. JSON event size is limited to 2 MiB; send larger reports as files.

banking.account may be null when unavailable. When present, all illustrated account fields are required. It is evidence from the consented source, not automatic payout authorization. Celestium must verify the beneficiary through its approved process before disbursement.

Return the complete offer once. Acceptance then refers to its immutable ID.

MANUAL_REVIEW_DECIDED data from Celestium

{
  "decision": "APPROVED",
  "reason_code": "APPROVED_AS_APPLIED",
  "reason_message": "Approved on the displayed terms",
  "reviewed_at": "2026-09-28T10:00:00Z",
  "offer": {
    "offer_id": "OFFER-1001-1",
    "currency": "INR",
    "loan_amount": "22000.00",
    "tenure_weeks": 22,
    "installment_frequency": "WEEKLY",
    "number_of_installments": 22,
    "installment_amount": "1000.00",
    "annual_interest_rate_percent": "0.00",
    "apr_percent": "0.00",
    "interest_rate_type": "FIXED",
    "processing_fee_amount": "0.00",
    "tax_amount": "0.00",
    "other_upfront_charges": "0.00",
    "net_disbursed_amount": "22000.00",
    "total_interest_amount": "0.00",
    "total_payable_amount": "22000.00",
    "valid_until": "2026-10-01T10:00:00Z",
    "kfs_url": "https://celestium.example.test/kfs/offer-1001-1",
    "terms_url": "https://celestium.example.test/terms/offer-1001-1"
  }
}

decision is APPROVED or REJECTED. Rejection requires a reason and offer=null. Approval requires all offer keys. A changed offer gets a new offer_id and a fresh borrower decision. Never edit terms under the old ID. Reject expired or superseded acceptance.

The example has 22 payments of INR 1000 and no charges. Production rates, APR, rounding, disclosures and fees must agree with the approved schedule and KFS. Authorize document access. KFS and terms URLs must be usable for the borrower journey without exposing other cases.

For a rounding adjustment, set installment_amount to the regular amount and use the approved schedule for the final amount. The KFS must disclose that difference. The total payable amount must equal the complete schedule.

Use events instead of an offer decision API.

OFFER_DECISION_RECORDED data from Aarthik

{
  "offer_id": "OFFER-1001-1",
  "decision": "ACCEPT",
  "decided_at": "2026-09-28T10:00:00Z",
  "reason": null
}

OFFER_DECISION_CONFIRMED data from Celestium

{
  "source_event_id": "11111111-1111-4111-8111-000000000003",
  "offer_id": "OFFER-1001-1",
  "decision": "ACCEPT",
  "recorded_at": "2026-09-28T10:00:00Z"
}

decision is ACCEPT, REJECT or EXPIRE. reason is nullable except when a meaningful rejection reason is available. Celestium verifies the current offer, expiry and prior decision. It records the immutable offer ID and the decision once. A business confirmation or the matching offer decision in Status permits the next step. HTTP 202 alone does not.

If the same offer is already accepted, a conflicting REJECT or EXPIRE must fail. Later cancellation is outside this first-release contract. Do not overwrite accepted terms. A new offer needs a new decision. Accept timestamps must come from the captured borrower action.

EVENT_PROCESSING_FAILED data in either direction

{
  "source_event_id": "11111111-1111-4111-8111-000000000003",
  "code": "STALE_OFFER",
  "message": "The offer has been replaced",
  "retryable": false,
  "failed_at": "2026-09-28T10:00:00Z"
}

Use this failure event when a stored event cannot be applied. Supported codes are VALIDATION_ERROR, IDENTITY_CONFLICT, STALE_OFFER, INVALID_STATE and PROCESSING_ERROR. retryable describes the business processing failure. Delivery retries still follow the transport rules.

Show processing failures in the support queue. Correct the cause before replay. For corrected content, create a new event ID and entity version. Never respond to EVENT_PROCESSING_FAILED with another failure event. Send failed failure-event deliveries to operations.

Celestium returns missing documents and current case state in Status. Aarthik uses Status to recover a delayed lead or acceptance result. Celestium asks Aarthik to replay missing journey events from its durable event log. No sixth partner interface is required.

A processing failure before lead registration retains the original null Celestium IDs. Correlate it by authenticated sender, external_reference_id and source_event_id. It must not create a loan.

Provider verification and lender review are two separate facts.

KYC_UPDATED data from Aarthik

{
  "provider": "DIGIO",
  "provider_reference_id": "KID-EXAMPLE",
  "mode": "VIDEO_AND_MANUAL_REVIEW",
  "status": "REVIEW_READY",
  "verified": false,
  "provider_event_id": "DIGIO-EVT-001",
  "provider_updated_at": "2026-09-28T10:00:00Z",
  "document_ids": [],
  "reason_code": null
}

KYC_REVIEW_DECIDED data from Celestium

{
  "provider": "DIGIO",
  "provider_reference_id": "KID-EXAMPLE",
  "decision": "APPROVED",
  "reviewed_at": "2026-09-28T10:00:00Z",
  "reviewer_reference": "STAFF-001",
  "reason_code": "REVIEW_COMPLETED",
  "reason_message": null
}

KYC_UPDATED.status is REQUESTED, REVIEW_READY, APPROVED, REJECTED, TERMINATED or EXPIRED. mode is STANDARD or VIDEO_AND_MANUAL_REVIEW. verified is true only for provider-confirmed APPROVED. provider_event_id can be null after provider status polling. provider_reference_id and provider_updated_at remain required.

For VKYC, Celestium staff complete the review through the supported Digio portal or approved Digio integration. The dashboard records that action and sends KYC_REVIEW_DECIDED. decision is APPROVED or REJECTED. reviewer_reference identifies an authorized operator. reason_code is required; reason_message may be null.

Aarthik stores the lender decision and checks the matching Digio request. It waits for the verified Digio outcome before mandate initiation. A web-hook button in the Celestium dashboard cannot invent Digio approval. A disagreement stays pending for operations.

For STANDARD KYC, a separate Celestium review event is not required unless lender policy requires it. Provider-confirmed rejection, termination or expiry stops progression. Required documents upload independently when the provider makes them available. Video availability must not block the supported provider review itself.

reason_code may be null for successful or pending outcomes. Supply the actual provider reason when a failure, rejection or expiry includes one. Do not invent a reason.

Registration, provider completion and file storage remain distinct.

MANDATE_UPDATED data from Aarthik

{
  "provider": "ZIPNACH",
  "provider_reference_id": "MANDATE-001",
  "umrn": "TEST-UMRN-001",
  "status": "ACTIVE",
  "verified": true,
  "maximum_amount": "1000.00",
  "currency": "INR",
  "frequency": "WEEKLY",
  "valid_from": "2026-10-01",
  "valid_until": "2027-03-31",
  "provider_updated_at": "2026-09-28T10:00:00Z",
  "document_ids": [],
  "reason_code": null
}

ESIGN_UPDATED data from Aarthik

{
  "provider": "DIGIO",
  "provider_reference_id": "DID-EXAMPLE",
  "status": "COMPLETED",
  "verified": true,
  "provider_event_id": "DIGIO-EVT-003",
  "provider_updated_at": "2026-09-28T10:00:00Z",
  "document_ids": [
    "CDOC-AGREEMENT-001"
  ],
  "reason_code": null
}

Mandate status is REQUESTED, PENDING, ACTIVE, REJECTED, CANCELLED or EXPIRED. verified=true only for provider-confirmed ACTIVE. umrn, limit, frequency and dates may be null until the provider returns them. ACTIVE must include the collection reference, limits and validity needed by Celestium. Use the actual authorized frequency, including AS_PRESENTED if applicable.

eSign status is REQUESTED, COMPLETED, EXPIRED, CANCELLED or FAILED. verified=true only after provider-confirmed completion. provider_event_id may be null after polling. document_ids can be empty while upload retries. A completed signature alone does not satisfy the required signed-file receipt.

document_ids are Celestium upload receipts. No public borrower-file URL appears in these events. A missing file stays pending in Status. Celestium must not request the borrower to sign again only because storage failed.

reason_code may be null for successful or pending outcomes. Supply the actual provider reason when a failure, rejection or expiry includes one. Do not invent a reason.

Celestium receives bytes and owns storage, access and retention.

POST /documents multipart request

Authorization: Bearer <credential>
Idempotency-Key: 44444444-4444-4444-8444-444444444444
Content-Type: multipart/form-data; boundary=<client boundary>

request_id = 44444444-4444-4444-8444-444444444444
external_reference_id = AL-CASE-0001
celestium_lead_id = 1001
celestium_loan_id = 2001
document_reference_id = DOC-BUR-001
document_type = BUREAU_REPORT
provider_reference_id = BUR-001
file = bureau-report.pdf (binary application/pdf)

HTTP 201 response or HTTP 200 identical replay

{
  "request_id": "44444444-4444-4444-8444-444444444444",
  "external_reference_id": "AL-CASE-0001",
  "celestium_lead_id": "1001",
  "celestium_loan_id": "2001",
  "document_reference_id": "DOC-BUR-001",
  "document_id": "CDOC-BUR-001",
  "document_type": "BUREAU_REPORT",
  "file_name": "bureau-report.pdf",
  "content_type": "application/pdf",
  "size_bytes": 125000,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "STORED",
  "stored_at": "2026-09-28T10:00:00Z"
}

Every form field is required except provider_reference_id. Upload after LEAD_REGISTERED or a Status response supplies both Celestium IDs. Use one file per request. No base64, bucket credential or public source URL is required. The sha256 example is a placeholder; the server returns the actual byte digest.

Return STORED only after the file passes validation and is durably stored with its case metadata. Use private storage and restricted dashboard access. Stream the file to storage. If metadata save fails after storage succeeds, recover the same object on retry. Never report success for an unfinished background upload.

Idempotency covers identifiers, document type and file bytes. Same key with changed content returns 409. A replacement uses a new document_reference_id and request_id. Preserve the old file for audit. A failed upload retries independently from KYC or signing.

One upload route supports every agreed evidence category.

These are version 2.0 limits, not verified provider limits. Test the largest real provider file in UAT. Change the agreed limit before release if needed. Do not split one file into undocumented chunks or silently truncate it.

Check actual file content, not only its extension or supplied MIME type. Reject corrupt, unsafe, unsupported or oversized files. Validate case ownership and all IDs. Do not log file contents. Apply malware controls before making files available to staff.

Celestium links each stored document_reference_id to documents_expected automatically. Status returns stored and pending references. A new status event is not needed just to confirm a synchronous upload. Upload receipt is separate from the provider outcome.

At LEAD_SUBMITTED, require bureau and banking evidence where applicable. Before disbursement, require the approved KYC evidence and whole signed agreement. The exact KYC list follows the selected Digio workflow. Do not require an artifact that the provider does not produce.

Preserve document_reference_id across retries. Store document_id, checksum, type, size, uploader and time. Set retention and access policy before live use. The storage implementation can change without changing this API.

One read returns current case and account facts from one snapshot.

Request

GET /status?external_reference_id=AL-CASE-0001
Authorization: Bearer <credential>
X-Request-Id: 55555555-5555-4555-8555-555555555555

HTTP 200 envelope fields

{
  "request_id": "55555555-5555-4555-8555-555555555555",
  "external_reference_id": "AL-CASE-0001",
  "celestium_lead_id": "1001",
  "celestium_loan_id": "2001",
  "snapshot_version": 8,
  "snapshot_at": "2026-10-05T12:00:00Z",
  "case_status": "DISBURSED",
  "loan_status": "ACTIVE",
  "loan_account_id": "CEL-ACCOUNT-0001",
  "offer": {
    "offer_id": "OFFER-1001-1",
    "decision": "ACCEPT",
    "source_event_id": "11111111-1111-4111-8111-000000000003",
    "recorded_at": "2026-09-28T10:00:00Z"
  },
  "checks": {
    "kyc": "APPROVED",
    "lender_kyc_review": "APPROVED",
    "mandate": "ACTIVE",
    "esign": "COMPLETED"
  }
}

Add documents, disbursement, soa, amortization_schedule and payments from the next pages to this same response. The downloadable status_response example contains the complete body and all 22 schedule rows. This read has no request body.

Before account creation, loan_account_id, soa and amortization_schedule are null and payments is an empty array. Celestium IDs can be null only before lead registration. A known receipt can report RECEIVED; an unknown reference returns 404. Do not create a case from a Status read.

offer is null before review. Its decision is PENDING, ACCEPT, REJECT or EXPIRE; source_event_id and recorded_at are null until recorded. checks use the event status enums plus NOT_STARTED; lender_kyc_review also permits NOT_REQUIRED. All sections must use the same snapshot_version and snapshot_at.

documents contains stored and pending arrays. Each stored item has document_reference_id, document_id and document_type. pending contains required document_reference_id strings. Return every stored file. Do not omit a required signed or KYC file from a disbursed case.

SOA shows current balances. The schedule shows each repayment obligation.

soa object

{
  "currency": "INR",
  "updated_at": "2026-10-05T12:00:00Z",
  "disbursed_amount": "22000.00",
  "principal_outstanding": "21000.00",
  "interest_outstanding": "0.00",
  "penalty_outstanding": "0.00",
  "charges_outstanding": "0.00",
  "total_outstanding": "21000.00",
  "total_overdue": "0.00"
}

amortization_schedule row model

{
  "installment_id": "INST-001",
  "installment_number": 1,
  "due_date": "2026-10-05",
  "principal": "1000.00",
  "interest": "0.00",
  "charges": "0.00",
  "amount": "1000.00",
  "paid_amount": "1000.00",
  "unpaid_amount": "0.00",
  "status": "PAID",
  "updated_at": "2026-10-05T12:00:00Z"
}

amortization_schedule contains schedule_version, updated_at, frequency and installments. installments contains every row, including paid rows. Initial product frequency is WEEKLY with 22 rows. Each row uses the model above. The complete JSON download includes all rows, without ellipses.

All money fields here are nonnegative decimal strings. total_outstanding equals principal, interest, penalty and charges outstanding. total_overdue cannot exceed total_outstanding. Each row amount equals principal plus interest plus charges. paid_amount plus unpaid_amount equals amount. status is DUE, PART_PAID, PAID or OVERDUE. A failed debit is a payment result, not a paid instalment.

Return actual lender updated times. Do not replace them with fetch time. Aarthik rejects an inconsistent or over-15-minute-old snapshot for money-dependent actions. Retry or show pending data. Configure a stricter policy if required. SOA is not a binding foreclosure quote. Amend schedules through versioned ledger corrections; preserve history internally.

A Status response and a web-hook use the same financial record shapes.

disbursement object and DISBURSEMENT_UPDATED data

{
  "disbursement_id": "DISB-001",
  "status": "DISBURSED",
  "amount": "22000.00",
  "currency": "INR",
  "bank_reference": "TEST-UTR-DISB-001",
  "updated_at": "2026-09-28T10:00:00Z",
  "reason_code": null
}

One payments array item and PAYMENT_UPDATED data

{
  "payment_id": "PAY-001",
  "claim_reference": null,
  "collection_id": "COLL-001",
  "mandate_reference": "MANDATE-001",
  "installment_ids": [
    "INST-001"
  ],
  "method": "ENACH",
  "status": "POSTED",
  "amount": "1000.00",
  "currency": "INR",
  "bank_reference": "TEST-UTR-PAY-001",
  "provider_reference": "ZIP-PRESENT-001",
  "value_date": "2026-10-05",
  "updated_at": "2026-10-05T12:00:00Z",
  "reason_code": null,
  "reversal_of_payment_id": null
}

disbursement.status is PENDING, DISBURSED or FAILED. bank_reference is null until verified; DISBURSED requires it. Do not use a request acknowledgement as disbursement evidence. Celestium executes the transfer outside this partner contract.

payment.status is PENDING_VERIFICATION, SUBMITTED, PROCESSING, FAILED, POSTED or REVERSED. POSTED means verified receipt and ledger allocation. Intermediate provider success is not POSTED. A reversal is a separate negative ledger operation; its API amount stays positive and reversal_of_payment_id names the original receipt.

claim_reference, collection_id, mandate_reference, bank_reference, provider_reference, value_date, reason_code and reversal_of_payment_id may be null when not applicable. POSTED requires value_date and traceable bank or provider evidence. payments returns all attempts and receipts for this 22-week loan. No silent truncation is allowed. Add agreed same-route pagination before extending to larger portfolios.

A borrower claim enters a verification queue. It does not update the balance.

PAYMENT_CLAIM_SUBMITTED data from Aarthik

{
  "claim_reference": "CLAIM-001",
  "service_type": "MISSED_EMI",
  "amount": "1000.00",
  "currency": "INR",
  "payment_date": "2026-10-05",
  "method": "UPI",
  "transaction_reference": "TEST-UTR-CLAIM-001",
  "document_ids": []
}

LOAN_STATUS_UPDATED data from Celestium

{
  "loan_status": "ACTIVE",
  "snapshot_version": 8,
  "updated_at": "2026-10-05T12:00:00Z",
  "reason_code": null
}

service_type is MISSED_EMI or PRE_PART_PAYMENT. FORECLOSURE requires an agreed quote process and is outside this release. method is NEFT, RTGS, IMPS or UPI. amount must be positive. Upload optional proof through Documents Upload. Empty document_ids means no file was supplied.

Celestium verifies the claim against bank records, detects the same receipt reported through another channel, then posts it once. It sends PAYMENT_UPDATED with claim_reference. Reject unsupported or unmatched claims with FAILED and a reason. A screenshot is not proof of settled receipt.

loan_status is NOT_CREATED, ACTIVE, OVERDUE, CLOSED or CANCELLED. CLOSED requires the approved ledger closure conditions. A reversal can reopen a closed account through an explicit newer lender state. Aarthik refreshes Status after a loan or payment event. It never calculates current balances from events alone.

Reject inconsistent inputs and keep business results visible.

Common non-success response

{
  "request_id": "22222222-2222-4222-8222-222222222222",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A required field is invalid",
    "retryable": false,
    "fields": [
      {
        "path": "applicant.pan",
        "message": "Invalid PAN format"
      }
    ]
  }
}

For web-hook errors request_id equals event_id when available. For malformed requests use X-Request-Id, or null when no valid ID exists. fields is an empty array for non-field errors. Error codes are VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, TOO_LARGE, UNSUPPORTED_MEDIA, RATE_LIMITED or INTERNAL_ERROR.

After a timeout, repeat the same operation with the same key. Never allocate a new key merely to bypass uncertainty. Keep idempotency and event records for the active case or loan and the approved post-closure retention period. Compare both systems daily during the pilot.

Celestium must request each debit after Aarthik completes mandate registration.

A mandate authorizes collection. Presentation requests a specific debit. These are separate operations. Aarthik keeps the existing ZipNACH registration journey. Celestium owns presentation, borrower collection notices, results, settlement checks and ledger posting.

The smallest first release

If ZipNACH and the sponsor bank enable an approved portal or file channel, start with that channel. Celestium prepares dues in its dashboard. An authorized operator submits them and imports results. Use a second approval where Celestium policy requires it. This is conditional on provider confirmation, not a claim that the current account includes a portal.

If no supported operational channel exists, Celestium must integrate the provider collection API before launching automatic repayments. Do not use the mandate registration Create or GetStatus call to request a debit. Do not build a direct NPCI connector for this migration unless the sponsor bank requires it.

The five interfaces between Aarthik and Celestium remain unchanged. Provider collection calls and callbacks are Celestium internal integration work. A provider callback can need its own private route. It is not a sixth Aarthik partner API.

Use one collection record to connect the due amount, provider attempt and ledger receipt.

Celestium internal collection record

{
  "collection_id": "COLL-001",
  "celestium_loan_id": "2001",
  "installment_ids": [
    "INST-001"
  ],
  "mandate_reference": "MANDATE-001",
  "umrn": "TEST-UMRN-001",
  "amount": "1000.00",
  "currency": "INR",
  "collection_date": "2026-10-05",
  "attempt_number": 1,
  "status": "PREPARED",
  "provider_reference": null,
  "submitted_at": null,
  "updated_at": "2026-09-28T10:00:00Z"
}

This is an internal model, not a claimed ZipNACH request schema. Celestium maps it to the provider contract after onboarding. Keep registration credentials and collection credentials separately scoped. Store provider secrets only in Celestium server configuration.

The unique business guard is loan plus due obligation plus active attempt. A database constraint and an approved state transition prevent two workers from submitting the same debit. Preserve the collection_id on retries. A provider call can succeed even when the network response is lost.

Celestium signs its normalized PAYMENT_UPDATED events to Aarthik. Aarthik verifies them and reads Status. Celestium must not send raw provider callbacks as if they were the agreed partner event.

Confirm the collection channel and mandate authority before setting a launch date.

Do not assume an active UMRN is portable to a different corporate or utility setup. Obtain written provider and sponsor-bank confirmation. Re-register only if required. Do not stop a valid borrower mandate without an approved migration plan.

Before launch, test one accepted presentation, one failure, one duplicate result, one uncertain submission and one reversal. Verify allocation, outstanding amount, instalment state and the Aarthik display. Test a manual borrower payment that overlaps a scheduled debit.

No provider-specific presentation endpoint, cutoff or retry limit is asserted here. Those details require the enabled ZipNACH collection product and sponsor-bank contract. The Aarthik and Celestium interface payloads remain fixed while Celestium resolves that adapter.

Create one support email ID that the support team monitors. Share it with Aarthik. Name the primary owner and an escalation contact. Aarthik will grant Console IGM access to the nominated users.

Use the original email thread and keep the issue reference unchanged. State the action taken, the reason and any information still required. Send only relevant evidence. Do not include passwords or full payment credentials.

Check the Console for the current case state. Sending an email alone does not prove that ONDC received the response or that the issue is closed. Aarthik handles response delivery, clarification, escalation and closure under the applicable IGM process.

Aarthik will connect incoming ONDC issues to Console cases and email notifications. Replies from the registered support mailbox will attach to the correct case. Aarthik will maintain the ONDC issue reference, message history and response due time.

Aarthik will handle ONDC formatting and delivery. Duplicate email replies must not create duplicate network responses. Unmatched replies, delivery failures and replies from an unregistered sender go to an Aarthik support queue.

Both teams will test one new issue, one clarification, one resolution and one failed email delivery before launch. Confirm mailbox access, authorized senders, attachment rules, response times and escalation contacts during setup. This page defines the planned flow; it does not confirm that mailbox access is already enabled.

Grievance events and grievance attachments are removed from the Celestium partner API contract. The event catalogue now has 14 event types. The five loan interfaces stay the same. Issue communications and evidence use the Console and email flow.

Celestium still owns the investigation and lender response. Aarthik owns the ONDC exchange. If a grievance reveals an incorrect payment or loan record, Celestium corrects its LMS and sends the normal payment or loan status event. That event updates the loan record; the email response updates the issue.

Complete each check before increasing the pilot size.

Assign one backend to each case. Preserve legacy ID mappings for old cases. New cases use version 2.0 only. Do not send the same business action through both contracts.

Export existing cases, terms, balances, schedules, consent records, mandate references, files and unresolved grievances. Reconcile counts and amounts at a recorded cutover time. Capture changes that occur during transfer.

If authorized old-system access remains, existing cases may finish there. If access ends, pause affected cases until Celestium verifies their records. Never assume rollback access exists.

If the pilot fails, stop new intake and preserve queued work. Keep confirmed bank movements. A software rollback must not repeat or reverse a money transaction.

Approve business ownership and prove the failure paths before production.

Record these decisions in the meeting

Name the Celestium engineering, credit, finance and operations owners. Approve version 2.0, the initial product and file limits. Confirm provider account control, the collection channel, mandate portability and the ledger. Set support contacts, pilot size and release authority. Estimate dates after these decisions.

Track review age, event failures, missing files, uncertain collections and unmatched receipts. Compare account records daily during the pilot. A technical test does not prove bank settlement. Celestium finance must approve financial results.

Use one meaning for each state and technical term.

Source basis: Harshil’s Celestium LOS API and web-hook contract, version 1.0, dated 27 September 2026; the original eight-page sequence; Harshil’s updated nine-page sequence dated 27 September 2026; and the Aarthik integration review. Version 2.0 replaces the source contract’s separate lead and offer APIs, split servicing reads, legacy field names and public file links.

NPCI explains that mandate authorization and debit processing are separate activities. The exact collection product, bank arrangement and enabled provider channel must be confirmed for Celestium. Public provider information does not establish its account permissions.

Primary references: NPCI NACH Procedural Guidelines V.7; NPCI eMandate eSign FAQ; ZipNACH product and models pages. These support the process boundary, not a fabricated provider API contract.

https://www.npci.org.in/PDF/nach/notofied-document/NACH-Procedural-Guidelines-V.7.pdf
https://www.npci.org.in/what-we-do/nach/faqs/emandate-esign-variant
https://yoekisoft.com/yoeki/productsmodal
https://fineract.apache.org/docs/1.15.0/

The examples are independent fixtures, not a chronological replay script. Use actual IDs, sequence versions, document checksums and provider results in UAT. Synthetic bank and borrower values must never be sent to live financial providers.

Complete JSON examples and the shared guide: https://celestium-transition-guide.aarthiklabs.chatgpt.site/contract-examples.json

Use the new nine-page sequence for the journey. Use the five-interface contract for partner implementation.

Harshil’s Celestium LOS Updated Sequence Diagrams dated 27 September 2026 separates Aadhaar KYC from video KYC. It places final borrower acceptance after lender review. These steps are retained. The diagram uses six older API boundaries and legacy event names. The mapping below applies the agreed simpler contract.

The event names in the diagram describe existing boundaries. They do not prove that the existing endpoint accepts the proposed version 2.0 payload. Aarthik must implement or verify the adapter before UAT. Confirm authentication and the host for /api/celestium/webhook during onboarding.

Preserve existing behaviour where required. Confirm these differences before UAT.

The diagram includes eligible self-employed personal loans and consented Account Aggregator data. Retain these as documented variants. Confirm product and provider enablement before activation. The initial contract remains BUSINESS_LOAN with 22 weekly instalments. Do not show a Celestium offer to salaried personal-loan applicants. There is no 150-day option.

Retain missed EMI, part-prepayment and foreclosure as servicing intents. SOA is not a binding foreclosure quote. Do not initiate a foreclosure payment until Celestium provides a valid approved quote and instructions. Confirm the quote process before enabling that action.

EXPIRE remains a proposed lifecycle extension that Celestium must approve before activation. Stale or expired offers cannot unlock KYC. An email or receipt cannot replace the required business confirmation.

Keep existing buyer-facing signed-document delivery in Aarthik. Confirm the current link expiry and retention configuration separately. The diagram describes an approximate seven-day link lifecycle. Celestium receives its durable copy through Documents Upload. Public file URLs are not required in the new partner events.