Skip to main content

Partner API Internal Overview

This page is the single internal source of truth for how the FinMatch Partner API works, where it is configured, and which docs are canonical for operations and maintenance.

This is intentionally separate from partner-facing documentation in developer-docs/.

Scope​

  • Internal operations and admin workflows for Partner API.
  • Runtime architecture and data flow.
  • Deployment and routing ownership.
  • Canonical internal docs vs legacy docs.

What the Partner API Is​

  • Service: finmatch-partner-api (Cloud Run)
  • Public domain path: https://api.finmatch.io/api/v1/*
  • Main endpoint: POST /api/v1/finance-quote
  • Code location: cloud-run/partner-api/

Merchant IDs And Key Boundaries​

  • Merchant IDs are identifiers (not secrets), but should still be treated as controlled metadata.
  • Partner quote requests are protected by partner bearer authentication and partner ID validation.
  • Finance Assistant submission/start-application auth is a separate path and uses merchant-scoped keys via auth/proxy.
  • A merchant being quotable in Partner API does not imply Finance Assistant key provisioning is complete.

Runtime Flow (Internal)​

  1. Request hits api.finmatch.io and is routed by load balancer path rules to partner-api-backend.
  2. cloud-run/partner-api/index.js handles auth, validation, merchant lookup, and lender filtering.
  3. Rate card data is sourced from credit products API (currently humm products are active in Partner API config).
  4. cloud-run/partner-api/lib/finance.js builds summary and products.
  5. Response returns normalized finance products, deposit adjustments (if applicable), and merchant deep links.

Finance Assistant Relationship (Important)​

  • financeAssistantApiKey is used for Finance Assistant workflows (enquiry submission and lender start flows), not for quote calculations.
  • In proxy mode, frontend sends payload to proxy and proxy injects merchant bearer token server-side.
  • Missing Finance Assistant key can break enquiry/start side effects while quote retrieval still succeeds.

Key Internal Components​

Service Code (Primary)​

  • cloud-run/partner-api/index.js - request lifecycle and endpoint handlers
  • cloud-run/partner-api/lib/finance.js - product shaping and quote response generation
  • cloud-run/partner-api/lib/cache.js - merchant/config cache loading
  • cloud-run/partner-api/lib/auth.js - API key auth
  • cloud-run/partner-api/lib/validation.js - payload validation
  • cloud-run/partner-api/lib/humm-api-logic.js - humm-specific normalisation
  • cloud-run/partner-api/partner-api-lenders-config.json - Partner API lender allow-list

API Contract (External-Facing, but Operationally Critical)​

  • cloud-run/partner-api/openapi.yaml - contract/source of truth for schema
  • cloud-run/partner-api/README.md - endpoint usage and examples

Routing and Platform Ownership​

  • platform/load-balancer-url-map.yaml - host/path routing rules
  • platform/LOAD_BALANCER_CONFIG.md - load balancer operational guide
  • platform/api/README.md - API site context; clarifies Cloud Run vs GCS ownership

Deployment and Release Ownership​

Canonical Deployment Sources​

  • .github/workflows/partner-api-deploy.yml - CI/CD deployment flow
  • cloud-run/partner-api/SETUP_GUIDE.md - most complete manual setup and infra flow
  • cloud-run/partner-api/DEPLOY_WITH_GITHUB_ACTIONS.md - GitHub Actions operational guidance

Current URL Source of Truth​

Current Cloud Run URL should be sourced from:

gcloud run services describe finmatch-partner-api --region europe-west2 --format="value(status.url)"

Do not hardcode *.run.app hostnames as canonical production references unless explicitly required for diagnostics.

Data Sources​

  • Credit product source API (all lenders):
    • https://credit-products-api-238644427841.europe-west2.run.app/api/v1/credit-products
  • Current lender-specific source (humm):
    • https://credit-products-api-238644427841.europe-west2.run.app/api/v1/credit-products?lender=humm

Documentation Consolidation Policy​

Use this page as the internal entry point. Treat the following as canonical and everything else as supporting or legacy.

Canonical Internal Docs (Keep)​

  • admin-docs/docs/partner-api/overview.md (this page)
  • cloud-run/partner-api/SETUP_GUIDE.md
  • cloud-run/partner-api/ARCHITECTURE.md
  • cloud-run/partner-api/LENDER_LOGIC_README.md
  • cloud-run/partner-api/LENDER_CONFIG_README.md
  • cloud-run/partner-api/URL_ARCHITECTURE.md
  • platform/LOAD_BALANCER_CONFIG.md

Legacy or Overlapping Internal Docs (Reference Only)​

  • cloud-run/partner-api/START_HERE.md
  • cloud-run/partner-api/QUICK_START.md
  • cloud-run/partner-api/README_DEPLOYMENT.md
  • cloud-run/partner-api/DEPLOYMENT.md
  • cloud-run/partner-api/DEPLOY_FROM_REPO.md
  • cloud-run/partner-api/DEPLOY_NOW.md
  • PARTNER_API_DEPLOYMENT.md
  • cloud-run/partner-api/COMMANDS_COPY_PASTE.md
  • cloud-run/partner-api/deployment-summary.txt
  • cloud-run/partner-api/REPO_DEPLOYMENT_SUMMARY.txt

When editing internals, update canonical docs first and only back-port to legacy docs if needed.

Out of Scope (Do Not Consolidate Here)​

Partner-facing docs are maintained separately in:

  • developer-docs/

That documentation remains the source for external/end-user developer guidance.