Connect your lending system to Vistroy

Vistroy tracks borrowers by Ghana Card across every SIM, every network and every lender. One API call before you pay out a loan tells you whether this person defaulted on another number, is borrowing from several lenders at once, or cannot afford the repayment.

This guide is for the technical team at a bank, microfinance company, savings and loans company or digital lender. Every example below can be copied and run as it is against the sandbox.

Getting access

1. Apply for an account. You get your API key straight away. Copy it: it is shown only once.
2. Wait for approval. The Vistroy registry team checks your institution. Until then, requests return 403 with "waiting for approval".
3. Build and test your integration with the examples on this page and the test borrowers below.

Send your key on every request:

X-API-Key: vsk_your_institution_key

The lending flow

1. Get consent. Send the borrower an SMS code. When they read it back, you receive a consent_id.
2. Run the pre-disbursement check with that consent_id, right before paying out. You get APPROVE, MANUAL_REVIEW or DECLINE, the safe amount, and the reasons.
3. Optional: read the borrower's MoMo statement to get their real income, and pass the statement_id to the check.
4. Report the loan once it is paid out, and report every status change after that: late, repaid, defaulted.
5. Agree a repayment plan if the borrower falls behind, and record each payment.
6. Answer disputes when a borrower says a record is wrong.

Good reporting is what makes the network work: every lender that reports defaults, and every lender that checks before lending, is protected by everyone else's data.

1. Borrower consent

You must have the borrower's permission before looking at their file. Vistroy sends an SMS code to their phone. They read the code back to you (or type it into your app), and that code becomes the proof.

Send the code

curl -X POST BASE/api/consents/otp/start \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ghana_card_number": "GHA-000000103-0",
    "msisdn": "0551110103",
    "purpose": "LOAN_APPLICATION",
    "valid_days": 30
  }'

Purposes: LOAN_APPLICATION, CREDIT_LIMIT_REVIEW, EXISTING_ACCOUNT_REVIEW, FRAUD_PREVENTION. The borrower's SMS names your institution and the purpose.

{
  "challenge_id": "OTP-01AF043AA79E",
  "sent_to": "055****103",
  "expires_in_minutes": 5,
  "sms_live": true
}

Confirm the code

curl -X POST BASE/api/consents/otp/verify \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{ "challenge_id": "OTP-01AF043AA79E", "code": "581286" }'

{
  "consent_id": "CNS-06D33EB3C0CD",
  "purpose": "LOAN_APPLICATION",
  "channel": "SMS_OTP",
  "evidence_reference": "OTP-01AF043AA79E verified by SMS to 055****103",
  "expires_at": "2026-10-30T09:00:00+00:00"
}

Consent collected another way

If the borrower signed a paper form in a branch or agreed in your own app, record it with POST /api/consents and a channel of BRANCH_PAPER, MOBILE_APP, USSD, WEB or VOICE, plus an evidence_reference such as your form number. SMS codes remain the strongest proof.

2. Pre-disbursement check

Call this right before you pay out. It looks at every phone number linked to the Ghana Card, open loans at other lenders, recent applications, shared devices and affordability, and gives one decision.

curl -X POST BASE/api/v1/check \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ghana_card_number": "GHA-000000103-0",
    "consent_id": "CNS-06D33EB3C0CD",
    "msisdn": "0551110103",
    "requested_amount": 1000,
    "tenor_days": 30,
    "avg_monthly_inflow": 2000,
    "momo_history_months": 18,
    "device_id": "DEV-12345",
    "loan_reference": "LN-0003"
  }'

The response (shortened):

{
  "application_id": "APP-21F9AC8919",
  "decision": "MANUAL_REVIEW",
  "requested_amount": 1000.0,
  "approved_amount": 600.0,
  "score": 649,
  "risk_band": "Fair (Limited History)",
  "flags": [
    { "code": "UNAFFORDABLE", "severity": "MEDIUM",
      "message": "Needs about GHS 1,000.00/month; safe capacity is GHS 600.00/month." }
  ],
  "identity": {
    "applying_number": "055****103",
    "linked_numbers": [ { "number": "055****103", "network": "MTN", "loans": 1,
                          "unpaid_default": false, "verified": true } ]
  },
  "exposure": { "open_loans": 0, "lenders_with_open_loans": 0, "outstanding_ghs": 0 },
  "affordability": { "monthly_capacity_ghs": 600.0, "affordable_max_ghs": 600.0 },
  "verification_details": { "report_id": "...", "signature": "...", "scoring_model_version": "vistroy-score-0.3" }
}

