API Reference

Complete reference for FinMatch Partner API variables and endpoint.

Endpoint URL

https://api.finmatch.io/v1/finance-quote

Retrieves real-time finance quotations for a customer purchase, including a simple finance offer summary for easy display and a detailed rep examples (optional to display).

note

Variable names have been designed for easy display. Remove "_" and capitalise variable names before displaying.

For example: customer_deposit becomes "Customer Deposit".

Authentication: Required (Bearer token via API key).

Request Variables:

These are the parameters sent in the JSON request body. All required fields must be included for a successful call.

Parameter	Type/Format	Description	Example
`merchant_id`	string	Unique identifier for the merchant	`"M000101"`
`partner_id`	string	Your unique partner identifier	`"P000001"`
`loan_amount`	number (2 decimal places)	Total amount the customer wants to finance	`9000.00`
`customer_deposit`	number (2 decimal places)	Deposit amount used (defaults to 0.00). May be overriden to meet minimum `customer_deposit`)	`1000.00`
`merchant_finance_url`	string (valid HTTPS URL)	Full URL to the merchant's finance page	`"https://www.xyzsolar.co.uk/finance"`

Example Request:

curl -X POST https://api.finmatch.io/v1/finance-quote \
  -H "Authorization: Bearer pk_apikey" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "M000100",
    "partner_id": "P000001",
    "loan_amount": 9000.00,
    "customer_deposit": 1000.00,
    "merchant_finance_url": "https://www.xyzsolar.co.uk/finance"
  }'

Response Variables - Finance Offer Summary (always display):

Field Path	Type	Description	Example
`success`	boolean	true if request succeeded	`true`
`data.summary.display`	boolean	true if finance offers are available and should be shown	`true`
`data.summary.finance_offer_summary`	string (HTML)	Ready-to-display FCA-compliant summary (max 80 characters)	`"FLEXIBLE FINANCE inc. 0% APR or 12.9% APR options from £152.97/month - <a href=\"https://www.xyzsolar.co.uk/finance?loan_amount=4500.00&customer_deposit=500.00\">Learn more</a>"`

Response Variables - Full Rep Examples (optional to display):

Note: This array is always returned but is an optional feature. If you do not want to display full rep examples, you can safely ignore data.products entirely. For some merchants the array can be legitimately empty — see Non-regulated merchants below — so never assume it contains at least one item.

Field (inside each item of `data.products[]`)	Type/Format	Description	Example
`lender`	string	Name of the lender	`"humm"`
`credit_product`	string	Description of the finance product	`"36 months Interest Free Credit (0% APR)"`
`purchase_price`	number (2 decimals)	Total basket value	`10000.00`
`customer_deposit`	number (2 decimals)	Deposit amount used (defaults to 0.00). May be overriden to meet minimum `customer_deposit`)	`1000.00`
`loan_amount`	number (2 decimals)	Total amount the customer wants to finance	`9000.00`
`first_payment_type`	string	Type of first payment taken	`"Upfront Instalment"`
`first_payment_amount`	number (2 decimals)	Amount of first payment taken	`166.60`
`initial_payment_due_value`	integer	The numeric value indicating when the initial payment is due	`30`
`initial_payment_due_unit`	string	The unit for the initial payment due timing	`"days"`
`apr`	string	APR including % symbol	`"9.90%"`
`annual_interest_rate`	string	Flat annual interest rate	`"9.90%"`
`number_of_repayments`	integer	Number of monthly payments	`59`
`monthly_repayment`	number (2 decimals)	Monthly payment amount	`211.15`
`cost_of_credit`	number (2 decimals)	Total interest over the term	`3624.45`
`total_amount_payable_excluding_deposit`	number (2 decimals)	Total repaid on the financed amount only (excludes deposit)	`12624.45`
`merchant_finance_url`	string (URL)	Deep-link to start application for this exact product	`"https://www.xyzsolar.co.uk/finance/?loan_amount=4500.00&customer_deposit=500.00&credit_product=hu0000-036M"`

Example Response:

{
  "success": true,
  "data": {
    "summary": {
      "display": true,
      "finance_offer_summary": "FLEXIBLE FINANCE inc. 0% APR or 12.9% APR options from £162.49/month. <a href=\"https://xyzsolar.co.uk/finance?loan_amount=9000.00&customer_deposit=1000.00\">Learn more.</a>"
    },
    "products": [
      {
        "lender": "humm",
        "credit_product": "36 months (0% APR Interest Free Credit)",
        "purchase_price": "10000.00",
        "customer_deposit": "2500.00",
        "loan_amount": "7500.00",
        "first_payment_type": "Upfront Instalment",
        "first_payment_amount": "208.33",
        "initial_payment_due_value": 0,
        "initial_payment_due_unit": "days",
        "apr": "0.00%",
        "annual_interest_rate": "0.00%",
        "number_of_repayments": 35,
        "monthly_repayment": "208.33",
        "cost_of_credit": "0.00",
        "total_amount_payable_excluding_deposit": "7500.00",
        "merchant_finance_url": "https://xyzsolar.co.uk/finance?loan_amount=7500.00&customer_deposit=2500.00&credit_product=hu0000-036M"
}
      // Additional products if multiple offers available
    ]
  }
}

Non-regulated merchants (empty products)

Some merchants are recorded on FinMatch as not FCA authorised to communicate regulated credit promotions. For these merchants the API still returns 200 OK with the same response shape, but:

data.summary.finance_offer_summary renders the merchant's non-regulated template — a plain headline plus the Learn more link, with no APR, monthly price, or offer figures.
data.products is an empty array (kept in the schema so existing integrations that iterate it do not break).
data.products_notice explains why the array is empty.

Field Path	Type	Description	Example
`data.products_notice.code`	string	Machine-readable reason code	`"MERCHANT_FCA_NOT_AUTHORISED"`
`data.products_notice.message`	string	Human-readable explanation of why `data.products` is empty	See example below

Example Response (non-regulated merchant):

{
  "success": true,
  "data": {
    "summary": {
      "display": true,
      "finance_offer_summary": "FLEXIBLE FINANCE <a href=\"https://xyzsolar.co.uk/finance?loan_amount=9000.00&customer_deposit=1000.00\">Learn more</a>"
    },
    "products": [],
    "products_notice": {
      "code": "MERCHANT_FCA_NOT_AUTHORISED",
      "message": "No products available for this merchant. Reason: merchant FCA status is Not authorised. Display the finance_offer_summary only."
    }
  }
}

Integration guidance: always display finance_offer_summary; render rep examples only when data.products is non-empty. data.products_notice is only present when the array is intentionally empty for compliance reasons — treat unknown future code values as "do not display products".

Status Codes:

Code	Description
`200`	Success - returns finance offers
`400`	Invalid Request
`401`	Unauthorized
`404`	Not Found
`429`	Rate limit exceeded
`500`	Internal server error

Need Help?

Examples: See the Examples page for code in multiple languages
Errors: Check the Error Handling page for common issues
Support: Email partners@finmatch.io

Endpoint URL​

Non-regulated merchants (empty products)​

Need Help?​

Endpoint URL

Non-regulated merchants (empty products)

Need Help?