Embedded Finance API

1. Getting Started

Status: Product overview — availability varies by API section

Release rule: check the API list at GET /sandbox/v1/openapi.json before building your integration. Sections marked Target are planned features, not a promise that they will be ready for your launch.

See API Availability & Delivery Roadmap for the current live, partial and target capability breakdown.

Use this address for sandbox API requests:

{host} = https://efaas.mightyfinance.co.zm/sandbox

Do not use efaas-origin.mightyfinance.co.zm in client integrations. It is an internal origin hostname, not the public API base URL.

MightyFin Embedded Finance is intended to let approved partners integrate selected payments, wallet and credit capabilities into their own products. Production capability depends on MightyFin's verified authority, approved product scope and named licensed service partners; sandbox access does not establish regulatory permission or production availability.

1.1 What You're Integrating

There are two groups of products:

• 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.

In the current sandbox, an eligible synthetic participant receives a synthetic wallet after the configured verification simulation succeeds. Production identity, wallet and credit-profile behavior remains capability- and approval-specific.

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.
• Credit limits. Check the selected product’s limits. Do not assume two products share one credit limit unless MightyFin confirms that the feature is available for your integration.
• 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.
• MightyFin makes the credit decision. Your platform submits the application and reads the result. You do not need to build a credit-decision system.

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 — read balances and test wallet transactions.

2. Authentication & Setup

Status: Sandbox available — production access remains approval-gated

2.1 Environments

Environment	Purpose	Access
Sandbox	Build and test your integration against synthetic data	Issued after tenant onboarding and application credential provisioning
Production	Real data and regulated operations	Separate review, approval, provisioning, activation, credentials, and capability-specific rail approval

The sandbox uses made-up customers, test identity checks and test money. It does not contact a live bank, mobile-money service or identity-check provider.

2.2 Onboarding Lifecycle

1. Register — open the eFaaS tenant portal to sign in or begin onboarding. Tenant onboarding is separate from registering participants in your network. The public Partners API is a target contract.
2. Review — our team reviews your integration and use case.
3. Sandbox — build and test against sandbox credentials.
4. Integration checks — test safe retries, verify webhook signatures and handle API errors. Full journey testing is also required.
5. KYB/UBO verification — required before live credentials are issued.
6. Activate — MightyFin staff enable only the permissions and limits approved for your business.
7. Issue production credentials — credentials are handed off once and kept separate from sandbox credentials.
8. Enable regulated capabilities — each financial rail remains disabled until its own approval and provider controls are complete.

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=participants:read wallets:read

// Response
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "participants:read wallets:read"
}

GET {host}/v1/participants
Authorization: Bearer eyJhbGciOi...

Scopes are API permissions — request only permissions assigned to your application, such as participants:read, participants:write, wallets:read, wallets:write, payouts:read, payouts:write, payments:read, payments:write, payments:reconcile, products:read, credit:read, credit:write, notifications:read, notifications:write, and webhook scopes.

2.4 API Standards

• Safe retries (Idempotency-Key). Check whether the API requires this header. To retry the same action, send the same key and body. Changing the body with the same key returns 409. Use a new key only for a new action. A retry returns the original result; use GET to check the latest status.
• Correlation IDs. Every response includes an X-Correlation-Id header — include it when contacting support about a specific call.
• Pagination. Follow the operation-specific cursor and page-size fields. They are not interchangeable: some lists use cursor, while document lists use after. Copy the returned cursor exactly; do not edit it. Keep the same filters when requesting the next page.
• Rate limits. A public partner quota contract is not enforced yet. Do not design around an assumed requests-per-minute figure until the executable contract publishes it.
• 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/{source_wallet_id}/transfers
Authorization: Bearer eyJhbGciOi...
Idempotency-Key: 7c1b1f2a-9e3d-4a2b-8f1e-3d2c1b0a9f8e
Content-Type: application/json

{
  "amount": "500.00",
  "currency": "ZMW",
  "recipient_wallet_id": "wal_9f8a2b1c",
  "partner_reference": "transfer-001"
}

3. Partners API

Status: Target — not exposed in the public API

This planned API will manage your business details, enabled products and branding. It is not available yet; use the tenant portal for current onboarding.

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

