Embedded Finance API

1. Getting Started

MightyFin Embedded Finance lets you offer payments, wallets, and credit inside your own product — under your own brand — without becoming a licensed financial institution yourself. We hold the license, the balance sheet, the payment rails, and the credit decisioning. You hold the relationship with the people and businesses in your ecosystem.

1.1 What You're Integrating

Two capability bundles sit on top of one shared account and ledger infrastructure:

• Advantage — direct financing for your own business: working capital, invoice advances, and equipment financing.
• Network — financial services you extend to the people and businesses inside your ecosystem: merchant credit, supplier credit, inventory financing, bulk payouts, and receivables collection.

Every participant — whether that's your business or someone in your network — gets a wallet, an identity record, and a credit profile through MightyFin. You white-label the experience; we run the infrastructure behind it.

1.2 Who Integrates

• Manufacturers / Producers — extending credit or fulfillment to downstream distributors.
• Distributors — extending stock or trade credit to retailers.
• Aggregators / Offtakers — financing input costs for the suppliers in their network (e.g. agricultural aggregators financing farmers).
• Service Agencies — managing payouts and credit for a distributed workforce or agent network.

If your business doesn't fit neatly into one of these, talk to your account team — we onboard new ecosystem shapes regularly.

1.3 Core Concepts

• One Identity. A participant's identity and credit history are portable — they follow the person or business, not the partner relationship. Someone active in your ecosystem today keeps their MightyFin identity and credit standing even if your relationship with them ends.
• One Wallet. There's a single Wallet ledger underneath everything. Partners, network participants, and end customers all hold accounts within it — not separate wallet products per audience.
• One Credit Limit. Every entity has one pooled credit limit spanning every product they're eligible for. Drawing on Merchant Credit and Invoice Advance for the same entity draws down the same pool.
• You see your relationship, not the whole picture. You see what's relevant to your own relationship with a participant — never their activity with other partners or products.
• You get outcomes, not the mechanism. Credit scores and decisions are generated by MightyFin's own risk infrastructure and delivered to you as an outcome to act on. You never need to build or manage the underlying decisioning yourself.

1.4 What's Next

• Authentication & Setup — get sandbox access and make your first authenticated request.
• Partners API — register your organization and configure the capabilities you're activating.
• Wallet API — the shared ledger every other capability sits on top of.

2. Authentication & Setup

2.1 Environments

Environment	Purpose	Access
Sandbox	Build and test your integration against realistic mock data	Issued as soon as you start onboarding
Live	Real money, real participants	Issued after KYB/UBO verification is complete

All downstream vendor calls (payment rails, identity verification) are mocked in sandbox — nothing you do there touches real money or real accounts.

2.2 Onboarding Lifecycle

1. Register — submit your organization details (Partners API).
2. Review — our team reviews your integration and use case.
3. Sandbox — build and test against sandbox credentials.
4. Certification — a short checklist confirming your integration handles idempotency, webhook signatures, and error responses correctly.
5. KYB/UBO verification — required before live credentials are issued.
6. Go live — live credentials issued, monitoring begins.
7. Ongoing reconciliation — standard for any active integration.

2.3 Authentication

MightyFin uses OAuth2 client credentials. You exchange a client_id and client_secret for a short-lived, scoped access token, then use that token as a Bearer token on every request.

POST {host}/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=wallet:read wallet:write credit:request

// Response
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "wallet:read wallet:write credit:request"
}

GET {host}/v1/wallets/me
Authorization: Bearer eyJhbGciOi...

Scopes are explicit and composable — request only what your integration needs (e.g. wallet:read, wallet:write, credit:request, participants:manage). Coarse "do everything" tokens aren't issued.

2.4 API Standards

• Idempotency. Every mutating request (POST, PATCH) requires an Idempotency-Key header. Retrying a request with the same key and body returns the original result — it's never executed twice. Reusing a key with a different body returns 409.
• Request IDs. Every response includes an X-Request-Id header — include it when contacting support about a specific call.
• Pagination. List endpoints accept limit (default 20, max 100) and cursor, and return next_cursor when more results exist.
• Rate limits. Sandbox: 60 requests/minute per client. Live: tiered by volume, starting at 300 requests/minute. Limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included on every response.
• Versioning. The API is versioned in the path (/v1/...). Breaking changes ship as a new version; non-breaking additions (new fields, new endpoints) don't. Deprecations are announced with a minimum 90-day migration window.

