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 £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",
        "first_payment_due_value": 0,
        "first_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"
      },
      {
        "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.10",
        "first_payment_due_value": 0,
        "first_payment_due_unit": "days",
        "apr": "12.90%",
        "annual_interest_rate": "12.90%",
        "number_of_repayments": 83,
        "monthly_repayment": "162.49",
        "cost_of_credit": "4593.72",
        "total_amount_payable_excluding_deposit": "13593.72",
        "merchant_finance_url": "https://xyzsolar.co.uk/finance?loan_amount=9000.00&customer_deposit=1000.00&credit_product=hu1290-084M"
      }
    ],
    "deposit_adjustment": {
      "requested_deposit": "1000.00",
      "corrected_deposit": "2500.00",
      "adjustment_reason": "Minimum 25% deposit required.",
      "affected_products": [
        "36 months (0% APR Interest Free Credit)"
      ]
    }
  }
}
  • 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)​

Image example temporarily unavailable in this docs build.

  • 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)​

Image example temporarily unavailable in this docs build.

  • 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?​