Skip to main content

Getting Started

Get up and running with the FinMatch Partner API in under 5 minutes.

Prerequisites​

Before you begin, you'll need:

1. Partner credentials: Email partners@finmatch.io to request your partner_id (format: P000000) and API key (format: sk_apikey).

2. Merchant ID: We provide the merchant_id (format: M0000000) securely to partners upon merchant signup. Lock this field in your merchant settings—merchants never see or change it. We'll email it from partners@finmatch.io.

Make Your First Request​

Send a POST to https://api.finmatch.io/v1/finance-quote with your credentials.

Example Request​

curl -X POST https://api.finmatch.io/v1/finance-quote \
  -H "Authorization: Bearer sk_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://xyzsolar.co.uk/finance"
}'
  • Always use HTTPS.
  • customer_deposit defaults to 0.00 or minimum deposit amount when left blank.

Example Response​

A successful response (200 OK) returns a finance offer summary and full rep examples:

{
  "success": true,
  "data": {
    "summary": {
      "display": true,
      "finance_offer_summary": "FLEXIBLE FINANCE including 0% APR or 12.9% APR options from £135.41/month. <a href=\"https://xyzsolar.co.uk/finance?loan_amount=7500.00&customer_deposit=2500.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.34,
        "apr": "0% Fixed",
        "annual_interest_rate": "0.00%",
        "number_of_repayments": 35,
        "monthly_repayment": 208.33,
        "cost_of_credit": 0,
        "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"
      },
      {
        "lender": "humm",
        "credit_product": "84 months (12.9% APR)",
        "purchase_price": 10000.00,
        "customer_deposit": 1000.00,
        "loan_amount": 9000.00,
        "first_payment_type": "upfront_instalment",
        "first_payment_amount": 107.14,
        "apr": "12.9%",
        "annual_interest_rate": "12.9%",
        "number_of_repayments": 83,
        "monthly_repayment": 162.49,
        "cost_of_credit": 4593.72,
        "total_amount_payable_excluding_deposit": 13593.72,
        "total_amount_payable": 14593.72,
        "url": "https://xyzsolar.co.uk/finance?loan_amount=9000.00&customer_deposit=1000.00&credit_product=hu1290-084M"
}
    ],
    "deposit_adjustment": {
      "requested_deposit": 1000,
      "corrected_deposit": 2500,
      "adjustment_reason": "Minimum 25% deposit required."
    }
  }
}
  • Always display finance_offer_summary below/next to the quote total for a simple, ready-to-embed summary.
  • If you don't want to display full rep examples, ignore data.products.
important

When displaying finance_offer_summary or any data.products, ensure you include the required FCA disclosure text if offers include credit >0% APR or >12 months (e.g., "XYZ Renewables Limited is a credit broker, not a lender. We are authorised and regulated by the Financial Conduct Authority (firm reference number: XXXXXX).").

The merchant will supply this text.

Testing​

Use the test merchant_id to recieve a mock response:

{
  "merchant_id": "M000100"
}

Go to Testing for the full list of test merchants.

Examples of a Finished Integration​

Here are some examples for how partners can display the finance offer summary and full rep examples:

Finance Offer Summary (always display)​

Finance Offer Summary

  • Always display the finance_offer_summary below/next to the quote total.
  • The summary is 80 characters or less.
  • Partners are responsible for displaying the FCA disclosure text. This text is provided by merchants.

Full Rep Examples (optional to display)​

Full Rep Examples

  • Partners can optionally display individual credit products. Our response container returns all necessary information.
  • Ensure all information is shown with equal prominence to comply with FCA guidelines.
  • Partners may need to append their own text to the full rep examples.
    • Example: text string containing "(excluding customer deposit)" is not returned in the container.

Next Steps​

Need Help?​