POST {host}/v1/wallets/me/transfers
Authorization: Bearer eyJhbGciOi...
Idempotency-Key: 7c1b1f2a-9e3d-4a2b-8f1e-3d2c1b0a9f8e
Content-Type: application/json

{
  "amount": 500.00,
  "currency": "ZMW",
  "destination_wallet_id": "wal_9f8a2b1c"
}

3. Partners API

The foundation of your integration — your organization's own record, capability activation, and white-label configuration.

3.1 Register a Partner

POST {host}/v1/partners
Idempotency-Key: <required>

// Request
{
  "legal_name": "Kalimba Distribution Ltd",
  "value_chain_role": "distributor",
  "country": "ZM",
  "contact_email": "ops@kalimbadist.example"
}

value_chain_role is one of manufacturer_producer, distributor, aggregator_offtaker, service_agency.

// Response
{
  "partner_id": "prt_2b6f0a91",
  "legal_name": "Kalimba Distribution Ltd",
  "status": "pending_review",
  "value_chain_role": "distributor"
}

3.2 Get / Update a Partner

GET   {host}/v1/partners/{id}
PATCH {host}/v1/partners/{id}

3.3 White-Label Configuration

GET   {host}/v1/partners/{id}/branding
PATCH {host}/v1/partners/{id}/branding

Configure the name, logo, and support contact your participants see — every interaction runs under your brand, backed by MightyFin's infrastructure.

// PATCH /partners/{id}/branding
{
  "display_name": "Kalimba Advance",
  "logo_url": "https://cdn.example.com/kalimba-logo.png",
  "support_email": "support@kalimbadist.example"
}

3.4 Capability Activation

Capabilities are activated per-partner and gated independently of available credit — activating Merchant Credit doesn't imply Supplier Credit is also active.

GET  {host}/v1/partners/{id}/capabilities
POST {host}/v1/partners/{id}/capabilities/{capability}/activate

// GET /partners/{id}/capabilities
{
  "data": [
    { "capability": "invoice_advance", "bundle": "advantage", "status": "active" },
    { "capability": "merchant_credit", "bundle": "network", "status": "active" },
    { "capability": "supplier_credit", "bundle": "network", "status": "eligible" }
  ]
}

status is active, eligible (you qualify, not yet turned on), or ineligible (see the response detail for the unmet requirement — e.g. Invoice Advance requires verified invoices, Merchant Credit requires an approved merchant relationship).

3.5 Offboarding

POST {host}/v1/partners/{id}/offboard

Ends your active relationship. Participants you onboarded keep their MightyFin identity and wallet — offboarding ends your relationship with them, not their standing with MightyFin. Any open credit exposure tied to your ecosystem is resolved as part of this process before deactivation completes.

4. Customers & Network Participants API

A Network participant is a person or business operating inside your ecosystem — a retailer, farmer, or worker you onboard. Their identity, credit history, and wallet are portable and stay with MightyFin regardless of their relationship with you.

4.1 Register a Participant

POST {host}/v1/participants
Idempotency-Key: <required>

// Request — individual
{
  "partner_id": "prt_2b6f0a91",
  "participant_type": "individual",
  "full_name": "Chanda Mwansa",
  "phone": "260971234567",
  "role_in_network": "retailer"
}

// Request — business
{
  "partner_id": "prt_2b6f0a91",
  "participant_type": "business",
  "business_name": "Mwansa General Store Ltd",
  "phone": "260971234567",
  "role_in_network": "retailer"
}

// Response
{
  "participant_id": "npt_4a1c9e02",
  "partner_id": "prt_2b6f0a91",
  "status": "pending_verification",
  "wallet_account_id": null
}

wallet_account_id populates once identity verification (§5) completes.

4.2 Manage a Participant

GET    {host}/v1/participants/{id}
PATCH  {host}/v1/participants/{id}
POST   {host}/v1/participants/{id}/suspend
POST   {host}/v1/participants/{id}/activate

Suspending a participant affects their standing within your ecosystem only — it never touches their underlying MightyFin identity or standing with any other partner.

// POST /participants/{id}/suspend
{ "reason": "under_review" }

4.3 Business Profile

GET    {host}/v1/participants/{id}/business-profile
PATCH  {host}/v1/participants/{id}/business-profile

Required when participant_type is business — industry, trading history, locations, and owners/directors.