Each product needs its own approval for your business. Enabling Merchant Credit does not also enable Supplier Credit.

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

Status: Sandbox partial — relationship lifecycle is available; business profile is target

A participant is a customer or business in your network, such as a retailer, farmer or worker. 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>

// Synthetic sandbox request
{
  "external_reference": "demo-worker-001",
  "participant_type": "individual",
  "display_name": "Sandbox Worker 001",
  "role_in_network": "worker"
}

Do not submit real names, phone numbers, national identifiers, or other personal data to the sandbox.

// Response
{
  "id": "par_4a1c9e02",
  "external_reference": "demo-worker-001",
  "participant_type": "individual",
  "display_name": "Sandbox Worker 001",
  "role_in_network": "worker",
  "relationship_status": "active",
  "verification_status": "pending",
  "wallet_account_id": null
}

wallet_account_id populates once identity verification (§5) completes.

4.2 Manage a Participant

GET, PATCH, suspend, and activate are available in sandbox. Each request that changes a record requires an Idempotency-Key. external_reference and participant_type cannot be changed; PATCH accepts display_name and/or role_in_network.

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" }

Both suspension and reactivation require a reason. Repeating the same transition with a new idempotency key returns 409 invalid_transition; retrying the original request with its original key returns the original result without making the change again.

4.3 Business Profile

Target — not deployed.

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

Status: Sandbox simulation partial — verification submission and document upload sessions are available

5.1 Start Verification

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

// Request
{
  "outcome": "verified",
  "reason": "Approved synthetic test scenario"
}

This test lets you choose verified, failed, or manual_review. It does not check a real person or business. A verified result creates the customer’s test ZMW wallet.

// Response
{
  "verification_id": "ver_7a3e1c9d",
  "participant": { "id": "par_7a3e1c9d", "verification_status": "verified" },
  "wallet": { "id": "wal_9f8a2b1c", "currency": "ZMW", "balance": "0.00" }
}

5.2 Check Verification Status

Target — the standalone verification lookup route is not deployed. The current participant response includes 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/upload-sessions
Idempotency-Key: <required>
Content-Type: application/json

{
  "document_type": "NATIONAL_ID",
  "purpose": "PARTICIPANT_VERIFICATION",
  "classification": "CONFIDENTIAL",
  "filename": "synthetic-id.png",
  "content_type": "image/png",
  "size_bytes": 12345,
  "sha256": "<lowercase SHA-256 hex>",
  "retention_category": "KYC_EVIDENCE"
}

Upload the file to the URL returned by this request. Use made-up test documents only.

5.4 Compliance Screening

Target — not deployed. The sandbox verification simulator does not perform sanctions, PEP, identity-document, or biometric screening. Real identity checks need separately approved providers and procedures before launch.

6. Wallet API

Status: Sandbox partial — wallet lookup, journal transactions, simulator funding, and wallet transfers are available

Use this API to read wallet balances and transactions, add test money and transfer between wallets. A wallet balance is not the same as available credit.

6.1 Get a Wallet

GET {host}/v1/wallets/{wallet_id}

{
  "id": "wal_9f8a2b1c",
  "currency": "ZMW",
  "balance": "42500.00",
  "status": "active"
}

The participant verification response includes the wallet_id to use here.

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}/sandbox-funding
Idempotency-Key: <required>

{
  "amount": "5000.00",
  "currency": "ZMW",
  "partner_reference": "sandbox-funding-001"
}

This adds test money only. It does not contact a bank or mobile-money provider.

6.4 Transfers

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

{
  "amount": "2000.00",
  "currency": "ZMW",
  "recipient_wallet_id": "wal_1a2b3c4d",
  "partner_reference": "transfer-001"
}

These transfers move money between two MightyFin wallets, not to an external bank or mobile-money account.

6.5 Loan Repayments

Target — not deployed.

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

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

6.6 Statements

Target — not deployed.

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

Requests that change a wallet require Idempotency-Key. Retry the same request with the same key to avoid moving money twice. A transfer must update both wallets together, not just one.

7. Credit API

Status: Sandbox available — manual review only; funding and production lending remain disabled

