Skip to content

Loan Repayment Guaranty Integration Guide

Product code: lrgg-stnd-1111

Covers loan repayment in the event the borrower becomes unable to repay due to death, disability, or critical illness. Primarily for lending platforms and microfinance institutions.

Integration Flow

Standard 4-step flow. Premium is calculated based on loan amount.

Step 1 — Get Premium Quote

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "dump ipck_lrgg-stnd-1111*PRMM",
      "seed": {
        "LoanAmount": 450000,
        "LoanTenure": 12
      }
    }
  }'

LoanAmount is the full loan principal in Naira. LoanTenure is the loan term in whole months (integer). Both are required in the quote seed — the premium is calculated from these values.

Type note: Both LoanAmount (float) and LoanTenure (integer) must be numbers, not strings. Send 450000 and 12, not "450000" and "12".

Response: 

{
  "exctnFdbck": { "id": 75 },
  "prmm": 5000
}

Step 2 — Register Consumer

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "h",
      "name": { "first": "Emeka", "last": "Obi" },
      "gender": "m",
      "dob": { "date": "1982-07-14" },
      "addrss": { "addrss": "22 Adeola Odeku Street, Victoria Island, Lagos" },
      "phoneNo": "+2348041234567",
      "eMail": "emeka.obi@email.com"
    }
  }
}

Date of birth, gender, and address are required for this product (unlike goods-in-transit or device warranty).

Response: Returns id — store as consumer_id.

Step 3 — Request Policy

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "entt_{CONSUMER_ID}: insure",
      "seed": {
        "ctgry": "lrgg",
        "type": "stnd",
        "pckg": "1111",
        "id": "YOUR_32_CHAR_TX_REF",
        "addtnlFact": {
          "LoanAmount": 450000,
          "LoanTenure": 12,
          "DsbrsmDate": "2024-03-20",
          "LoanStartDate": "2024-03-20",
          "LoanEndDate": "2025-03-20"
        }
      }
    }
  }'

Required Fields

Field Type Description
ctgry string "lrgg"
type string "stnd"
pckg string "1111"
id string Your 32-char lowercase alphanumeric transaction ref
addtnlFact.LoanAmount number (float) Loan principal in Naira — e.g., 450000
addtnlFact.LoanTenure number (integer) Loan term in whole months — e.g., 12 for one year
addtnlFact.DsbrsmDate string Date funds were disbursed — YYYY-MM-DD
addtnlFact.LoanStartDate string Cover start date — YYYY-MM-DD
addtnlFact.LoanEndDate string Cover end date — YYYY-MM-DD

For Organisational Borrowers (Optional)

If the loan is to a company or organisation, include director details:

Field Type Description
addtnlFact.DrctrName string Director's full name
addtnlFact.DrctrDob string Director's date of birth — YYYY-MM-DD

Response: 

{
  "exctnFdbck": { "id": 75 }
}

Step 4 — Check Policy Status

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "dump entt_{CONSUMER_ID}|insr_lrgg-stnd-1111-{TX_ID}*STATUS"
    }
  }'

Status values

status Meaning Next step
"p" Pending — Octamile is reviewing and issuing the guaranty Poll again; see timing note below
"a" Approved — base64 certificate in response Done
"d" Declined — see statusNote for the reason Contact Octamile

Loan guaranty issuance is a manual process. After the insure request is accepted, Octamile reviews and issues the certificate within one business day. status will remain "p" until issued — do not expect instant approval. Poll every few minutes and notify the disbursement workflow asynchronously when status becomes "a".

Approved response: 

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "crtfct": "<base64-encoded-certificate>",
  "crtfctType": "jpg"
}

Integration Timing

Purchase the guaranty at or before loan disbursement. Octamile recommends:

  1. Generate premium quote at loan approval.
  2. Collect premium as part of loan processing fees.
  3. Disburse loan.
  4. Immediately call Step 3 with the disbursement date.

Do not submit the policy request days after disbursement — the LoanStartDate must match the actual disbursement date.

Common Decline Reasons

Issue Likely cause Fix
Loan amount mismatch LoanAmount in Step 3 differs from Step 1 Always pass the same loan amount in both steps
Date discrepancy LoanStartDate is after LoanEndDate Verify loan tenure calculation before submission
Consumer age Borrower falls outside insurable age range Contact Octamile support — age band eligibility may apply

See also