Skip to main content

Partner API Internal Overview

There is no Partner API quotes page in the admin left nav. Operators copy keys and run quotes from Users, Lenders, and the merchant Quote tab. Credit-application push webhooks are a separate left-nav item: Partner webhooks. Do not start from cloud-run/partner-api/.

Operator surfaces​

  1. Partner webhooks (https://admin.finmatch.io/partner-webhooks/). Endpoints, merchant consent, signing keys (shown once), test notification, Partner webhook deliveries. Requires admin:partner-webhooks. Partner webhooks

  2. Users (https://admin.finmatch.io/users/). Partner rows: Copy reveals the partner API key after the admin password prompt. Do not paste the value into /docs/. Users

  3. Lenders → a lender → API. API Playground Send Request posts to https://api.finmatch.io/v1/finance-quote. Paste the key only in Authorization Bearer Key. Lender API

  4. Merchant → Admin → Quote. Request quotes compares Partner API against lender and runtime. Quote comparison

Quotes return products only for humm, Snap, Propensio, and Zopa. Other catalogue lenders stay filtered even when assigned on the merchant.

This page is also the single internal source of truth for where the service is configured. Partner-facing docs stay in developer-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/

Scope​

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

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.
  • Partner API quotes read merchants.json. Test keys and live keys use the same file. Cloudflare KV Finance Assistant key pairing is not on this path. Sandbox preview is a different system.

Incomplete FOS profile​

Representative examples fail with MERCHANT_CONFIGURATION_INCOMPLETE and missing finance_offer_summary when the merchant profile template string is empty. Assigned credit products and Finance offer summary enabled (storefront embed / badge only) do not fill that field. Save the strings on the Overview Finance Offer Summary card, or Save credit products so they seed.

Do not paste Partner API keys, Finance Assistant keys, or Cloudflare tokens into /docs/.

Operator training: Finance offer summary settings.

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. Partner API currently returns products for humm, Snap, Propensio, and Zopa (partner-api-lenders-config.json enabled: true). Other catalogue lenders stay filtered out until they are enabled there.
  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.

For Not authorised merchants the quote is still 200 OK with empty products and products_notice.code MERCHANT_FCA_NOT_AUTHORISED. The FCA empty-products path applies the merchant deposit floor (explicit merchantMinimumDeposit, or inferred from uniform per-product rules) and includes data.deposit_adjustment when the requested deposit is below that floor (affected_products empty). Learn more uses the corrected deposit and loan. Authorised product quotes use max(merchant global, product rule) so a product/lender minimum cannot be lowered. Operator training: Merchant FCA status and Calculator deposit dropdown. Partner-facing contract: Non-regulated merchants.

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.

Live service: project finmatch-finance-mkt, region europe-west2. Ignore northamerica-northeast1 in legacy DEPLOY_NOW.md.

Cloud Run logs​

Use GCP Console or gcloud for Partner API quote traffic. This is not the admin Monitoring page.

  1. Open Google Cloud Console → project finmatch-finance-mkt.
  2. Cloud Run → finmatch-partner-api → Logs. The tab may also appear as Observability → Logs. Same service.

Two log streams:

StreamWhat it hasWhat it does not have
App stdout ([AUTH] / [QUOTE] / [ERROR])partner_id and merchant_idClient IP
Cloud Run request logs (run.googleapis.com/requests)httpRequest.remoteIpPartner / merchant ids

Join a stdout line to its request log with the shared trace field. The Logs table hides remoteIp until you open JSON or add that field (or group by httpRequest.remoteIp).

Console filters:

  • App lines: textPayload contains P000115 or M801688.
  • Request logs: POST and finance-quote.
  • Same live key from James vs a customer: compare remoteIp only. Playground quotes are partner_id P000001. Infinity’s live key is P000115.

Do not paste live remoteIp values, Authorization headers, Partner API keys, or Finance Assistant keys into /docs/. Do not dump full request headers.

Example gcloud (project finmatch-finance-mkt, region europe-west2):

gcloud logging read 'resource.type="cloud_run_revision"
  AND resource.labels.service_name="finmatch-partner-api"
  AND resource.labels.location="europe-west2"
  AND textPayload:"M801688"' \
  --project=finmatch-finance-mkt --limit=50 \
  --format='value(timestamp,textPayload)'

gcloud logging read 'resource.type="cloud_run_revision"
  AND resource.labels.service_name="finmatch-partner-api"
  AND logName:"run.googleapis.com%2Frequests"
  AND httpRequest.requestMethod="POST"
  AND httpRequest.requestUrl:"finance-quote"' \
  --project=finmatch-finance-mkt --limit=20 \
  --format='value(timestamp,httpRequest.remoteIp,httpRequest.status,trace)'

Empty profile FOS strings are a different failure: Incomplete FOS profile.

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.