Submit Loan Agreements to Kenal Stamps for stamping using the General Contract schema. This endpoint handles contract creation, PDF upload, and optional immediate confirmation (wallet charging).

For the full request/response schema, see the API Reference.

Endpoint

POST /api/integration/loan/submit

Request Body

Field	Type	Required	Description
`externalReferenceId`	string	Yes	Your unique identifier for this contract
`loanAmount`	number	Yes	Total loan amount in RM
`duration`	number	Yes	Loan duration value
`durationUnit`	`MONTHS` \| `YEARS`	Yes	Duration unit
`confirm`	boolean	No	If `true`, charges the wallet immediately
`useServiceCreditFallback`	boolean	No	Fall back to service credits if duty wallet is insufficient
`originalFileName`	string	Yes	PDF filename
`fileBase64`	string	Yes	Base64-encoded PDF (max 20MB)
`contentType`	string	Yes	Must be `application/pdf`
`data`	object	Yes	General Contract data (see below)

Contract Data (`data`)

Field	Type	Required	Description
`title`	string	Yes	Contract title
`contractDate`	string	No	`YYYY-MM-DD`. Required if `confirm=true`
`parties`	array	Yes	Minimum 2 party objects
`effectiveDate`	string	No	`YYYY-MM-DD`
`expirationDate`	string	No	`YYYY-MM-DD`
`numberOfDuplicates`	number	No	Default: 0

Party Object

Field	Type	Required	Description
`name`	string	Yes	Party name
`partyType`	`individual` \| `company`	Yes	Party type
`role`	string	No	e.g. "Lender", "Borrower"
`address`	object	Yes	Address with `addressLine1`, `addressLine2`, `postcode`, `city`, `state`, `country`
`contactNumber`	string	Yes	Phone number
`email`	string	No	Email address
`identityNumber`	string	No	For individuals
`registrationNumber`	string	No	For companies
`identityType`	`NRIC` \| `PASSPORT`	No	For individuals

Response

{
  "contractId": "a1b2c3d4-...",
  "status": "Pending",
  "organizationId": "...",
  "partnerId": "...",
  "externalReferenceId": "LOAN-001",
  "confirmed": false,
  "message": "Contract created",
  "stampDutyAmount": 10.00,
  "latePenaltyAmount": 0,
  "totalDutyPayable": 10.00,
  "balances": {
    "serviceCreditBalance": 50,
    "exemptionCreditBalance": 0,
    "dutyWalletBalance": 1000.00
  }
}

Idempotency

Re-sending the same (x-service-id, externalReferenceId) updates the existing contract's data, as long as the contract is still in a mutable status (Pending).

If the contract has already been confirmed or is in a later status, the request returns a 409 Conflict.

Late-Stamping Penalties

For contracts with a contractDate more than 30 days before the submission date, a late-stamping penalty applies. The penalty amount is included in the latePenaltyAmount field of the response.

Error Responses

Status	Description
`400`	Validation error (missing fields, invalid schema)
`401`	Authentication failed
`402`	Insufficient wallet balance (when `confirm=true`)
`403`	Integration is inactive
`409`	Duplicate reference in immutable status
`413`	File exceeds 20MB

Loan Agreement API