{
  "components": {
    "parameters": {
      "IdempotencyKey": {
        "description": "Optional but strongly recommended on all POSTs. The first request executes; retries with the same key replay the cached response (header `Idempotent-Replayed: true`). Reuse across a different method/path returns 409.",
        "in": "header",
        "name": "Idempotency-Key",
        "required": false,
        "schema": {
          "maxLength": 255,
          "type": "string"
        }
      }
    },
    "responses": {
      "Forbidden": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "The credential lacks the lending permission, is disabled, or (sandbox routes) is a live-mode key."
      },
      "NotFound": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "The resource does not exist within your organisation scope (foreign ids also return 404, so there is no existence leak)."
      },
      "RateLimited": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Per-key rate limit exceeded. Back off and retry."
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Missing or invalid API key credentials."
      },
      "ValidationError": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Request body failed validation."
      }
    },
    "schemas": {
      "AMLScreenStatus": {
        "description": "Outcome of MyItura's independent AML/sanctions screen.",
        "enum": [
          "pending",
          "clear",
          "hit"
        ],
        "type": "string"
      },
      "APIResponse": {
        "description": "Standard response envelope wrapping every JSON response.",
        "properties": {
          "data": {
            "description": "The response payload; shape varies per endpoint. Omitted when empty.",
            "nullable": true
          },
          "error": {
            "description": "Machine-readable error code or detail. Omitted on success.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable outcome summary.",
            "type": "string"
          },
          "status": {
            "description": "HTTP status code, echoed in the body.",
            "type": "integer"
          },
          "success": {
            "description": "True for 2xx responses.",
            "type": "boolean"
          }
        },
        "required": [
          "status",
          "success",
          "message"
        ],
        "type": "object"
      },
      "APIUsageDailyRollup": {
        "description": "One day of the organisation's metered API usage.",
        "properties": {
          "day": {
            "format": "date-time",
            "type": "string"
          },
          "errorCount": {
            "description": "Requests that returned a 4xx/5xx status.",
            "format": "int64",
            "type": "integer"
          },
          "requestCount": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "AcceptTermsRequest": {
        "properties": {
          "consent": {
            "$ref": "#/components/schemas/BorrowerConsent"
          }
        },
        "required": [
          "consent"
        ],
        "type": "object"
      },
      "ApprovalMode": {
        "description": "Who approves loans on the product. `partner_pushed`: the decision is made on the partner's side and pushed via POST /v1/preapprovals; the loan's economics come from the pushed decision rather than the product's own pricing.",
        "enum": [
          "tenant",
          "auto_credit_score",
          "myitura_analyst",
          "partner_pushed"
        ],
        "type": "string"
      },
      "Borrower": {
        "description": "Org-scoped lending identity for a tenant's customer. API-only borrowers get no MyItura user account; the raw BVN is never returned (stored only as a keyed hash).",
        "properties": {
          "clientReference": {
            "description": "The tenant's own identifier for this borrower.",
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "email": {
            "format": "email",
            "nullable": true,
            "type": "string"
          },
          "firstName": {
            "maxLength": 100,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "identityStatus": {
            "$ref": "#/components/schemas/BorrowerIdentityStatus"
          },
          "lastName": {
            "maxLength": 100,
            "type": "string"
          },
          "linkedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "phone": {
            "maxLength": 20,
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "userId": {
            "description": "Set only after a verified claim-link to a MyItura user.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "BorrowerConsent": {
        "description": "What you observed when your borrower signed. Relaying an acceptance is not the same as observing one, so these are the borrower's details as your surface saw them, not your server's. Every field is required.",
        "properties": {
          "documentReference": {
            "description": "The `documentReference` from GET /v1/loans/{id}/offer-letter, naming the offer that was on the screen. If the offer has since been re-issued this call is refused with 409, and the borrower has to be shown the current one.",
            "example": "offer_2f1c8f0a-6b2e-4a55-9d3c-0f5a1b2c3d4e",
            "maxLength": 200,
            "type": "string"
          },
          "ipAddress": {
            "description": "The borrower's IP address, as your surface saw it.",
            "example": "102.89.23.14",
            "type": "string"
          },
          "signatureEmail": {
            "description": "The email the borrower signed with, if you collected one.",
            "format": "email",
            "maxLength": 150,
            "type": "string"
          },
          "signatureFullName": {
            "description": "The name the borrower typed, which is their signature.",
            "example": "Ada Obi",
            "maxLength": 200,
            "minLength": 2,
            "type": "string"
          },
          "signedAt": {
            "description": "When the borrower signed, at your clock.",
            "format": "date-time",
            "type": "string"
          },
          "userAgent": {
            "description": "The borrower's user agent, as your surface saw it.",
            "maxLength": 400,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "signatureFullName",
          "ipAddress",
          "userAgent",
          "signedAt",
          "documentReference"
        ],
        "type": "object"
      },
      "BorrowerIdentityStatus": {
        "description": "Whether the borrower has been claim-linked to a verified MyItura user.",
        "enum": [
          "unclaimed",
          "linked"
        ],
        "type": "string"
      },
      "CancelLoanRequest": {
        "properties": {
          "reason": {
            "description": "Why the loan is being called off. Recorded and echoed on the loan and the loan.cancelled event.",
            "maxLength": 500,
            "type": "string"
          }
        },
        "type": "object"
      },
      "CreateMandateRequest": {
        "description": "Sets up a direct-debit mandate for the loan's borrower.",
        "properties": {
          "accountNumber": {
            "maxLength": 20,
            "type": "string"
          },
          "bankCode": {
            "maxLength": 20,
            "type": "string"
          },
          "callbackUrl": {
            "description": "Where the borrower is redirected after authorising.",
            "format": "uri",
            "type": "string"
          },
          "email": {
            "description": "Borrower email used for the provider authorisation.",
            "format": "email",
            "type": "string"
          },
          "provider": {
            "description": "The rail. Omit for the default Paystack flow. Set `creditcheck` to register a mandate YOU operate: nothing is initialised with Paystack, the mandate goes straight to active as a status marker, and we never debit it.",
            "enum": [
              "paystack",
              "mono",
              "creditcheck"
            ],
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "type": "object"
      },
      "CreatePreapprovalRequest": {
        "description": "Push envelope. The decision (and optional enriched) payloads are your Cortex outputs verbatim. They are summarised into typed fields and retained as pushed, except that raw BVNs are scrubbed at rest. Amounts inside the payloads are naira; conversion to kobo happens on our side.",
        "example": {
          "borrower": {
            "email": "adaeze.okonkwo@example.com",
            "firstName": "Adaeze",
            "lastName": "Okonkwo",
            "phone": "+2348031234567"
          },
          "clientReference": "CRDCHK-2026-0001",
          "decision": {
            "approved_amount": 450000,
            "conditions": {
              "interest_rate": 5,
              "repayment_frequency": "monthly",
              "tenor_days": 90
            },
            "confidence": "high",
            "metadata": {
              "assessment_id": "cx_9f2a71c4e8",
              "bvn": "22200000001"
            },
            "recommendation": "approve",
            "risk_band": "B",
            "trust_score": 742
          },
          "providerId": "9f1c2b64-0f1a-4c3e-9b8a-2d5e7f0a1b2c"
        },
        "properties": {
          "borrower": {
            "properties": {
              "email": {
                "format": "email",
                "nullable": true,
                "type": "string"
              },
              "firstName": {
                "maxLength": 100,
                "type": "string"
              },
              "lastName": {
                "maxLength": 100,
                "type": "string"
              },
              "phone": {
                "maxLength": 20,
                "type": "string"
              }
            },
            "required": [
              "firstName",
              "lastName",
              "phone"
            ],
            "type": "object"
          },
          "clientReference": {
            "description": "Your reference for this push.",
            "maxLength": 255,
            "type": "string"
          },
          "decision": {
            "description": "Your Cortex decision payload, verbatim. Must carry metadata.assessment_id, metadata.bvn and decision.recommendation; decision.approved_amount and decision.conditions {interest_rate, tenor_days, repayment_frequency} are summarised when present.",
            "type": "object"
          },
          "enriched": {
            "description": "Your Cortex enriched payload, verbatim (optional).",
            "type": "object"
          },
          "providerId": {
            "description": "Optional healthcare provider id from GET /v1/providers (record-only).",
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "borrower",
          "decision"
        ],
        "type": "object"
      },
      "DeclineTermsRequest": {
        "properties": {
          "consent": {
            "$ref": "#/components/schemas/BorrowerConsent"
          },
          "reason": {
            "description": "Optional reason the borrower gave.",
            "maxLength": 500,
            "type": "string"
          }
        },
        "required": [
          "consent"
        ],
        "type": "object"
      },
      "ErrorResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/APIResponse"
          },
          {
            "description": "Error envelope: success=false, data omitted, error populated (e.g. NOT_FOUND, INVALID_ID, IDEMPOTENCY_KEY_CONFLICT).",
            "properties": {
              "error": {
                "type": "string"
              }
            },
            "type": "object"
          }
        ]
      },
      "InsuranceMode": {
        "description": "Loan-insurance behaviour for the product.",
        "enum": [
          "automatic",
          "manual",
          "off"
        ],
        "type": "string"
      },
      "InsurancePolicyStatus": {
        "enum": [
          "pending",
          "active",
          "failed"
        ],
        "type": "string"
      },
      "InsurancePremiumBearer": {
        "description": "Who pays the insurance premium.",
        "enum": [
          "borrower",
          "tenant"
        ],
        "type": "string"
      },
      "InterestModel": {
        "description": "Interest calculation method.",
        "enum": [
          "flat",
          "reducing_balance"
        ],
        "type": "string"
      },
      "IssueOfferRequest": {
        "properties": {
          "productId": {
            "description": "Loan product to issue against. Defaults to the tenant's configured preapprovalDefaultProductId. The product's approval mode must be partner_pushed.",
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "KYCAttestation": {
        "description": "A delegated-KYC (Tier A) tenant's assertion that it verified the borrower, plus MyItura's independent AML screen result and audit-sampling flag.",
        "properties": {
          "amlScreenDetail": {
            "nullable": true,
            "type": "string"
          },
          "amlScreenStatus": {
            "$ref": "#/components/schemas/AMLScreenStatus"
          },
          "amlScreenedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "attestedAt": {
            "format": "date-time",
            "type": "string"
          },
          "attestedByKey": {
            "description": "Masked public key of the attesting credential.",
            "type": "string"
          },
          "attestedChecks": {
            "additionalProperties": true,
            "description": "The attested checks payload, e.g. {\"bvn_verified\": true, \"id_type\": \"nin\", \"id_last4\": \"1234\", \"credit_check\": {...}}.",
            "type": "object"
          },
          "auditOutcome": {
            "description": "pending | pass | fail (set by a reviewer).",
            "nullable": true,
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "loanId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "sampledForAudit": {
            "type": "boolean"
          },
          "schemaVersion": {
            "type": "integer"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "KYCTier": {
        "description": "Who performs KYC: delegated (tenant attests, Tier A) or managed (MyItura runs KYC, Tier B).",
        "enum": [
          "delegated",
          "managed"
        ],
        "type": "string"
      },
      "Loan": {
        "description": "The partner-API loan of record. All amounts are in kobo; economics are frozen in the loan's pricing snapshot at approval.",
        "properties": {
          "activeMandateId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "amountPaidKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "amountRequestedKobo": {
            "description": "Requested amount in kobo.",
            "format": "int64",
            "type": "integer"
          },
          "applicationUrl": {
            "description": "Hosted borrower checkout URL, when applicable.",
            "nullable": true,
            "type": "string"
          },
          "approvalMode": {
            "$ref": "#/components/schemas/ApprovalMode"
          },
          "approvalNotes": {
            "nullable": true,
            "type": "string"
          },
          "approvedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "clientReference": {
            "description": "Tenant free-form reference, echoed in webhooks.",
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "example": "NGN",
            "type": "string"
          },
          "disbursedAmountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "disbursedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "disbursementReference": {
            "nullable": true,
            "type": "string"
          },
          "hasActiveMandate": {
            "type": "boolean"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "kycTier": {
            "$ref": "#/components/schemas/KYCTier"
          },
          "loanProductId": {
            "format": "uuid",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "description": "Tenant free-form metadata, echoed in webhooks.",
            "nullable": true,
            "type": "object"
          },
          "offerLetterIssuedAt": {
            "description": "When the offer letter PDF was last rendered and stored (re-rendered on acceptance to carry the signature block). Fetch the document via GET /v1/loans/{id}/offer-letter.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "outstandingKobo": {
            "description": "Total still owed (principal + cost of credit - paid).",
            "format": "int64",
            "type": "integer"
          },
          "pricingSnapshotId": {
            "description": "Immutable pricing snapshot reference; null until approval.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "principalBalanceKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "principalKobo": {
            "description": "Approved principal in kobo (== requested unless re-priced).",
            "format": "int64",
            "type": "integer"
          },
          "rejectionReason": {
            "nullable": true,
            "type": "string"
          },
          "settlementDestination": {
            "$ref": "#/components/schemas/SettlementDestination"
          },
          "status": {
            "$ref": "#/components/schemas/LoanStatus"
          },
          "tenorDays": {
            "type": "integer"
          },
          "termsAcceptedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanDecisionRequest": {
        "description": "Decision payload. `notes` applies to approvals; `reason` applies to rejections.",
        "properties": {
          "notes": {
            "description": "Optional approval notes (approve).",
            "nullable": true,
            "type": "string"
          },
          "reason": {
            "description": "Rejection reason (reject).",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanInsurancePolicy": {
        "description": "An insurance purchase for a loan. Automatic products insure at disbursement; manual products insure when the tenant triggers it.",
        "properties": {
          "commissionKobo": {
            "description": "The platform's share of the premium.",
            "format": "int64",
            "type": "integer"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "errorMessage": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "loanId": {
            "format": "uuid",
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "policyReference": {
            "nullable": true,
            "type": "string"
          },
          "premiumBearer": {
            "$ref": "#/components/schemas/InsurancePremiumBearer"
          },
          "premiumKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "provider": {
            "example": "mycover",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/InsurancePolicyStatus"
          },
          "triggeredBy": {
            "enum": [
              "automatic",
              "manual"
            ],
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanKYCResult": {
        "properties": {
          "documents": {
            "items": {
              "properties": {
                "status": {
                  "example": "verified",
                  "type": "string"
                },
                "type": {
                  "example": "bvn",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "loanStatus": {
            "description": "The loan's status after this submission.",
            "type": "string"
          },
          "outcome": {
            "description": "`verified` advances the loan to `kyc_completed`. `failed` means a provider refused the identity. `pending` means the provider has not answered yet; submit again or poll the loan.",
            "enum": [
              "verified",
              "failed",
              "pending"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanMandate": {
        "description": "A direct-debit mandate for a loan. The borrower authorises via authorizationUrl, after which the mandate becomes active and chargeable. Provider authorisation codes are never serialised.",
        "properties": {
          "accountNumber": {
            "nullable": true,
            "type": "string"
          },
          "activatedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "amountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "authorizationUrl": {
            "description": "Borrower authorisation URL (hosted by the provider).",
            "nullable": true,
            "type": "string"
          },
          "bankCode": {
            "nullable": true,
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "loanId": {
            "format": "uuid",
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "provider": {
            "$ref": "#/components/schemas/MandateProvider"
          },
          "reference": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/MandateStatus"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanProduct": {
        "description": "A tenant-defined lending product: KYC tier, approval mode, pricing, settlement destination and limits.",
        "properties": {
          "approvalMode": {
            "$ref": "#/components/schemas/ApprovalMode"
          },
          "capitalPoolCode": {
            "description": "Funding pool this product draws from.",
            "nullable": true,
            "type": "string"
          },
          "code": {
            "description": "Unique per organisation.",
            "maxLength": 50,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "example": "NGN",
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "description": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "insuranceMode": {
            "$ref": "#/components/schemas/InsuranceMode"
          },
          "insurancePremiumBearer": {
            "$ref": "#/components/schemas/InsurancePremiumBearer"
          },
          "insurancePremiumBps": {
            "description": "Insurance premium as basis points of principal.",
            "type": "integer"
          },
          "interestModel": {
            "$ref": "#/components/schemas/InterestModel"
          },
          "interestRateBps": {
            "description": "Annual nominal interest rate in basis points (pro-rated by tenor at pricing time).",
            "type": "integer"
          },
          "isActive": {
            "type": "boolean"
          },
          "kycTier": {
            "$ref": "#/components/schemas/KYCTier"
          },
          "lateFeeBps": {
            "type": "integer"
          },
          "maxAmountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "maxTenorDays": {
            "type": "integer"
          },
          "minAmountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "minTenorDays": {
            "type": "integer"
          },
          "name": {
            "maxLength": 150,
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "processingFeeBps": {
            "description": "Processing fee as basis points of principal.",
            "type": "integer"
          },
          "processingFeeFlatKobo": {
            "description": "Fixed processing fee in kobo.",
            "format": "int64",
            "type": "integer"
          },
          "recoveryEnabled": {
            "type": "boolean"
          },
          "recoveryPolicyId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "settlementCatalogEnabled": {
            "description": "Merchant/service catalog step (only for merchant_wallet).",
            "type": "boolean"
          },
          "settlementDestination": {
            "$ref": "#/components/schemas/SettlementDestination"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanRepayment": {
        "description": "A repayment collected against a loan and its waterfall allocation (fee -\u003e interest -\u003e principal).",
        "properties": {
          "amountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "completedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "externalReference": {
            "description": "Tenant's off-platform collection reference (method=external).",
            "nullable": true,
            "type": "string"
          },
          "feePortionKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "interestPortionKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "ledgerTransactionRef": {
            "nullable": true,
            "type": "string"
          },
          "loanId": {
            "format": "uuid",
            "type": "string"
          },
          "method": {
            "$ref": "#/components/schemas/RepaymentMethod"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "principalPortionKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "reference": {
            "description": "System-generated unique repayment reference.",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/RepaymentStatus"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanRepaymentScheduleItem": {
        "description": "One instalment of the loan's amortisation schedule. The principal/interest/fee split is fixed at schedule-generation time.",
        "properties": {
          "amountPaidKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "dueDate": {
            "format": "date-time",
            "type": "string"
          },
          "feeKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "installmentNumber": {
            "type": "integer"
          },
          "interestKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "loanId": {
            "format": "uuid",
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "paidAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "principalKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/ScheduleStatus"
          },
          "totalKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LoanStatus": {
        "description": "Loan lifecycle state. `cancelled` is a pre-disbursement call-off by either side; cancelledBy on the loan says which.",
        "enum": [
          "pending",
          "kyc_required",
          "kyc_pending",
          "kyc_completed",
          "attested",
          "under_review",
          "approved",
          "rejected",
          "awaiting_acceptance",
          "terms_accepted",
          "terms_declined",
          "disbursed",
          "active",
          "completed",
          "defaulted",
          "cancelled"
        ],
        "type": "string"
      },
      "MandateProvider": {
        "description": "The auto-debit rail. `paystack` (live) and `mono` are charged BY MyItura. `creditcheck` is PARTNER-OPERATED: you hold the mandate and debit on your own side, we never hold an authorisation for it and never charge it, so it is a status marker only. Record what you collect with `method: \"external\"`.",
        "enum": [
          "paystack",
          "mono",
          "creditcheck"
        ],
        "type": "string"
      },
      "MandateStatus": {
        "enum": [
          "initiated",
          "pending",
          "active",
          "failed",
          "cancelled",
          "expired"
        ],
        "type": "string"
      },
      "OfferLetterLink": {
        "description": "A short-lived signed link to a loan's offer letter PDF. The object itself is private; fetch it promptly and re-request a link rather than caching the URL.",
        "properties": {
          "documentReference": {
            "description": "Identifies the offer in this letter. Send it back on accept-terms or decline-terms so the acceptance names what was accepted.",
            "example": "offer_2f1c8f0a-6b2e-4a55-9d3c-0f5a1b2c3d4e",
            "type": "string"
          },
          "expiresAt": {
            "format": "date-time",
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "type": "object"
      },
      "PayoutRequest": {
        "description": "A manual borrower-bank payout: raised against the borrower's ledger balance, settled off-platform by the tenant/admin.",
        "properties": {
          "accountName": {
            "type": "string"
          },
          "accountNumber": {
            "type": "string"
          },
          "amountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "bankCode": {
            "type": "string"
          },
          "bankName": {
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "example": "NGN",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "ledgerTransactionRef": {
            "nullable": true,
            "type": "string"
          },
          "loanId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "rejectionReason": {
            "nullable": true,
            "type": "string"
          },
          "settledAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "settledByUserId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "settlementReference": {
            "nullable": true,
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/PayoutStatus"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "PayoutStatus": {
        "enum": [
          "requested",
          "settling",
          "completed",
          "rejected"
        ],
        "type": "string"
      },
      "Preapproval": {
        "description": "Org-scoped record of a partner-pushed credit decision. Every push is recorded, declines included. Amounts are converted to kobo and rates to basis points at ingest; the raw BVN is never stored or returned (keyed hash only).",
        "properties": {
          "approvedAmountKobo": {
            "description": "decision.approved_amount (naira) converted to kobo at ingest.",
            "format": "int64",
            "type": "integer"
          },
          "assessmentId": {
            "description": "Your assessment identifier (decision metadata.assessment_id). It is the idempotency key: replaying the same assessment returns the existing record.",
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "clientReference": {
            "nullable": true,
            "type": "string"
          },
          "confidence": {
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "expiresAt": {
            "description": "When the unconsumed pre-approval lapses (tenant-configured; not set on declines).",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "interestRateBps": {
            "description": "decision.conditions.interest_rate (percent) converted to basis points.",
            "nullable": true,
            "type": "integer"
          },
          "loanId": {
            "description": "Set once the pre-approval is carried into a loan.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "providerOrgId": {
            "description": "Healthcare provider referenced in the push (record-only).",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "recommendation": {
            "description": "decision.recommendation as pushed (lower-cased), e.g. approve | decline.",
            "type": "string"
          },
          "repaymentFrequency": {
            "nullable": true,
            "type": "string"
          },
          "riskBand": {
            "nullable": true,
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/PreapprovalStatus"
          },
          "tenorDays": {
            "nullable": true,
            "type": "integer"
          },
          "trustScore": {
            "nullable": true,
            "type": "integer"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "PreapprovalAck": {
        "description": "Push acknowledgement (also returned on idempotent replays).",
        "properties": {
          "approvedAmountKobo": {
            "format": "int64",
            "type": "integer"
          },
          "assessmentId": {
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "expiresAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "preapprovalId": {
            "format": "uuid",
            "type": "string"
          },
          "recommendation": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/PreapprovalStatus"
          }
        },
        "type": "object"
      },
      "PreapprovalFunnel": {
        "description": "Your pre-approval conversion and money reconciliation. Counts only loans that came from your pushed decisions. Nothing from any other program is mixed in. All amounts are kobo.",
        "properties": {
          "acceptedByBorrower": {
            "type": "integer"
          },
          "approvedAmountKobo": {
            "description": "Total credit pushed as approved.",
            "format": "int64",
            "type": "integer"
          },
          "awaitingOffer": {
            "description": "Approved and stored, offer not yet issued.",
            "type": "integer"
          },
          "declinedByBorrower": {
            "description": "Borrower turned the issued offer down.",
            "type": "integer"
          },
          "declinedByPartner": {
            "description": "Pushed as a decline; never became a loan.",
            "type": "integer"
          },
          "disbursed": {
            "type": "integer"
          },
          "disbursedAmountKobo": {
            "description": "Total principal actually released.",
            "format": "int64",
            "type": "integer"
          },
          "expired": {
            "description": "Lapsed before being taken up.",
            "type": "integer"
          },
          "offerIssued": {
            "description": "Offer letter out, awaiting the borrower.",
            "type": "integer"
          },
          "outstandingKobo": {
            "description": "Still owed on those loans.",
            "format": "int64",
            "type": "integer"
          },
          "pushed": {
            "description": "Every decision received, declines included.",
            "type": "integer"
          },
          "repaidAmountKobo": {
            "description": "Total collected against those loans.",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PreapprovalStatus": {
        "description": "Lifecycle of a pushed pre-approval: received → offer_issued → accepted | declined | expired → disbursed. A pushed decline lands directly as declined and never becomes a loan.",
        "enum": [
          "received",
          "offer_issued",
          "accepted",
          "declined",
          "expired",
          "disbursed"
        ],
        "type": "string"
      },
      "ProviderDirectoryItem": {
        "description": "A MyItura healthcare provider (public directory contract: active, patient-serving providers only, no permissions, contact or configuration).",
        "properties": {
          "address": {
            "nullable": true,
            "type": "string"
          },
          "city": {
            "nullable": true,
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "country": {
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "description": "Use as providerId in pre-approval pushes.",
            "format": "uuid",
            "type": "string"
          },
          "isActive": {
            "type": "boolean"
          },
          "localGovernment": {
            "nullable": true,
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "organisationLogoUrl": {
            "description": "Short-lived signed URL.",
            "nullable": true,
            "type": "string"
          },
          "organisationType": {
            "type": "string"
          },
          "providerType": {
            "enum": [
              "laboratory",
              "pharmacy",
              "laboratory_pharmacy"
            ],
            "type": "string"
          },
          "receivesDrugs": {
            "type": "boolean"
          },
          "receivesTests": {
            "type": "boolean"
          },
          "slug": {
            "type": "string"
          },
          "state": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "RecordRepaymentRequest": {
        "description": "Collects a repayment: `wallet` debits the borrower's ledger balance, `mandate` charges the active direct-debit mandate, `external` records an off-platform collection.",
        "properties": {
          "amountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "exclusiveMinimum": true,
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "externalReference": {
            "description": "Your collection reference (method=external).",
            "maxLength": 160,
            "nullable": true,
            "type": "string"
          },
          "method": {
            "$ref": "#/components/schemas/RepaymentMethod"
          }
        },
        "required": [
          "method",
          "amountKobo"
        ],
        "type": "object"
      },
      "RegisterWebhookEndpointRequest": {
        "description": "Registers a webhook destination. The per-endpoint signing secret is returned once in the response and never again.",
        "properties": {
          "description": {
            "maxLength": 255,
            "nullable": true,
            "type": "string"
          },
          "events": {
            "description": "Event names to subscribe to; omit or send empty for all events.",
            "example": [
              "loan.approved",
              "loan.disbursed",
              "repayment.completed"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "mode": {
            "default": "live",
            "enum": [
              "live",
              "test"
            ],
            "type": "string"
          },
          "url": {
            "format": "uri",
            "maxLength": 512,
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "RegisterWebhookEndpointResponseData": {
        "description": "The registered endpoint plus its signing secret, which is shown exactly once. Store it securely.",
        "properties": {
          "endpoint": {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          "signingSecret": {
            "description": "The whsec_ HMAC-SHA256 signing secret for this endpoint. Returned only in this response.",
            "example": "whsec_...",
            "type": "string"
          }
        },
        "type": "object"
      },
      "RepaymentMethod": {
        "description": "How the repayment's funds were collected.\n- `external`: you collected on your own rail and are recording it (idempotent on `externalReference`). This is the default for partner-run direct debit.\n- `cash_wallet`: debit the borrower's OWN MyItura cash wallet, which is what their bank transfer pays into. Requires a claimed MyItura account with sufficient balance.\n- `wallet`: sweep the borrower's UNDRAWN credit back to your pool, not a collection from the borrower.\n- `mandate`: charge a MyItura-operated Paystack mandate. Not available for partner-operated rails.",
        "enum": [
          "wallet",
          "mandate",
          "external",
          "cash_wallet"
        ],
        "type": "string"
      },
      "RepaymentStatus": {
        "enum": [
          "pending",
          "completed",
          "failed"
        ],
        "type": "string"
      },
      "RequestPayoutRequest": {
        "description": "Raises a manual bank payout against the borrower's ledger balance (borrower_bank_account settlement).",
        "properties": {
          "accountName": {
            "maxLength": 150,
            "type": "string"
          },
          "accountNumber": {
            "maxLength": 20,
            "type": "string"
          },
          "amountKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "exclusiveMinimum": true,
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "bankCode": {
            "maxLength": 20,
            "type": "string"
          },
          "bankName": {
            "maxLength": 120,
            "type": "string"
          },
          "borrowerId": {
            "format": "uuid",
            "type": "string"
          },
          "loanId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "borrowerId",
          "amountKobo",
          "bankName",
          "bankCode",
          "accountNumber"
        ],
        "type": "object"
      },
      "ScheduleStatus": {
        "description": "State of one repayment instalment.",
        "enum": [
          "pending",
          "paid",
          "partial",
          "overdue",
          "waived"
        ],
        "type": "string"
      },
      "SettlementDestination": {
        "description": "Where disbursed funds go.",
        "enum": [
          "borrower_wallet",
          "borrower_bank_account",
          "merchant_wallet",
          "tenant_wallet"
        ],
        "type": "string"
      },
      "SettlementLine": {
        "description": "Per-loan breakdown line of a settlement statement.",
        "properties": {
          "feeKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "interestKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "loanId": {
            "format": "uuid",
            "type": "string"
          },
          "repayments": {
            "description": "Number of repayments contributing in the period.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "SettlementStatement": {
        "description": "One payable sweep of tenant revenue (fees + interest) to the org wallet, with the per-loan lines that made it up.",
        "properties": {
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "failureReason": {
            "nullable": true,
            "type": "string"
          },
          "feeSweptKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "interestSweptKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/SettlementLine"
            },
            "nullable": true,
            "type": "array"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "periodEnd": {
            "format": "date-time",
            "type": "string"
          },
          "periodStart": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/SettlementStatementStatus"
          },
          "totalSweptKobo": {
            "description": "Amount in kobo (NGN minor unit).",
            "format": "int64",
            "type": "integer"
          },
          "transferReference": {
            "nullable": true,
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SettlementStatementStatus": {
        "enum": [
          "completed",
          "skipped",
          "failed"
        ],
        "type": "string"
      },
      "SubmitAttestationRequest": {
        "description": "A Tier A (delegated-KYC) tenant's attestation that it verified the borrower. MyItura still runs its own AML screen and retains audit rights.",
        "properties": {
          "attestedChecks": {
            "additionalProperties": true,
            "description": "The checks performed, e.g. {\"bvn_verified\": true, \"id_type\": \"nin\", \"id_last4\": \"1234\", \"credit_check\": {...}}.",
            "type": "object"
          },
          "schemaVersion": {
            "default": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "SubmitLoanKYCRequest": {
        "description": "The borrower's identity, collected by you. The same fields the hosted checkout asks the borrower for, because it is the same verification: we run it either way.",
        "properties": {
          "address": {
            "example": "12 Marina Road, Lagos",
            "maxLength": 255,
            "type": "string"
          },
          "bvn": {
            "description": "Bank Verification Number, exactly 11 digits. Required: it is what ties the borrower to bureau data, so a NIN does not substitute for it.",
            "example": "22200000001",
            "maxLength": 11,
            "minLength": 11,
            "type": "string"
          },
          "dateOfBirth": {
            "description": "The borrower's date of birth, passed to the provider as part of the check.",
            "example": "1990-01-31",
            "maxLength": 20,
            "type": "string"
          },
          "nin": {
            "description": "National Identification Number, if the borrower has one. Length-ranged rather than pinned at 11 because a NIN may carry a suffix.",
            "example": "12345678901",
            "maxLength": 15,
            "minLength": 11,
            "type": "string"
          }
        },
        "required": [
          "bvn"
        ],
        "type": "object"
      },
      "WebhookDelivery": {
        "description": "One row of the durable webhook delivery log (the /v1/events feed). The signed envelope {event, timestamp, data} is rebuilt at send time.",
        "properties": {
          "attemptCount": {
            "type": "integer"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "deliveredAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "endpointId": {
            "description": "The registered endpoint this delivery targets.",
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "event": {
            "example": "loan.approved",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "lastError": {
            "nullable": true,
            "type": "string"
          },
          "maxAttempts": {
            "type": "integer"
          },
          "nextAttemptAt": {
            "format": "date-time",
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "payload": {
            "additionalProperties": true,
            "description": "The event's data object.",
            "type": "object"
          },
          "responseStatus": {
            "nullable": true,
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookDeliveryStatus"
          },
          "targetUrl": {
            "format": "uri",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "WebhookDeliveryStatus": {
        "enum": [
          "pending",
          "delivering",
          "succeeded",
          "failed",
          "dead"
        ],
        "type": "string"
      },
      "WebhookEndpoint": {
        "description": "A registered webhook destination. The signing secret is returned once on creation and never serialised again.",
        "properties": {
          "consecutiveFails": {
            "type": "integer"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "nullable": true,
            "type": "string"
          },
          "events": {
            "description": "Subscribed event names; empty/null = all events.",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "lastFailureAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "lastSuccessAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "mode": {
            "enum": [
              "live",
              "test"
            ],
            "type": "string"
          },
          "organisationId": {
            "format": "uuid",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookEndpointStatus"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "url": {
            "format": "uri",
            "maxLength": 512,
            "type": "string"
          }
        },
        "type": "object"
      },
      "WebhookEndpointStatus": {
        "enum": [
          "active",
          "disabled"
        ],
        "type": "string"
      }
    },
    "securitySchemes": {
      "PublicKeyAuth": {
        "description": "Your organisation's public API key. Must be paired with SecretKeyAuth (X-API-Secret-Key). Alternatively send a single header `Authorization: ApiKey \u003cpublicKey\u003e:\u003csecretKey\u003e` instead of the pair.",
        "in": "header",
        "name": "X-API-Public-Key",
        "type": "apiKey"
      },
      "SecretKeyAuth": {
        "description": "Your organisation's secret API key. Must be paired with PublicKeyAuth (X-API-Public-Key). Alternatively send a single header `Authorization: ApiKey \u003cpublicKey\u003e:\u003csecretKey\u003e` instead of the pair.",
        "in": "header",
        "name": "X-API-Secret-Key",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "name": "MyItura API support",
      "url": "https://myitura.com/api-docs/lending"
    },
    "description": "The machine-to-machine API a lending partner calls with an API key pair. This file describes exactly the operations documented at https://myitura.com/api-docs/lending and nothing else. Products are defined and the capital pool is funded on the organisation dashboard, not over this API.",
    "title": "MyItura Lending Partner API",
    "version": "1.0.0",
    "x-logo": {
      "altText": "MyItura",
      "backgroundColor": "#FFFFFF",
      "url": "https://myitura.com/images/my-itura-logo.svg"
    }
  },
  "openapi": "3.0.3",
  "paths": {
    "/v1/borrowers/{id}": {
      "get": {
        "operationId": "getBorrower",
        "parameters": [
          {
            "description": "Borrower id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Borrower"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Borrower retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a borrower",
        "tags": [
          "Borrowers"
        ]
      }
    },
    "/v1/events": {
      "get": {
        "description": "Your organisation's recent webhook delivery log, newest first.",
        "operationId": "listEvents",
        "parameters": [
          {
            "description": "Maximum rows to return.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/WebhookDelivery"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Events retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List webhook deliveries",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/v1/events/{id}/redeliver": {
      "post": {
        "description": "Requeues a delivery for another attempt (e.g. after fixing your receiver).",
        "operationId": "redeliverEvent",
        "parameters": [
          {
            "description": "Webhook delivery id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "description": "No payload.",
                          "nullable": true
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Event requeued for delivery."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Redeliver a webhook event",
        "tags": [
          "Webhooks"
        ]
      }
    },
    "/v1/loans": {
      "get": {
        "operationId": "listLoans",
        "parameters": [
          {
            "description": "Filter by loan status.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "pending",
                "kyc_required",
                "kyc_pending",
                "kyc_completed",
                "attested",
                "under_review",
                "approved",
                "rejected",
                "awaiting_acceptance",
                "terms_accepted",
                "terms_declined",
                "disbursed",
                "active",
                "completed",
                "defaulted",
                "cancelled"
              ],
              "type": "string"
            }
          },
          {
            "description": "Maximum rows to return.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/Loan"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Loans retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List loans",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}": {
      "get": {
        "operationId": "getLoan",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Loan retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a loan",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/accept-terms": {
      "post": {
        "description": "Records the borrower's acceptance of the offered terms; the loan becomes ready to disburse. The consent object is required: it is the evidence that this borrower agreed to this offer, so it carries what you observed when they signed and the `documentReference` of the offer they were shown.",
        "operationId": "acceptLoanTerms",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcceptTermsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Accept the loan terms succeeded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state transition or business-rule failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The `documentReference` does not name the offer currently on this loan. Fetch it again and have the borrower re-confirm."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The consent is missing or incomplete."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Accept the loan terms",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/approve": {
      "post": {
        "description": "Approves the loan (tenant approval mode). Freezes the immutable pricing snapshot and moves the loan to awaiting_acceptance.",
        "operationId": "approveLoan",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoanDecisionRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Approve a loan succeeded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state transition or business-rule failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Approve a loan",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/attestation": {
      "post": {
        "description": "Records a delegated-KYC (Tier A) attestation for the loan's borrower and triggers MyItura's independent AML screen.",
        "operationId": "submitLoanAttestation",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitAttestationRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/KYCAttestation"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Attestation recorded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state transition or business-rule failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Submit a KYC attestation",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/cancel": {
      "post": {
        "description": "Call a loan off before any money has moved. Allowed from creation right up to disbursement, offer or no offer, and refused once disbursed: past that point the loan can only complete, default or go to recovery. Idempotent. The borrower's equivalent is the hosted checkout. Emits loan.cancelled carrying cancelledBy.",
        "operationId": "cancelLoan",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelLoanRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "Loan cancelled."
          },
          "400": {
            "description": "Already disbursed, or otherwise not cancellable."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Cancel a loan",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/decline-terms": {
      "post": {
        "description": "Records your borrower declining an issued offer (`awaiting_acceptance` → `terms_declined`, terminal) and emits `loan.offer.declined`. Idempotent. A declined loan cannot be revived. Push a fresh decision instead. The same consent object as acceptance is required: walking away from an offer is a decision the borrower made, and the record has to say who made it and against which document.",
        "operationId": "declineTerms",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclineTermsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Terms declined."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The loan is not in a state where terms can be declined."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The `documentReference` does not name the offer currently on this loan. Fetch it again and have the borrower re-confirm."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The consent is missing or incomplete."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Decline the offer",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/disburse": {
      "post": {
        "description": "Releases funds from your capital pool to the product's settlement destination and generates the repayment schedule.",
        "operationId": "disburseLoan",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Disburse a loan succeeded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state transition or business-rule failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Disburse a loan",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/insurance": {
      "get": {
        "operationId": "getLoanInsurance",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanInsurancePolicy"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Insurance policy retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get the loan's insurance policy",
        "tags": [
          "Insurance"
        ]
      }
    },
    "/v1/loans/{id}/kyc": {
      "post": {
        "description": "Managed-tier identity, collected by you and verified by us. This is the tenant-driven equivalent of the identity step in the hosted checkout: the same providers, the same encrypted retention, the same transition from `kyc_required` to `kyc_completed`. Use it when you drive your own interface rather than sending the borrower to the hosted page.\\n\\nOnly managed-tier loans reach it. On a delegated-tier loan you attest identity yourself, so a submission here is refused with 400 and you should post to /v1/loans/{id}/attestation instead.\\n\\nA provider refusing the identity is a 200 with `outcome: failed`, not an error: the loan's state is the answer either way.",
        "operationId": "submitLoanKYC",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitLoanKYCRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanKYCResult"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Identity submitted."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The loan is delegated tier, or the submission could never be verified."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Validation failed."
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Submit the borrower's identity",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/mandates": {
      "post": {
        "description": "Initiates a direct-debit mandate for the loan's borrower. The borrower authorises via the returned authorizationUrl.",
        "operationId": "createLoanMandate",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMandateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanMandate"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Mandate created."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state or provider failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Create a direct-debit mandate",
        "tags": [
          "Mandates"
        ]
      }
    },
    "/v1/loans/{id}/offer-letter": {
      "get": {
        "description": "Mints a fresh short-lived signed link to the loan's offer letter PDF (rendered at approval, re-rendered with the signature block once accepted). The document is stored privately and is never public, so links expire. Request a new one rather than caching.",
        "operationId": "getOfferLetter",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/OfferLetterLink"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "A signed link to the PDF."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The loan has not been approved, so no offer letter exists."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a link to the offer letter PDF",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/reject": {
      "post": {
        "description": "Rejects the loan (terminal).",
        "operationId": "rejectLoan",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoanDecisionRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Reject a loan succeeded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state transition or business-rule failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Reject a loan",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/loans/{id}/repayments": {
      "get": {
        "operationId": "listLoanRepayments",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/LoanRepayment"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Repayments retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List the loan's repayments",
        "tags": [
          "Repayments"
        ]
      },
      "post": {
        "description": "Collects a repayment via wallet, mandate charge, or records an external (off-platform) collection. The amount is allocated fee -\u003e interest -\u003e principal.",
        "operationId": "recordLoanRepayment",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecordRepaymentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanRepayment"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Repayment recorded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid state, insufficient balance, or collection failure."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Record a repayment",
        "tags": [
          "Repayments"
        ]
      }
    },
    "/v1/loans/{id}/schedule": {
      "get": {
        "operationId": "getLoanSchedule",
        "parameters": [
          {
            "description": "Loan id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/LoanRepaymentScheduleItem"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Schedule retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get the loan's repayment schedule",
        "tags": [
          "Loans"
        ]
      }
    },
    "/v1/mandates/{id}": {
      "get": {
        "operationId": "getLoanMandate",
        "parameters": [
          {
            "description": "Mandate id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanMandate"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Mandate retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a mandate",
        "tags": [
          "Mandates"
        ]
      }
    },
    "/v1/mandates/{id}/activate": {
      "post": {
        "description": "Verifies the borrower's authorisation with the provider and activates the mandate. Supplying authorizationCode uses the sandbox/test path.",
        "operationId": "activateLoanMandate",
        "parameters": [
          {
            "description": "Mandate id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanMandate"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Mandate activated."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Authorisation not yet completed or provider verification failed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Activate a mandate",
        "tags": [
          "Mandates"
        ]
      }
    },
    "/v1/payouts": {
      "get": {
        "operationId": "listPayouts",
        "parameters": [
          {
            "description": "Filter by payout status.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "requested",
                "settling",
                "completed",
                "rejected"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/PayoutRequest"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Payouts retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List payout requests",
        "tags": [
          "Payouts"
        ]
      },
      "post": {
        "description": "Raises a manual bank payout against the borrower's ledger balance. Settlement happens off-platform; mark it settled (or rejected) afterwards.",
        "operationId": "requestPayout",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestPayoutRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PayoutRequest"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Payout requested."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Insufficient borrower balance or invalid request."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Request a payout",
        "tags": [
          "Payouts"
        ]
      }
    },
    "/v1/payouts/{id}": {
      "get": {
        "operationId": "getPayout",
        "parameters": [
          {
            "description": "Payout request id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PayoutRequest"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Payout retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a payout request",
        "tags": [
          "Payouts"
        ]
      }
    },
    "/v1/preapprovals": {
      "get": {
        "operationId": "listPreapprovals",
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "schema": {
              "$ref": "#/components/schemas/PreapprovalStatus"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 50,
              "maximum": 200,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "properties": {
                            "preapprovals": {
                              "items": {
                                "$ref": "#/components/schemas/Preapproval"
                              },
                              "type": "array"
                            }
                          },
                          "type": "object"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Your organisation's pre-approvals, newest first."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List pre-approvals",
        "tags": [
          "Pre-Approvals"
        ]
      },
      "post": {
        "description": "Records a Cortex credit decision (approvals AND declines) against your tenant. Requires the Pre-Approved Lending permission and the tenant-config preapproval switch. Idempotent on the decision's metadata.assessment_id: a replay returns the existing record (200) instead of creating a new one (202). Emits the `preapproval.received` webhook on first ingest.",
        "operationId": "createPreapproval",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePreapprovalRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PreapprovalAck"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Idempotent replay, this assessment was already recorded."
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PreapprovalAck"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Pre-approval received and recorded."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid body."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Push a pre-approved credit decision",
        "tags": [
          "Pre-Approvals"
        ]
      }
    },
    "/v1/preapprovals/funnel": {
      "get": {
        "description": "Your whole program in one call: what you pushed, what converted, and what the money is doing. Per-loan detail stays on `GET /v1/loans`; your capital position is on `GET /v1/pools/balance`.",
        "operationId": "getPreapprovalFunnel",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PreapprovalFunnel"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "The funnel."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Pre-approval funnel + reconciliation",
        "tags": [
          "Pre-Approvals"
        ]
      }
    },
    "/v1/preapprovals/{id}": {
      "get": {
        "operationId": "getPreapproval",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Preapproval"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "The pre-approval."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a pre-approval",
        "tags": [
          "Pre-Approvals"
        ]
      }
    },
    "/v1/preapprovals/{id}/issue-offer": {
      "post": {
        "description": "Creates the loan for a stored pre-approval and issues its offer letter, moving the pre-approval to `offer_issued` and emitting `loan.offer.issued` with a signed link to the PDF. Idempotent: if the pre-approval already has a loan, that loan is returned.\n\nThe pushed decision's `approved_amount`, `conditions.interest_rate` and `conditions.tenor_days` become the loan's frozen economics (still validated against your tenant caps), and the pushed evidence is recorded as the Tier A KYC attestation. MyItura's own AML screen still gates approval, so a screen hit leaves the loan under review and issues no offer.\n\nTenants with `preapprovalAutoIssueOffer` enabled do not need this call: a valid pushed approval issues its offer automatically.",
        "operationId": "issuePreapprovalOffer",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueOfferRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/Loan"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "The loan, with its offer issued."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The pre-approval cannot be carried into an offer (a decline, expired, already consumed, missing tenor, no product, or an AML hit)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Issue the offer for a pre-approval",
        "tags": [
          "Pre-Approvals"
        ]
      }
    },
    "/v1/products": {
      "get": {
        "operationId": "listProducts",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/LoanProduct"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Products retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List loan products",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/products/{id}": {
      "get": {
        "operationId": "getProduct",
        "parameters": [
          {
            "description": "Loan product id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanProduct"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Product retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a loan product",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/providers": {
      "get": {
        "description": "Paginated read-only directory of active MyItura healthcare providers (laboratories and pharmacies), serving exactly the public directory contract. Use a provider's id as providerId when pushing pre-approvals.",
        "operationId": "listProviders",
        "parameters": [
          {
            "description": "Narrow to laboratories (only true is honoured).",
            "in": "query",
            "name": "receiveTest",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Narrow to pharmacies (only true is honoured).",
            "in": "query",
            "name": "receiveDrug",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Filter by provider name (partial match).",
            "in": "query",
            "name": "name",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by state, LGA, city or address (partial match).",
            "in": "query",
            "name": "location",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "schema": {
              "default": "name",
              "enum": [
                "name",
                "code",
                "created_at",
                "updated_at"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_order",
            "schema": {
              "default": "asc",
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "properties": {
                            "pagination": {
                              "type": "object"
                            },
                            "providers": {
                              "items": {
                                "$ref": "#/components/schemas/ProviderDirectoryItem"
                              },
                              "type": "array"
                            }
                          },
                          "type": "object"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "The provider directory page."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List healthcare providers",
        "tags": [
          "Providers"
        ]
      }
    },
    "/v1/settlements": {
      "get": {
        "operationId": "listSettlements",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/SettlementStatement"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Settlement statements retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List settlement statements",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/v1/settlements/{id}": {
      "get": {
        "operationId": "getSettlement",
        "parameters": [
          {
            "description": "Settlement statement id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SettlementStatement"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Settlement statement retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get a settlement statement",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/v1/settlements/{id}/csv": {
      "get": {
        "operationId": "downloadSettlementCSV",
        "parameters": [
          {
            "description": "Settlement statement id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "The statement's per-loan lines as a CSV attachment."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Download a settlement statement as CSV",
        "tags": [
          "Settlements"
        ]
      }
    },
    "/v1/test/mandates/{id}/simulate-activation": {
      "post": {
        "description": "Test-mode helper that marks a mandate active without a real provider authorisation. Refused (403) for live-mode keys.",
        "operationId": "simulateMandateActivation",
        "parameters": [
          {
            "description": "Mandate id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/LoanMandate"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Mandate activated (simulated)."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Mandate is not in a simulatable state."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Simulate mandate activation (sandbox only)",
        "tags": [
          "Sandbox"
        ]
      }
    },
    "/v1/usage": {
      "get": {
        "description": "Your organisation's daily API-usage rollup (the metering/billing feed).",
        "operationId": "getAPIUsage",
        "parameters": [
          {
            "description": "How many days back to include.",
            "in": "query",
            "name": "days",
            "required": false,
            "schema": {
              "default": 30,
              "maximum": 90,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/APIUsageDailyRollup"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Usage retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Get your API usage rollup",
        "tags": [
          "Usage"
        ]
      }
    },
    "/v1/webhook-endpoints": {
      "get": {
        "description": "Signing secrets are never included; they are shown once at registration only.",
        "operationId": "listWebhookEndpoints",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "items": {
                            "$ref": "#/components/schemas/WebhookEndpoint"
                          },
                          "type": "array"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Endpoints retrieved."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "List webhook endpoints",
        "tags": [
          "Webhooks"
        ]
      },
      "post": {
        "description": "Registers a delivery destination. The response contains the endpoint's HMAC-SHA256 signing secret exactly once. Store it securely, because it cannot be retrieved again.",
        "operationId": "registerWebhookEndpoint",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterWebhookEndpointRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/APIResponse"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/RegisterWebhookEndpointResponseData"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Webhook endpoint registered; signingSecret shown once."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid endpoint definition."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "summary": "Register a webhook endpoint",
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "security": [
    {
      "PublicKeyAuth": [],
      "SecretKeyAuth": []
    }
  ],
  "servers": [
    {
      "description": "Production. Sandbox is the same host with test-mode keys.",
      "url": "https://api.myitura.com"
    },
    {
      "description": "Production alias. Same service, kept for integrations built before api.myitura.com.",
      "url": "https://loansapi.myitura.com"
    }
  ],
  "tags": [
    {
      "description": "Tenant-defined loan products.",
      "name": "Products"
    },
    {
      "description": "Org-scoped borrower identities.",
      "name": "Borrowers"
    },
    {
      "description": "Partner-pushed credit decisions (requires the Pre-Approved Lending permission on top of Loan Tenant). Status lifecycle: received → offer_issued → accepted | declined | expired → disbursed.",
      "name": "Pre-Approvals"
    },
    {
      "description": "Read-only directory of MyItura healthcare providers (laboratories/pharmacies), for referencing provider ids in pre-approval pushes.",
      "name": "Providers"
    },
    {
      "description": "Loan origination and lifecycle.",
      "name": "Loans"
    },
    {
      "description": "Direct-debit mandates for auto-collection.",
      "name": "Mandates"
    },
    {
      "description": "Repayment collection and history.",
      "name": "Repayments"
    },
    {
      "description": "Loan insurance policies (manual-mode products).",
      "name": "Insurance"
    },
    {
      "description": "Manual borrower-bank payouts.",
      "name": "Payouts"
    },
    {
      "description": "Revenue settlement statements.",
      "name": "Settlements"
    },
    {
      "description": "API usage metering rollups.",
      "name": "Usage"
    },
    {
      "description": "Webhook endpoints and the delivery event log.",
      "name": "Webhooks"
    },
    {
      "description": "Test-mode-only helpers; refused for live keys.",
      "name": "Sandbox"
    }
  ]
}