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

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`
`apr`	string	APR including % symbol and type (Fixed or Variable)	`"9.90% Fixed"`
`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 including 0% APR or 12.9% APR options from £152.97/month – <a href=\"https://www.xyzsolar.co.uk/finance\">Learn more</a>"
    },
    "products": [
      {
        "lender": "humm",
        "credit_product": "36 months Interest Free Credit (0% APR)",
        "purchase_price": 5500.00,
        "customer_deposit": 500.00,
        "loan_amount": 4500.00,
         "first_payment_type": "Upfront Instalment",
         "first_payment_amount": 0.00,
        "apr": "0%",
        "annual_interest_rate": "0%",
        "number_of_repayments": 36,
        "monthly_repayment": 125.00,
        "cost_of_credit": 0.00,
        "total_amount_payable_excluding_deposit": 4500.00,
        "url": "https://www.xyzsolar.co.uk/finance/?loan_amount=4500.00&customer_deposit=500.00&credit_product=hu0000-036M"
      }
      // Additional products if multiple offers available
    ]
  }
}

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​

Need Help?​

Endpoint URL

Need Help?