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:

Amounts

Send amounts as strings with exactly two decimal places, for example "9000.00". Responses return amounts the same way. JSON numbers such as 9000.00 are still accepted, but many JSON libraries drop the trailing zeros and store them as binary floating point, so strings are the exact form.

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`	string (2 decimal places)	Total amount the customer wants to finance. Numbers such as `9000.00` are also accepted.	`"9000.00"`
`customer_deposit`	string (2 decimal places)	Deposit amount used (defaults to `"0.00"`). May be overriden to meet minimum `customer_deposit`. Numbers are also accepted.	`"1000.00"`
`merchant_finance_url`	string (valid HTTPS URL)	Full URL to the merchant's finance page	`"https://www.xyzsolar.co.uk/finance"`
`merchant_reference`	string (optional, max 64 characters: letters, digits, space, `.`, `-`, `_`)	Your own quotation number. We store it with the quote and return it on every credit status notification. Ends are trimmed; an internal space is kept (for example `"TQ7 3PG"`). Never put customer details in it. Any other character returns `400`.	`"TQ7 3PG"`

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",
    "merchant_reference": "QB-10452"
  }'

Response Variables - Quote (always returned):

Field Path	Type	Description	Example
`data.finmatch_quote_id`	string	Unique id for this quote. Store it.	`"FMQ-7K2M9X4P3TQ8"`
`data.merchant_reference`	string or `null`	The `merchant_reference` you sent, echoed back (space kept).	`"TQ7 3PG"`

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`	string (2 decimals)	Total basket value	`"10000.00"`
`customer_deposit`	string (2 decimals)	Deposit amount used (defaults to 0.00). May be overriden to meet minimum `customer_deposit`)	`"1000.00"`
`loan_amount`	string (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`	string (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`	string (2 decimals)	Monthly payment amount	`"211.15"`
`cost_of_credit`	string (2 decimals)	Total interest over the term	`"3624.45"`
`total_amount_payable_excluding_deposit`	string (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"`

Send finance links exactly as returned

Finance links carry parameters that tie the customer's application back to your quote. Don't add, remove or reorder them, including merchant_reference. The quote id on the link is finmatch_quote_id; quote_id is still accepted.

Example Response:

{
  "success": true,
  "data": {
    "finmatch_quote_id": "FMQ-7K2M9X4P3TQ8",
    "merchant_reference": "QB-10452",
    "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=8000.00&customer_deposit=2000.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."
    },
    "deposit_adjustment": {
      "requested_deposit": "1000.00",
      "corrected_deposit": "2000.00",
      "adjustment_reason": "Minimum 20% deposit required.",
      "affected_products": []
    }
  }
}

data.deposit_adjustment is included when the requested customer_deposit is below the merchant's minimum deposit (a merchant-wide floor, or the uniform per-product rule when no global floor is set). The Learn more URL uses the corrected deposit and loan. affected_products is an empty array because this merchant has no product list. Omit deposit_adjustment when the requested deposit already meets the floor.

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?