Find a product, submit a test application and read MightyFin’s decision. MightyFin staff review applications; your platform does not approve the loan.

7.1 Discover Products

GET {host}/v1/products
GET {host}/v1/products/{product_id}
POST {host}/v1/products/{product_id}/validate

Read the product’s current terms. Validation checks the amount, currency, repayment period and applicant type. Passing this check does not approve credit or set money aside.

7.2 Submit an Application

POST {host}/v1/credit/applications
Idempotency-Key: <required>
Authorization: Bearer <token with credit:write>

{
  "product_policy_id": "prd_0123456789abcdef0123456789abcdef",
  "relationship_id": "npt_0123456789abcdef0123456789abcdef",
  "party_id": "pty_0123456789abcdef0123456789abcdef",
  "applicant_role": "network_participant",
  "wallet_id": "wal_0123456789abcdef0123456789abcdef",
  "origin": "efaas",
  "currency": "ZMW",
  "purpose": "inventory",
  "amount_minor": 1500000,
  "term_days": 90
}

The response is 202 Accepted with status pending_review. Amounts use minor units: 1500000 means K15,000.00 for ZMW. Use made-up customer details and test data only.

7.3 Read the Outcome

GET {host}/v1/credit/applications/{application_id}
Authorization: Bearer <token with credit:read>

The same tenant can read its application. Current public states are pending_review, offered, accepted, declined, and cancelled. Credit Analyst review is an internal staff operation and requires a recorded reason; there is no automatic approval model in this release.

7.4 Accept an Offer

POST {host}/v1/credit/applications/{application_id}/accept
Idempotency-Key: <required>
Authorization: Bearer <token with credit:write>

Acceptance records agreement to an offer that is still valid. It does not release money or start the loan. Funding needs separate approval and a confirmed payment.

7.5 Not Yet Public

Credit limits, decision-detail endpoints, appeals, analyst queues and funding controls are not public tenant endpoints. Do not build against examples for those capabilities until they appear in the executable sandbox OpenAPI document.

8. Commerce Finance API

Status: Sandbox available

Record delivery of goods or services linked to an approved financing account, and report delivery disputes.

8.1 Register a Fulfillment

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

// Request
{
  "facility_id": "fac_8b2a1d3e",
  "recipient_participant_id": "npt_supplier_01",
  "currency": "ZMW",
  "items": [
    { "description": "50kg maize seed, 200 units", "value": "12000.00" }
  ],
  "delivery_confirmed_at": "2026-07-22T14:00:00Z",
  "evidence": [
    { "document_id": "doc_delivery_01", "type": "delivery_note" }
  ]
}

// Response
{
  "id": "cfl_8b2a1d3e000000000000000000000",
  "facility_id": "fac_8b2a1d3e",
  "status": "confirmed"
}

8.2 Check Fulfillment Status

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

status is confirmed, disputed, or cancelled. List with GET /v1/commerce/fulfillments using cursor pagination. Results are isolated to both the tenant and calling application.

The financing account must first become eligible through the normal loan process. Recording a delivery does not approve credit, pay the supplier, verify the documents or change the repayment schedule (§10).

8.3 Disputing a Fulfillment

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

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

The sandbox records the dispute and sends a traceable update. It does not automatically resolve the dispute or move real money.

9. Payments API

Status: Sandbox available — incoming and outgoing payments use test providers; live bank and mobile-money payments are disabled

Use this API for payments into or out of MightyFin. Use the Wallet API for transfers between MightyFin wallets.

9.1 Collections — Bringing Money In

Requires payments:write. The request is accepted asynchronously; it does not create a wallet or ledger posting.

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

{
  "amount": "5000.00",
  "currency": "ZMW",
  "payment_method": { "type": "mobile_money", "provider": "mock", "channel_reference": "260971234567" },
  "purpose": "wallet_deposit"
}

payment_method.type describes the channel. In sandbox, set payment_method.provider to mock; live provider adapters are deliberately disabled until separately certified. purpose is supplied by the caller and is preserved as instruction context.

9.2 Disbursements — Sending Money Out

Requires payments:write. A source_wallet_id is required. Before dispatching the mock-provider instruction, sandbox Payment Rails places an authoritative hold on that wallet. A failed instruction releases the hold; a successful instruction is posted only after matching provider evidence is reconciled. This exercises the accounting controls without moving real money.

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