Keep application_id and verification_details with your loan file. The signature proves the report came from Vistroy and was not changed. Anyone can check it with POST /api/reports/verify.

3. Report loans

Report each loan when you pay it out, then send the same loan_reference again whenever its status changes. Sending it again updates the loan, it never creates a duplicate.

curl -X POST BASE/api/loans/submit \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ghana_card_number": "GHA-000000103-0",
    "loan_reference": "LN-2026-0001",
    "loan_amount": 600,
    "monthly_payment": 600,
    "repayment_status": "ACTIVE",
    "msisdn": "0551110103",
    "network": "MTN"
  }'

Always include msisdn. The phone number is what lets Vistroy catch a borrower who defaults on one SIM and applies on another. You can also send opened_date (YYYY-MM-DD) if the loan was paid out on an earlier day.

4. Upload a loan book

Send many loans in one request, for example your whole portfolio on the first day, then a weekly update. Upload the CSV text inside JSON. First check it with dry_run: true to see errors row by row, then import.

Downloads a CSV with the right columns: ghana_card_number, loan_reference, loan_amount, monthly_payment, repayment_status, msisdn, network, opened_date. The last three are optional. Dates can be 2026-03-15 or 15/03/2026.

curl -X POST BASE/api/loans/bulk \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "csv_text": "ghana_card_number,loan_reference,loan_amount,monthly_payment,repayment_status,msisdn\nGHA-000000901-0,LN-0001,1500,300,ACTIVE,0241234567\n",
    "dry_run": true
  }'

{
  "dry_run": true, "imported": 0,
  "rows_valid": 1, "rows_with_errors": 0,
  "new_loans": 1, "updated_loans": 0, "borrowers": 1, "defaulted": 0,
  "errors": []
}

Then send the same request with "dry_run": false. If some rows have errors, the import is refused unless you add "skip_errors": true, which imports only the valid rows. Up to 5,000 rows per request.

5. Repayment plans

When a borrower falls behind, agree a plan instead of writing the loan off. Vistroy tracks each payment, sends SMS reminders, and marks the loan REPAID (or SETTLED if you accepted less) when the plan is finished. Other lenders see that the borrower is on a plan.

curl -X POST BASE/api/repayment-plans \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "loan_reference": "LN-2026-0001",
    "instalments": 3,
    "frequency": "MONTHLY",
    "first_due_date": "2026-11-01"
  }'

Frequencies: WEEKLY, BIWEEKLY, MONTHLY, ONE_OFF. For a settlement, add outstanding_balance and a lower agreed_amount.

curl -X POST BASE/api/repayment-plans/RPL-9D3CEE2562/payments \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 200, "channel": "MOMO", "reference": "MP240930.1234.A56789" }'

Use the MoMo transaction ID as reference. The same reference can't be recorded twice, which prevents double counting.

Overdue loans, repayment permissions and evidence packs

For a loan marked Late or Defaulted with no open plan, you can send an SMS reminder. It goes only to the borrower's own numbers: the number the loan was paid to, and numbers the borrower confirmed with an SMS code. Never to contacts. At most once every 3 days and 4 times in 30 days, and never while a dispute is open.

6. Disputes

Borrowers can challenge a record from their own page. Disputes about your loans appear for you to answer within 30 days.

curl -X POST BASE/api/disputes/DSP-700AAC1EDB/respond \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "CORRECT",
    "corrected_status": "REPAID",
    "clear_default_history": true,
    "notes": "Payment confirmed in our ledger on 12 August."
  }'

Use "action": "NO_CHANGE" with a clear explanation if the record is correct.

7. Mobile money statements

Upload the borrower's statement exactly as MTN MoMo, Telecel Cash or AT Money sent it, as a PDF or CSV (up to 5 MB). Vistroy reads the transactions and works out real monthly income, leaving out loan payouts from other apps and reversals. It needs the same consent_id as the check.

curl -X POST BASE/api/momo/statements \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ghana_card_number": "GHA-000000901-0",
    "consent_id": "CNS-06D33EB3C0CD",
    "msisdn": "0241234567",
    "file_name": "statement.pdf",
    "file_base64": "JVBERi0xLjQK..."
  }'

The response (shortened):