{
  "industry": "agriculture_input_retail",
  "trading_since": "2019-03-01",
  "locations": [{ "type": "primary", "town": "Chipata", "province": "Eastern" }],
  "owners": [{ "full_name": "Chanda Mwansa", "role": "director", "ownership_pct": 100 }]
}

4.4 What You See

You see a participant's activity within your own ecosystem only — never their relationship with other partners or products. This is enforced server-side on every request, not something you need to filter for yourself.

5. Identity & KYC/KYB API

5.1 Start Verification

POST {host}/v1/participants/{id}/verification
Idempotency-Key: <required>

// Request
{
  "verification_type": "individual_kyc",
  "documents": ["national_id"]
}

verification_type is individual_kyc (national ID / passport, phone, selfie match) or business_kyb (registration documents, UBO declaration). Returns a session your integration directs the participant to complete.

// Response
{
  "verification_id": "ver_7a3e1c9d",
  "status": "pending",
  "session_url": "https://verify.mightyfinance.co.zm/s/ver_7a3e1c9d"
}

5.2 Check Verification Status

GET {host}/v1/participants/{id}/verification/{verification_id}

{
  "verification_id": "ver_7a3e1c9d",
  "status": "verified",
  "verified_at": "2026-07-22T10:14:00Z"
}

status is pending, verified, or failed. Subscribe to participant.verified via Webhooks instead of polling for real-time updates.

5.3 Document Upload

POST {host}/v1/participants/{id}/documents
Content-Type: multipart/form-data

Accepts standard document formats (PDF, JPEG, PNG). Documents are retained per our data retention policy and used only for verification and compliance purposes.

5.4 Compliance Screening

Every participant is automatically screened against sanctions and PEP lists as part of verification — no separate call required on your side. A compliance_hold status on a participant means a manual review is in progress; participant-facing actions are paused until it clears.

6. Wallet API

One ledger underneath every capability. Partners, network participants, and customers each hold an account within the same Wallet service — not separate wallet products per audience.

6.1 Get a Wallet

GET {host}/v1/wallets/me

{
  "wallet_id": "wal_9f8a2b1c",
  "owner_id": "npt_4a1c9e02",
  "owner_type": "network_participant",
  "currency": "ZMW",
  "balance": 42500.00,
  "available_balance": 42500.00
}

6.2 Transactions

GET {host}/v1/wallets/{id}/transactions?limit=20&cursor=...