{
  "amount": "2000.00",
  "currency": "ZMW",
  "source_wallet_id": "wal_9f8a2b1c",
  "purpose": "participant_cashout",
  "payment_method": { "type": "mobile_money", "provider": "mock", "channel_reference": "260971234567" }
}

Use GET {host}/v1/payments/{payment_id} with payments:read to inspect an instruction. A provider callback supplies the evidence required for settlement; see §11.

9.3 Bulk Payouts

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

{
  "source_wallet_id": "wal_2b6f0a91",
  "partner_reference": "payroll-2026-08",
  "expected_total": "1250.00",
  "currency": "ZMW",
  "items": [
    { "reference": "worker-001", "destination_wallet_id": "wal_1a2b3c4d", "amount": "500.00" },
    { "reference": "worker-002", "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
{
  "id": "pob_3c4d5e6f",
  "status": "processing",
  "item_count": 2,
  "expected_total": "1250.00",
  "currency": "ZMW"
}

This is a wallet-to-wallet sandbox payout batch. It is not an external mobile-money or bank disbursement.

9.4 Reference Data

Supported networks and banks: §16 Reference Data.

10. Billing & Collections API

Status: Sandbox available

Use Loan Collections for repayments on funded loans. Use Billing for invoices and other money your customers owe your business. Keep these separate. The origin field records where the request came from, for example efaas.

10.1 Repayment Schedule

GET {host}/v1/repayments/facilities/{facility_id}/schedule

{
  "facility_id": "fac_4a1c9e02",
  "origin": "efaas",
  "product_policy_id": "merchant_credit",
  "obligation_type": "loan_facility",
  "allocation_strategy": "loan_installment",
  "installments": [
    {
      "due_date": "2026-08-15",
      "due": { "principal": "1200.00", "interest": "80.00", "fees": "0.00", "penalty": "0.00", "total": "1280.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/facilities/{facility_id}/payments
Idempotency-Key: <required>

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

10.3 Billing — 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/billing/receivables
Idempotency-Key: <required>

{
  "participant_id": "npt_4a1c9e02",
  "destination_wallet_id": "wal_86e1c030",
  "amount": "3000.00",
  "currency": "ZMW",
  "due_date": "2026-08-01",
  "reference": "Invoice #INV-2201",
  "origin": "ef",
  "origin_reference": "partner-order-2201",
  "obligation_type": "service_invoice",
  "allocation_policy_version": 1
}

// Response
{
  "id": "rcv_5f0a2b3c000000000000000000000000",
  "status": "pending",
  "amount": "3000.00",
  "allocation_strategy": "billing_balance"
}

GET {host}/v1/billing/receivables/{receivable_id}

status is pending, collected, or overdue. Collected money goes to your business’s wallet. It is separate from a loan repayment.

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/batches
Idempotency-Key: <required>

{
  "declared_total": "480000.00",
  "currency": "ZMW",
  "lines": [
    { "facility_id": "fac_11a", "source_wallet_id": "wal_11a", "amount": "15000.00" },
    { "facility_id": "fac_11b", "source_wallet_id": "wal_11b", "amount": "22000.00" }
  ]
}

11. Reconciliation API

Status: Sandbox available for external payment instructions — provider callbacks are internal; tenants reconcile only their own successful instructions

Check that a successful payment matches the provider’s payment record. This check does not itself move money or update a wallet.

11.1 Submit Proof of Payment

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

{
  "evidence_id": "evd_0123456789abcdef0123456789abcdef",
  "settlement_reference": "bank-settlement-2026-07-01"
}

Requires payments:reconcile. Payment Rails verifies the payment is successful and the evidence amount and currency exactly match the instruction. A mismatch is rejected with 409 and creates a reconciliation exception for operational review.

11.2 Provider callbacks and exceptions

Providers call a signed internal callback endpoint. Partners cannot forge or submit provider evidence. An invalid signature, invalid status transition, changed replayed evidence, or a mismatch is rejected.

Tenant-scoped exception review is available with reconciliation:read and reconciliation:write:

GET  {host}/v1/reconciliation/exceptions
GET  {host}/v1/reconciliation/exceptions/{exception_id}
POST {host}/v1/reconciliation/exceptions/{exception_id}/claim
POST {host}/v1/reconciliation/exceptions/{exception_id}/resolve

Use the same request key when retrying claim or resolve, so the action is not repeated. They cannot create or alter provider evidence, and each request is limited to your business and the application making the call. Reversals, suspense handling, and live-provider operations remain controlled production capabilities.

12. Risk & Decisioning

Status: Sandbox available through the Credit API — manual Credit Analyst decisions only

MightyFin assesses the application. Your platform uses the Credit API to submit it and read the result.

12.1 Current Decision Model

Every sandbox application enters pending_review. An authorised Credit Analyst reviews the case and records an offer or a decline, with a reason and a history that cannot be silently changed. The offer uses the selected product’s rules and prices.

No AI model, automatic approval threshold or automated decline is active. Future automation must be separately versioned, tested and approved, and must retain its inputs and reason codes.

12.2 Tenant-Visible Outcome

Tenants retrieve the current outcome using:

GET {host}/v1/credit/applications/{application_id}

The application is tenant-isolated. Internal analyst queues, policy administration, risk evidence, appeals and exposure-management endpoints are not part of the public sandbox contract.

12.3 Separation from Money Movement

An offer does not release money. After the customer accepts, MightyFin must separately approve funding and confirm the payment before the loan becomes active.

13. Notifications API

Status: Sandbox available — approved in-app templates only

Request a message using an approved template. In the sandbox, you cannot send free-text messages or supply email addresses or phone numbers.

13.1 Queue a Notification

POST {host}/v1/notifications
Idempotency-Key: <required>
Authorization: Bearer <token with notifications:write>

{
  "recipient_id": "npt_0123456789abcdef0123456789abcdef",
  "template": "repayment.due",
  "channel_preferences": ["in_app"],
  "data": {
    "facility_id": "fac_0123456789abcdef0123456789abcdef",
    "amount": "2466.67",
    "currency": "ZMW",
    "due_date": "2026-09-30"
  }
}

Approved templates are credit.application.offered, credit.application.declined, repayment.due, repayment.overdue, and payment.received. Each template accepts only its documented variables. The recipient must be a platform identifier.

13.2 Dispatch Status

GET {host}/v1/notifications/{notification_id}
Authorization: Bearer <token with notifications:read>

Statuses are queued, dispatched, or dispatch_failed. dispatched means the message was passed to the delivery service—not that the recipient received or read it.

13.3 Reliability and Boundaries

You can send messages only within your business and application permissions. Retry the same request with the same key to avoid duplicates. Failed deliveries can be retried, but a message failure does not cancel or change the related payment.

Email and SMS remain unavailable through this API until trusted recipient resolution, consent, channel policy and provider controls are released.

14. Webhooks

Status: Existing sandbox delivery controls; application-scoped management, secret rotation and credit/payment/commerce/Wallet-transfer event bridges are pending coordinated deployment/UAT. Verify the deployed contract before relying on them.

Register a webhook URL to receive supported updates. You can also use the relevant GET API to check the latest status. Registering a webhook does not mean every planned update type is available.

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/deliveries/{delivery_id}/replay
Idempotency-Key: <required>

Only a dead-letter delivery for an active endpoint can be replayed. The first accepted replay returns 201; retrying the same request with the same idempotency key returns the same delivery and Idempotent-Replayed: true.

14.3 Event Types

Event	Fires when
participant.updated	Tenant-owned participant relationship fields change
participant.suspended	Your tenant suspends its relationship with a participant
participant.reactivated	Your tenant reactivates its participant relationship
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 Handle repeated updates safely

Every delivered event envelope carries a stable id. Treat a repeated id as a no-op — occasional redelivery is expected. The delivery-management API calls this reference event_id; it is not a second event identity. Arrival order is not guaranteed: retrieve current authorized resource state before acting on delayed status events.

14.5 Managing Endpoints

The application-scoped implementation accepts client-credentials tokens with webhooks:manage. Workloads can manage only their own application's endpoints and deliveries; the API does not accept an arbitrary target application ID in the body. Authorized human administrators retain their existing role-controlled access. This does not grant production access or bypass approval.

GET   {host}/v1/webhooks/endpoints
POST  {host}/v1/webhooks/endpoints
DELETE {host}/v1/webhooks/endpoints/{id}
POST   {host}/v1/webhooks/endpoints/{id}/secret-rotation/prepare
POST   {host}/v1/webhooks/endpoints/{id}/secret-rotation/activate

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

Store the one-time signing secret securely. Prepare rotation with a reason, configure the receiver with the returned secret, then activate with secret_version and reason. Preparing does not replace the active key. A secret is never redisclosed on retry; inspect endpoint state after a lost response. An expired pending rotation must be prepared again. Sandbox test requests target only the selected endpoint and return 202 Accepted; production does not accept synthetic test events.

The credit status bridge exposes only application ID, status and lifecycle action. Internal analyst notes and risk rules are excluded. Your business remains responsible for emails and SMS to your customers.

Payment completion requires reconciliation and, where the payment targets a Wallet, confirmed Wallet posting. Provider acceptance alone is not completion. A failed payment does not prove a refund or hold release has completed; retrieve current payment details and follow recovery status. Payment event data contains payment_id, direction, status, amount, currency, and an optional wallet_transaction_id. Amounts are decimal strings. Provider evidence and internal routing data are not included. Other shared-service event families still require deployment verification.

14.6 Transfer and Fulfilment Updates

These updates passed internal tests but still need release and testing through the public APIs. Your application receives them without depending on the MightyFin dashboard.

Event	Public data	Meaning
wallet.transaction.completed	transaction_id, status, operation, amount, currency	For the shared Wallet transfer path, operation is transfer and the ledger posting has committed. This is not external bank settlement.
commerce.fulfillment.confirmed	fulfillment_id, status	A delivery confirmation with supplied document references was recorded. It does not certify document contents or prove a merchant was paid.
commerce.fulfillment.disputed	fulfillment_id, status	A dispute was recorded. It does not automatically refund or reverse funds.

Shared Wallet transfer notifications are routed to the initiating tenant application. Other applications do not receive them merely because they belong to the same organisation. Internal Wallet events, document references, dispute notes and routing credentials are not included.

For acceptance testing, register a callback through the public webhook API, make a sandbox transfer through POST /v1/wallets/{wallet_id}/transfers, and match the returned transaction ID to the signed event. Retry the same request with its original key, test an insufficient-balance case, and verify another tenant/application receives nothing. No MightyFin dashboard is needed for this integration test. Redelivery can occur; deduplicate the event envelope's id.

15. Reports API

Status: Sandbox available — transaction totals and credit exposure

Read payment totals and loan balances for your business. The reports use the payment and loan-account records; they do not calculate separate versions of the balances.

15.1 Transaction totals

GET {host}/v1/reports/transactions?from=2026-08-01&to=2026-08-31

The period is UTC, both supplied dates are inclusive, and the maximum range is 366 days. Results are grouped by direction and currency. Requested, provider-succeeded, reconciled, and failed totals are separate. Use reconciled_amount when you need the amount supported by matching settlement evidence; a provider succeeded status alone is not presented as reconciled money.

15.2 Credit exposure

GET {host}/v1/reports/credit-exposure?owner_id={participant_id}&as_of=2026-09-07

owner_id is optional; omit it for all facilities owned by your tenant. The response separates outstanding principal, interest, fees, and penalties, plus the amount due and overdue on the selected date. Only servicing accounts produced by a disbursed facility are included—pending credit applications are never counted as exposure.

The optional as_of field currently accepts only today’s date in UTC. Reports for earlier dates are not available yet. A past date returns an error rather than showing today’s balance as if it were historical.

15.3 Not yet available

Scheduled report emails, custom report builders, live data and bulk downloads are not available yet.

16. Reference Data

Status: Sandbox available — empty lists mean no provider or programme is enabled

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 product list described in §7.1, grouped by product bundle. Where an API asks for programme_code, use a value from this list rather than inventing one.

17. Error Handling

Status: Available — workload API errors; OAuth uses a separate error format

17.1 Error Response Shape

Errors from application API calls use this format:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "correlation_id": "cor_example"
  }
}

Use HTTP status and error.code for automated handling. Show error.message to the user; use error.code, not the message wording, in your program’s error handling. Include the correlation ID when contacting support; never include credentials or access tokens. Numeric errorCode and errorDescription are not the workload API contract.

The OAuth token endpoint can return the identity provider's OAuth shape (error as a string and optional error_description). Handle this separately. Gateways can also return non-JSON errors: check content type and HTTP status before parsing.

17.2 HTTP Status Codes

Status	Handling
400	Correct invalid parameters before retrying.
401	Check credentials/token expiry and obtain a valid token.
403	Check application grants and requested token scopes; do not retry unchanged.
404	Resource or route does not exist, or is not visible to this tenant.
409	Resolve the conflict, including an idempotency key reused with a different body.
422	Resolve business validation or an invalid workflow transition.
429	Respect Retry-After when provided and back off.
500, 502, 503, 504	Treat the outcome as potentially uncertain; check the payment or loan status before sending the same request again.

17.3 Retry Safety

For a retry of the same financial operation, preserve its original Idempotency-Key and request body. A timeout does not prove the operation failed. Retrieve its status where available before retrying. Do not generate a new key merely to bypass a conflict.

For temporary failures, wait longer between retries, add a small random delay and stop after a set number of attempts. Do not repeatedly retry validation, permission or workflow errors. Unknown error codes must have a safe fallback; no numeric domain ranges are reserved by this documentation.

18. Security & Infrastructure

Status: Sandbox available — live service targets still need agreement and testing

18.1 Access Control

Keep your business’s credentials private. Never share them with another business. 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 customers’ personal information in your own systems any longer than necessary.

18.3 Availability

Production availability targets, maintenance notices and incident channels must be confirmed in your approved service agreement. Sandbox operation is not evidence of a production SLA. No public status hostname is certified by this guide.

18.4 Rate Limits

A fixed public per-client quota has not been certified. Do not assume a sandbox or production requests-per-minute allowance. Respect 429 responses and Retry-After when supplied; wait longer between retries, add a small random delay and stop after a set number of attempts. Confirm contracted limits and load-test thresholds before launch.

18.5 Check how your integration is working

Sandbox available. Requires the observability:read scope.

GET {host}/v1/observability/summary

Shows how many requests your application made, which succeeded or failed, which were retries, and how long they took. p95 is the time within which 95% of requests finished. It also shows payment-matching problems: new, resolved and still unresolved, including older problems. The default period is 24 hours; the maximum is 30 days.

Telemetry is isolated by tenant, environment, and application. It stores only the HTTP method, normalized route pattern, status, duration, replay flag, and timestamp. Raw URLs, query values, request or response bodies, tokens, and participant identifiers are not stored.

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

Status: Sandbox available — generated artifacts contain implemented routes only

19.1 Postman Collection

The fastest way to explore the API without writing code:

https://efaas.mightyfinance.co.zm/sandbox/v1/postman-collection.json

Import directly into Postman or Insomnia. The collection and runtime OpenAPI document are generated from the same deployed-operation manifest, so both contain the complete public sandbox route list. Calls that require an authorised person to sign in are marked separately from calls your server can make using its Client ID and secret.

19.2 Client Libraries

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

Use any standard HTTP client for APIs marked available. Planned APIs cannot be tested until released.

19.3 OpenAPI Specification

GET https://efaas.mightyfinance.co.zm/sandbox/v1/openapi.json

Machine-readable spec covering the endpoints currently implemented in the sandbox. Target-only sections of this guide are intentionally excluded.

19.4 Run the integration tests

Ask MightyFin for the Node.js test package for your API version. It checks API sign-in, separation of businesses’ records, customer registration and updates, safe retries, test wallet transfers and payment status.

The client requires a tenant's own sandbox credentials and never prints or stores the secret or access token. It creates synthetic test records only. Ask the integration team for the released certification package corresponding to the deployed API version.

Glossary

Status: Available

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	A proposed shared borrowing limit across products. Do not assume it is available; check the product and release status.
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	An update sent to your registered URL. Verify its signature. Updates may be delayed or repeated. See Webhooks.
Sandbox	A separate environment using test people and test money. It does not move real money or invoke enabled production rails. Access follows tenant onboarding and sandbox credential provisioning.
Live	The live environment, which needs separate approval. Availability requires separate organizational, technical, legal/compliance and capability-specific approval; KYB/UBO completion alone is insufficient.
Scope	A permission for an API call, included in 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	Identifies one logical action on operations that support replay. Follow the operation's required headers, reuse the same key and body for retries, and use GET for current state.
Value Chain Role	The category describing a partner's position in its ecosystem — manufacturer_producer, distributor, aggregator_offtaker, or service_agency.
error.code / error.message	Workload API error fields inside the error object. Use the code and HTTP status for handling, and error.correlation_id for support. OAuth errors use a separate OAuth response shape.

API Availability & Delivery Roadmap

Status: Current sandbox capability map — last reconciled 7 September 2026

These guides include available APIs and planned features. An example does not mean an API is ready. Check the current sandbox API list before building a feature:

GET https://efaas.mightyfinance.co.zm/sandbox/v1/openapi.json

Available now in sandbox

Area	What tenants can integrate
Authentication	Exchange your Client ID and secret for an API access token
Participants	Register, find, update, suspend and reactivate test customers in your network
Verification	Choose a test identity-check result; this does not verify a real person
Documents	Request participant document upload sessions when the application has the document permission
Wallets	Read test ZMW wallets and page through their transactions
Sandbox funding	Add test money, not real money
Transfers	Transfer test money between wallets and retry safely
Payments & reconciliation	Test incoming and outgoing payments, check their status and match them with provider records
Payouts	Send a group of test wallet payments and check each result as it completes
Reference data	Read sandbox code lists; an empty list means no corresponding provider or programme is enabled
Webhooks	Authorized tenant users can register endpoints, run sandbox tests, inspect attempts and replay eligible failures
Products	Find available products and check whether a request fits their terms
Credit	Submit a test application, follow staff review and accept an offer before it expires
Notifications	Queue approved in-app templates for platform recipients and inspect dispatch status
Observability	Check your application’s API successes, failures and unresolved payment-matching problems

Partially available

Area	Available	Not yet callable
Participants	Relationship lifecycle and verification simulation	Business profile
Identity	Verification simulation and document upload authorization	Live KYC/KYB and screening providers
Wallets	Synthetic wallet, journal, funding and transfer	Production funds, statements, guarantees and external rails
Payments	Mock external collection/disbursement lifecycle, authoritative wallet holds, explicit evidence reconciliation and post-reconciliation wallet settlement	Live bank/mobile-money provider adapters, reversals and suspense workflows
Billing & Collections	Facility schedules, repayment allocation, penalty accrual, batches and tenant receivables	Production collection rails and controlled recovery operations
Commerce Finance	Evidence-backed fulfilment registration, tenant-safe reads and dispute opening	Production dispute operations and any controlled downstream remediation
Reports	Reconciled payment totals and authoritative facility exposure	Scheduled delivery, bulk downloads and production data

Planned features—not available yet

These sections describe planned features. Do not rely on these API examples for a live launch yet:

• Partners API

Delivery sequence

1. Finish integration testing — check API instructions, webhook access and the full sandbox journeys. Business onboarding already exists.
2. Connect live payment providers — test wallet updates, held payments, reversals and bank or mobile-money connections before enabling real payments.
3. Credit decisions — test applications, staff decisions and offers are available. Public limit management, appeals and automatic decisions are not yet available.
4. Billing and collections — test billing is available. Live collections and debt-recovery actions still need release and approval.
5. Goods finance — test delivery records and disputes are available. Live dispute handling is not yet available.
6. Notifications — approved in-app messages can be tested. Email and SMS still need recipient, consent and delivery checks.
7. Reports — test transaction totals, loan balances and API health reports are available. Scheduled emails, bulk downloads and live reports are not yet available.

Before a feature is released, its instructions must explain permissions, safe retries, updates and availability, with completed tests.

Integration rule

Application client credentials are server-to-server secrets. Never embed a client secret in a web or mobile application. Browser-facing products should call the tenant's own backend, which then calls EFaaS using securely stored credentials.