{
  "statement_id": "STM-6AB787C69A",
  "account_number": "024****567",
  "account_name": "Kwame Mensah Demo",
  "period_start": "2026-06-01", "period_end": "2026-09-28", "months_covered": 3.9,
  "transactions_read": 105,
  "avg_monthly_income_ghs": 3140.82,
  "income_stability": 0.95,
  "loan_payouts_received": 1, "loan_payouts_ghs": 500.0,
  "gambling_ghs": 250.59, "gambling_share_pct": 2.0,
  "balance_checks": 104, "balance_breaks": 0,
  "monthly": [ { "month": "2026-06", "income": 3088.99, "loan_payouts": 0.0, "money_out": 2139.76 } ],
  "flags": [ { "code": "GAMBLING_SPEND", "severity": "LOW", "message": "Some betting payments (GHS 250.59, 2.0% of income)." } ]
}

Then send "statement_id": "STM-6AB787C69A" with the check. Vistroy keeps only this summary, not the individual transactions. The read appears in the borrower's activity log.

Sample files for testing: sample PDF and sample CSV, for the made-up borrower GHA-000000901-0 on 0241234567.

8. Pilot results

See what the checks caught and what happened to the loans you paid out afterwards. Each check is matched to the loan you reported: by loan_reference if you sent one, otherwise the first loan for the same borrower opened within 30 days.

curl BASE/api/pilot/report?days=90 -H "X-API-Key: vsk_your_institution_key"

You get checks run, decisions, loans declined and not paid out (and how many of those borrowers defaulted at another lender later), loan sizes reduced, default rates by decision, the most common warnings, and money recovered through repayment plans. The CSV has one row per check. A printable version is at /report.

9. Your account and keys

Check your approval status, and manage your keys without contacting Vistroy. You can have up to 3 active keys at a time.

curl -X POST BASE/api/account/keys \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Production server" }'

1. Create a new key and put it in your system.
2. Check that it works. GET /api/account shows when each key was last used.
3. Turn off the old key. It stops working straight away. You can't turn off your last active key.

10. Staff logins

People at your company sign in to the dashboard with their own email and password. Your systems keep using the API key. Every action is recorded with the name of the person who did it.

curl -X POST BASE/api/staff/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "officer@yourcompany.com", "password": "..." }'

Send the returned token as X-Staff-Token instead of X-API-Key. It lasts 12 hours. After 5 wrong passwords, the email is locked for 15 minutes.

New staff get a temporary password, shown once, and must choose their own when they first sign in. The API key can add the first admin, for lenders who signed up before staff logins existed. A company always keeps at least one admin.

11. List and update loans

Your loans, newest change first, with counts by status, the decision from the matching check, and any repayment plan.

curl -X POST BASE/api/loans/LN-2026-0001/status \
  -H "X-API-Key: vsk_your_institution_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "LATE", "note": "Missed the October payment" }'

Changes only the status. Reopening a Repaid or Settled loan needs a manager. A loan with an active repayment plan closes through the plan, not here.

12. Borrower data rights

Borrowers can download everything Vistroy holds about them from the My Credit File page: loans, phone numbers, consents, checks, statement summaries and who looked at their file. They can also ask for a correction, deletion, or for Vistroy to stop using their data. The Vistroy team answers within 30 days.

A completed deletion removes statement summaries and device records and withdraws all consents. Loan records are kept, so lenders keep a fair history. After consents are withdrawn, checks return 403 until the borrower gives a new consent.

13. Borrower approves on their phone

After you call /api/consents/otp/start, the borrower can read you the SMS code as before, or open the Vistroy USSD or WhatsApp menu and choose 3 Approve a lender. They have 15 minutes. Check the answer with:

curl BASE/api/consents/otp/OTP-1A2B3C4D5E6F \
  -H "X-API-Key: vsk_your_institution_key"

status is WAITING, APPROVED (with the consent to use in your check), DECLINED or EXPIRED. Ask every few seconds while the borrower is with you. The dashboard does this for you.

Decisions and risk flags

Errors

Errors return a JSON body with a plain-language detail you can show to your staff.

Test data (sandbox)

These test borrowers exist in the sandbox so you can see each outcome. They are not real people.

Data rules

• Only check a borrower who has given consent, and only for the purpose they agreed to.
• Every check and every loan update appears in the borrower's own activity log, with your institution's name.
• Borrowers get an SMS fraud alert when you check their file (at most one per lender per day) and when a new phone number is linked to their Ghana Card. If they press "This wasn't me", your permissions for that borrower are withdrawn and the file shows OWNER_REPORTED_FRAUD to every lender until the report is closed.
• Phone numbers of other lenders' customers are always masked (024****104).
• Report accurately and on time. Correct a wrong record as soon as you know about it.
• Answer borrower disputes within 30 days.

Questions: contact the Vistroy team. To get a key, apply for an account. The full list of endpoints and fields is in the interactive API reference.