{
  "data": [
    {
      "transaction_id": "wtx_11a2b3c4",
      "type": "credit",
      "amount": 15000.00,
      "currency": "ZMW",
      "description": "Merchant Credit disbursement",
      "created_at": "2026-07-22T09:00:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6..."
}

6.3 Deposits

POST {host}/v1/wallets/{id}/deposits
Idempotency-Key: <required>

{
  "amount": 5000.00,
  "currency": "ZMW",
  "payment_method": { "provider": "mobile_money", "channel_ref": "260971234567" }
}

payment_method.provider is mobile_money or bank_transfer — never a specific gateway name. Which rail actually executes the transfer is resolved server-side and can change without your integration changing.

6.4 Transfers

POST {host}/v1/wallets/{id}/transfers
Idempotency-Key: <required>

{
  "amount": 2000.00,
  "currency": "ZMW",
  "destination_wallet_id": "wal_1a2b3c4d"
}

Transfers between two MightyFin wallets settle instantly and never leave the ledger — no external rail involved.

6.5 Loan Repayments

POST {host}/v1/wallets/{id}/loan-repayments
Idempotency-Key: <required>

{
  "amount": 1200.00,
  "currency": "ZMW",
  "credit_application_id": "capp_c91d0f3a"
}

6.6 Statements

GET {host}/v1/wallets/{id}/statements?from=2026-07-01&to=2026-07-31

Returns a signed URL to a downloadable statement covering the requested period.

6.7 Guarantees

Every mutating endpoint above requires Idempotency-Key — retried requests never double-execute. Every write is atomic across the ledger's double-entry tables — a transfer either fully completes or fully fails, never partially.

7. Credit API

MightyFin's core differentiator: credit decisions built on how your ecosystem actually transacts, delivered to you as an outcome — you never build or manage the underlying risk models yourself.

7.1 Credit Programmes

Programme	Bundle	What it is
Invoice Advance	Advantage	Advance against your own verified invoices
Business Flex	Advantage	Flexible working-capital draw for your own business
Equipment Finance	Advantage	Financing your own operating assets
Merchant Credit	Network	Credit extended to a merchant in your ecosystem
Supplier Credit	Network	Financing between participants in your ecosystem (e.g. distributor→retailer stock credit, aggregator→supplier input credit)
Purchase/Inventory Financing	Network	Financing a participant's stock or inventory purchase

GET {host}/v1/credit/programmes

7.2 Submit an Application

POST {host}/v1/credit/applications
Idempotency-Key: <required>

// Request
{
  "programme_code": "invoice_advance",
  "participant_id": "npt_4a1c9e02",
  "amount_requested": 15000.00,
  "currency": "ZMW",
  "supporting_reference": { "invoice_ids": ["inv_7734", "inv_7735"] }
}

// Response
{
  "application_id": "capp_c91d0f3a",
  "status": "in_review",
  "programme_code": "invoice_advance",
  "amount_requested": 15000.00
}

status is in_review, approved, declined, or offer_pending. Most applications resolve within minutes; higher-value or borderline applications may route through additional review — subscribe to credit.application.status_changed (§14) rather than polling.

7.3 Credit Limits

Every entity has one pooled limit spanning every credit programme they're eligible for.

GET {host}/v1/credit/limits/{owner_id}

{
  "owner_id": "npt_4a1c9e02",
  "currency": "ZMW",
  "limit_total": 50000.00,
  "limit_used": 15000.00,
  "limit_available": 35000.00
}

7.4 Credit Lifecycle

Application → Approval → Offer → Acceptance → Disbursement → Repayment → Closure.

POST {host}/v1/credit/applications/{id}/accept
Idempotency-Key: <required>

State	Meaning
in_review	Being assessed
approved	Decision made, offer being prepared
offer_pending	Terms presented, awaiting acceptance
accepted	Offer accepted
disbursed	Funds moved to the recipient's wallet
repaying	Active repayment (§10)
closed	Fully repaid
declined	Not approved — every decline includes eligible alternatives where available

7.5 Decision Detail

GET {host}/v1/credit/applications/{id}/decision

{
  "application_id": "capp_c91d0f3a",
  "status": "declined",
  "reason_code": "insufficient_trading_history",
  "eligible_alternatives": [
    { "programme_code": "business_flex", "reason": "shorter trading-history requirement" }
  ]
}

Every decision includes a reason code and, where applicable, alternatives the applicant already qualifies for — never just a bare decline.

8. Commerce Finance API

Tracks the delivery side of a transaction financed through Network — confirming goods or services were fulfilled against a Purchase/Inventory Financing or Supplier Credit draw.

8.1 Register a Fulfillment

POST {host}/v1/commerce/fulfillments
Idempotency-Key: <required>

// Request
{
  "credit_application_id": "capp_c91d0f3a",
  "items": [
    { "description": "50kg maize seed, 200 units", "value": 12000.00 }
  ],
  "delivery_confirmed_at": "2026-07-22T14:00:00Z"
}

// Response
{
  "fulfillment_id": "cfl_8b2a1d3e",
  "credit_application_id": "capp_c91d0f3a",
  "status": "confirmed"
}

8.2 Check Fulfillment Status

GET {host}/v1/commerce/fulfillments/{id}

status is pending, confirmed, or disputed. A confirmed fulfillment closes the loop on the associated credit application's underlying collateral — it doesn't affect the repayment schedule itself, which is tracked separately (§10).

8.3 Disputing a Fulfillment

POST {host}/v1/commerce/fulfillments/{id}/dispute

{ "reason": "goods_not_received", "description": "Delivery not confirmed by recipient." }

Routes into the same dispute-resolution workflow as Reconciliation.

9. Payments API

Payment Rails handles money moving into or out of the platform — distinct from the Wallet API, which handles money moving within the platform's own ledger.

9.1 Collections — Bringing Money In

POST {host}/v1/payments/collections
Idempotency-Key: <required>

{
  "amount": 5000.00,
  "currency": "ZMW",
  "payment_method": { "provider": "mobile_money", "channel_ref": "260971234567" },
  "purpose": "wallet_deposit"
}

payment_method.provider is mobile_money or bank_transfer — the specific rail is resolved server-side. purpose is wallet_deposit or network_collection (a receivable collected on your behalf, see §10).

9.2 Disbursements — Sending Money Out

POST {host}/v1/payments/disbursements
Idempotency-Key: <required>

{
  "amount": 2000.00,
  "currency": "ZMW",
  "source_wallet_id": "wal_9f8a2b1c",
  "destination": { "provider": "mobile_money", "channel_ref": "260971234567" }
}

Used when money leaves the platform entirely — a participant cashing out to their own account, distinct from a wallet-to-wallet transfer.

9.3 Bulk Payouts

POST {host}/v1/payments/disbursements/bulk
Idempotency-Key: <required>

{
  "source_wallet_id": "wal_2b6f0a91",
  "payouts": [
    { "destination_wallet_id": "wal_1a2b3c4d", "amount": 500.00 },
    { "destination_wallet_id": "wal_5e6f7g8h", "amount": 750.00 }
  ]
}

Pay hundreds or thousands of network participants in a single call. Each payout is processed and reported individually — a partial failure never blocks the rest of the batch.

// Response
{
  "batch_id": "bpo_3c4d5e6f",
  "status": "processing",
  "total_payouts": 2,
  "total_amount": 1250.00
}

Subscribe to payment.disbursement.completed / payment.disbursement.failed (§14) for per-payout results.

9.4 Reference Data

Supported networks and banks: §16 Reference Data.

10. Repayments & Collections API

Two related but distinct capabilities: Repayments track what participants owe MightyFin on active credit; Collections let you collect what your own network owes you, using the same rails.

10.1 Repayment Schedule

GET {host}/v1/repayments/{owner_id}/schedule

{
  "owner_id": "npt_4a1c9e02",
  "programme_code": "merchant_credit",
  "installments": [
    {
      "due_date": "2026-08-15",
      "principal": 1200.00,
      "interest": 80.00,
      "running_balance": 13800.00,
      "status": "upcoming"
    }
  ]
}

10.2 Repayment Channels

Repayments are collected wallet-first, with bank transfer as a backup channel — cash is never accepted.

POST {host}/v1/repayments/{owner_id}/pay
Idempotency-Key: <required>

{ "amount": 1200.00, "currency": "ZMW", "source": "wallet" }

10.3 Smart Collections — Your Own Receivables

Register and collect what your network owes you — e.g. a distributor collecting from retailers — through the same wallet and payment infrastructure.

POST {host}/v1/collections/receivables
Idempotency-Key: <required>

{
  "participant_id": "npt_4a1c9e02",
  "amount": 3000.00,
  "currency": "ZMW",
  "due_date": "2026-08-01",
  "reference": "Invoice #INV-2201"
}

// Response
{
  "receivable_id": "rcv_5f0a2b3c",
  "status": "pending",
  "amount": 3000.00
}

GET {host}/v1/collections/receivables/{id}

status is pending, collected, or overdue. Collected amounts settle to your own wallet, distinct from any credit repayment flow.

10.4 Institutional Bulk Repayment

For a single lump-sum payment covering many participants' repayments at once (e.g. a payroll-linked institutional partner), submit the total with an itemized breakdown — matching is handled automatically, with any mismatches routed to Reconciliation.

POST {host}/v1/repayments/bulk
Idempotency-Key: <required>

{
  "total_amount": 480000.00,
  "currency": "ZMW",
  "line_items": [
    { "owner_id": "npt_11a", "amount": 15000.00 },
    { "owner_id": "npt_11b", "amount": 22000.00 }
  ]
}

11. Reconciliation API

Matches money that moved externally (via Payment Rails) against the Wallet ledger's own record of what should have happened.

11.1 Submit Proof of Payment

POST {host}/v1/reconciliation/proofs
Idempotency-Key: <required>

{
  "amount": 480000.00,
  "currency": "ZMW",
  "reference": "Bank lump-sum, batch 2026-07",
  "document_url": "https://uploads.example.com/proofs/pf_9931.pdf",
  "expected_matches": [
    { "wallet_transaction_id": "wtx_11a", "amount": 15000.00 }
  ]
}

Matching runs automatically. Anything that doesn't cleanly reconcile is routed to manual review — see status via:

GET {host}/v1/reconciliation/exceptions

11.2 Disputes

POST {host}/v1/reconciliation/disputes
GET  {host}/v1/reconciliation/disputes/{id}

// Request
{
  "wallet_transaction_id": "wtx_11a",
  "reason": "amount_incorrect",
  "description": "Expected ZMW 15,000, received ZMW 16,200."
}

Track resolution via GET or subscribe to reconciliation events (§14).

12. Risk & Decisioning

MightyFin's risk decisioning runs entirely on our side — you never call a separate "risk engine" API. Decisions surface to you through the Credit API as an outcome, a reason code, and (where applicable) eligible alternatives.

12.1 What Factors Into a Decision

Decisions weigh identity verification status, credit history, your relationship with the applicant, transaction history within your ecosystem, and — where relevant — invoice or trading data submitted as part of the application. You don't need to submit a risk score yourself; submit the application (§7.2) and MightyFin's infrastructure does the rest.

12.2 Reason Codes

Code	Meaning
insufficient_trading_history	Not enough transaction history in this ecosystem yet
identity_unverified	Verification (§5) not yet complete
limit_exceeded	Requested amount exceeds the pooled credit limit (§7.3)
documentation_incomplete	Required supporting documents missing or unreadable
existing_exposure	Outstanding exposure across other active credit already high relative to profile

This list grows as new programmes launch — treat an unrecognized code as informational, not an error.

12.3 Escalation and Review

Some applications — high-value or borderline — route to manual review before a final decision. This is by design, not a fallback: certain decisions always warrant a second look, regardless of how much automation matures. You'll see this reflected as status: in_review on the application (§7.4) — no separate call needed.

12.4 Appeals

A declined applicant can request reconsideration:

POST {host}/v1/credit/applications/{id}/appeal

{ "additional_context": "Updated trading history attached." }

13. Notifications API

Send participant-facing notifications (SMS, push, email) through the same infrastructure MightyFin uses for its own platform notifications.

13.1 Send a Notification

POST {host}/v1/notifications/send
Idempotency-Key: <required>

{
  "recipient_id": "npt_4a1c9e02",
  "template": "credit.application.approved",
  "channel_preference": ["sms", "push"],
  "data": { "programme_name": "Merchant Credit", "amount": 15000.00 }
}

template maps to platform events — see §14 Webhooks for the full event list.

13.2 Delivery Status

GET {host}/v1/notifications/{id}/status

{ "notification_id": "ntf_2c3d4e5f", "status": "delivered", "channel": "sms" }

13.3 Reliability

SMS delivery automatically fails over across multiple carriers/providers — no action needed on your side. Retried sends are deduplicated via Idempotency-Key, so a retried bulk-payout notification burst never double-sends.

14. Webhooks

Subscribe to real-time events instead of polling.

14.1 Signing

Every webhook is signed. Verify before trusting the payload:

X-MightyFin-Signature: sha256=<hex-encoded HMAC>
X-MightyFin-Timestamp: <unix epoch seconds>

Compute the HMAC over timestamp.payload using your webhook secret and compare in constant time. Reject anything with a timestamp older than a few minutes.

14.2 Delivery and Retries

Your endpoint must respond within 5 seconds. Failed deliveries retry on this schedule:

Attempt	Delay after previous
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	60 minutes
6+	Every 6 hours, up to 72 hours total

After 72 hours, delivery stops automatically. Resend manually:

POST {host}/v1/webhooks/events/{id}/resend

14.3 Event Types

Event	Fires when
participant.verified	Identity/KYC clears
wallet.transaction.completed	A wallet transaction settles
credit.application.status_changed	A credit application changes state
payment.collection.completed / .failed	A collection resolves
payment.disbursement.completed / .failed	A disbursement resolves
reconciliation.exception.raised	A proof of payment fails to match
commerce.fulfillment.confirmed	A fulfillment is confirmed

14.4 Idempotent Consumption

Every payload carries a stable event_id. Treat a repeated event_id as a no-op — occasional redelivery is expected, not a bug.

14.5 Managing Endpoints

GET   {host}/v1/webhooks/endpoints
POST  {host}/v1/webhooks/endpoints
DELETE {host}/v1/webhooks/endpoints/{id}

{ "url": "https://api.yourcompany.com/webhooks/mightyfin", "events": ["credit.application.status_changed"] }

15. Reports API

Reporting views over your own transaction, credit, and reconciliation data.

15.1 Transaction Reports

GET {host}/v1/reports/transactions?owner_id={id}&from={date}&to={date}

{
  "owner_id": "prt_2b6f0a91",
  "period": { "from": "2026-07-01", "to": "2026-07-31" },
  "summary": { "total_collections": 1250000.00, "total_disbursements": 480000.00, "currency": "ZMW" }
}

15.2 Credit Exposure Reports

GET {host}/v1/reports/credit-exposure?owner_id={id}

Rolls up outstanding exposure across every active credit programme for the given owner.

15.3 Scheduled Delivery

POST {host}/v1/reports/schedules

{ "report_type": "transactions", "frequency": "monthly", "delivery_email": "finance@yourcompany.example" }

16. Reference Data

16.1 Currency

Zambia-first: ZMW. Additional currencies roll out alongside new-market launches.

GET {host}/v1/reference/currencies

16.2 Mobile Money Networks

GET {host}/v1/reference/mobile-money-providers

{
  "data": [
    { "code": "mtn", "name": "MTN Mobile Money" },
    { "code": "airtel", "name": "Airtel Money" },
    { "code": "zamtel", "name": "Zamtel Kwacha" }
  ]
}

Never required as a top-level field — you send provider: mobile_money on a request (§6, §9) and, where relevant, select a specific network from this list.

16.3 Banks

GET {host}/v1/reference/banks

{
  "data": [
    { "code": "zanaco", "name": "Zanaco" },
    { "code": "fnb", "name": "FNB Zambia" }
  ]
}

16.4 Value Chain Roles

GET {host}/v1/reference/value-chain-roles

{
  "data": [
    { "code": "manufacturer_producer", "name": "Manufacturer / Producer" },
    { "code": "distributor", "name": "Distributor" },
    { "code": "aggregator_offtaker", "name": "Aggregator / Offtaker" },
    { "code": "service_agency", "name": "Service Agency" }
  ]
}

16.5 Credit Programmes

GET {host}/v1/reference/credit-programmes

Returns the full catalogue from §7.1 with bundle assignment — the authoritative, closed set of values for programme_code used throughout the Credit API.

17. Error Handling

17.1 Error Response Shape

{
  "errorCode": 4302,
  "errorDescription": "Requested amount exceeds available pooled credit limit."
}

Build automated handling against errorCode — it's stable. Treat errorDescription as human-readable debugging text; it can change without notice.

17.2 HTTP Status Codes

Status	Meaning
400	Malformed request
401	Missing or invalid authentication
402	Insufficient balance for the requested operation
403	Authenticated, but not authorized for this resource or action
404	Resource not found, or not visible to you
409	Conflict — most commonly an Idempotency-Key reused with a different request body
422	Request is well-formed but fails business validation
429	Rate limit exceeded

17.3 Error Code Ranges

Range	Domain
1000	General / shared
2000	Wallet
3000	Payments
4000	Partners
4100	Identity & KYC/KYB
4200	Customers & Network Participants
4300	Credit
4400	Commerce Finance
4500	Repayments & Collections
4600	Reconciliation

Reference

Code	Meaning
1001	Missing required parameter
1002	Unauthorized — missing or invalid bearer token
1003	Idempotency-Key reused with a different request body
1004	Rate limit exceeded
2001	Insufficient wallet balance
2002	Wallet not found
3001	Payment method not supported
3002	Collection failed
3003	Disbursement failed
4001	Partner not found, or not visible to you
4002	Capability not eligible for activation
4003	Value chain role not recognized
4101	Verification session not found
4102	Verification type not supported for this subject type
4201	Participant not found
4301	Credit programme not found, or not activated for this partner
4302	Requested amount exceeds available pooled credit limit
4303	Application not in a state that allows this transition
4401	Fulfillment not found
4501	Receivable not found
4601	Proof of payment does not match any expected transaction

This table grows as new capabilities ship — an unlisted code should be treated as informational, not assumed reserved.

18. Security & Infrastructure

18.1 Access Control

Every credential is unique to your organization — never shared or pooled across partners. Access tokens are short-lived and scoped; there's no "do everything" token issued to anyone, including internal staff, without explicit, time-bound approval.

18.2 Integration Best Practices

• Always send Idempotency-Key on mutating requests — it's how retries stay safe.
• Verify webhook signatures before processing a payload (§14.1) — never trust an unsigned event.
• Never treat a timeout as success. Poll for actual status, or wait for the corresponding webhook.
• Never look up a resource by a caller-supplied identifier alone — always operate within your own authenticated context; the platform enforces this server-side regardless, but design your integration the same way.
• Don't log full request/response payloads containing tokens or participant PII in your own systems any longer than necessary.

18.3 Availability

Target: 99.9% uptime, excluding scheduled maintenance windows (announced at least 72 hours in advance). Status and incident history: status.mightyfinance.co.zm.

18.4 Rate Limits

Environment	Limit
Sandbox	60 requests/minute per client
Live	300 requests/minute per client, higher tiers available on request

18.5 Observability

GET {host}/v1/observability/summary

Your own integration health: request volume, success/error rate, timeout/retry counts, and reconciliation breaks specific to your traffic.

18.6 Data Handling

MightyFin is the data controller for all participant and transaction data processed through the platform. You receive the outcomes relevant to your relationship with a participant — never another partner's data, and never the underlying models that produce credit decisions.

19. SDKs & Developer Tools

19.1 Postman Collection

The fastest way to explore the API without writing code:

{host}/v1/postman-collection.json

Import directly into Postman or Insomnia — includes every endpoint in this documentation, pre-configured for sandbox.

19.2 Client Libraries

Language	Status
Node.js / TypeScript	Coming soon
Java	Coming soon
PHP	Planned
Mobile (Kotlin / Swift)	Planned

In the meantime, every endpoint here works with any standard HTTP client — the API itself is the source of truth.

19.3 OpenAPI Specification

GET {host}/v1/openapi.json

Machine-readable spec covering every endpoint in this documentation — use it to generate your own client, or validate your integration against it in CI.

Glossary

Terms used consistently across this documentation.

Term	Definition
Partner	The organization integrating MightyFin — registered via the Partners API. Everything in these docs is written from a partner's point of view.
Network Participant	A person or business inside a partner's ecosystem — a retailer, farmer, or worker the partner onboards. Their identity, credit history, and wallet are portable and stay with MightyFin regardless of the relationship with any one partner.
Advantage	The capability bundle covering direct financing for a partner's own business: Invoice Advance, Business Flex, and Equipment Finance.
Network	The capability bundle covering financial services a partner extends to participants in its own ecosystem: Merchant Credit, Supplier Credit, and Purchase/Inventory Financing.
Wallet	The single ledger account type underneath every capability. Partners, network participants, and customers each hold a wallet — not separate wallet products per audience. See the Wallet API.
Pooled Credit Limit	One credit limit per entity, spanning every credit programme it's eligible for. Drawing on two different programmes for the same entity draws down the same pool.
Credit Programme	A named financing product — Invoice Advance, Business Flex, Equipment Finance, Merchant Credit, Supplier Credit, or Purchase/Inventory Financing. See Credit Programmes.
Reason Code	A stable, machine-readable code explaining a credit decision (e.g. insufficient_trading_history). Decline responses include reason codes and, where applicable, eligible alternatives.
KYC	Know Your Customer — identity verification for an individual (national ID/passport, phone, selfie match).
KYB	Know Your Business — verification for a business (registration documents, UBO declaration).
UBO	Ultimate Beneficial Owner — the individual(s) who ultimately own or control a business, declared as part of KYB.
Fulfillment	Confirmation that goods or services financed through a Network draw were actually delivered. See the Commerce Finance API.
Reconciliation	The process of matching money that moved externally (via Payment Rails) against the Wallet ledger's own record of what should have happened. See the Reconciliation API.
Collection	Money coming into the platform from an external source — a wallet deposit or a receivable collected on a partner's behalf.
Disbursement	Money leaving the platform to an external account — distinct from a wallet-to-wallet transfer, which never leaves the ledger.
Receivable (Smart Collection)	A partner's own money owed by its network — e.g. a distributor collecting from retailers — registered and collected through MightyFin's rails on the partner's behalf.
Webhook	A signed, real-time event notification a partner subscribes to instead of polling. See Webhooks.
Sandbox	The test environment. All downstream vendor calls (payment rails, identity verification) are mocked — nothing touches real money or real accounts. Issued as soon as onboarding starts.
Live	The production environment. Real money, real participants. Issued after KYB/UBO verification completes.
Scope	An explicit, composable permission granted to an access token (e.g. wallet:read, credit:request). Coarse "do everything" tokens aren't issued.
Access Token	A short-lived, scoped Bearer token exchanged for a client_id / client_secret pair via OAuth2 client credentials, used to authenticate every API request.
Idempotency Key	A required header on every mutating request. Retrying a request with the same key and body returns the original result instead of executing it twice.
Value Chain Role	The category describing a partner's position in its ecosystem — manufacturer_producer, distributor, aggregator_offtaker, or service_agency.
errorCode / errorDescription	The two fields on every error response. errorCode is stable and safe to build automated handling against; errorDescription is human-readable text that can change without notice.