Credit status notifications
When a customer applies from a finance link we returned on your quote — the Learn more link in finance_offer_summary, or a product merchant_finance_url — FinMatch sends a signed HTTPS POST to your saved webhook URL:
- the first time the lender responds (a raw status code)
- each time that status code changes, or
- when you send a test
Match each notification to the job in your system.
We also send credit status notifications (CSNs) via email. The email is separate from this webhook. Contact partners@finmatch.io with the email address(es) that you would like to receive them.
Events
| event_type | When |
|---|---|
credit_application.status_changed | The lender’s status changed. One event per change, none for repeats. |
credit_application.test | Sent on request so you can prove the endpoint works. Never about a real application. Do not update a job. |
Example notification
This is the JSON body we POST to you, not a response you send us.
{
"event_id": "CSN00000116-01",
"event_type": "credit_application.status_changed",
"timestamp": "2026-10-01T08:41:41.928Z",
"environment": "live",
"merchant_id": "M000106",
"merchant_reference": "QB-10452",
"finmatch_reference": "M000106-P000001-R00000001",
"lender": "zopa",
"lender_reference": "T3STREF1",
"credit_application_status": "CONDITIONALLY_APPROVED",
"loan_amount": "9000.00",
"deposit": "1000.00",
"purchase_price": "10000.00",
"credit_product": null
}
A test event uses "event_type": "credit_application.test" and dummy / null IDs. environment is sandbox or live according to the key (sk_test_ or sk_live_). It is not a real application.
Reference
| Field | Type | Description |
|---|---|---|
event_id | string | Unique per notification. Repeated on retry. Also in the FinMatch-Event-Id header. Example: CSN00000116-01. |
event_type | string | One of the events above. Also in the FinMatch-Event-Type header. |
timestamp | string (ISO 8601, UTC) | When this update occurred. Use it to order events. |
environment | string | live or sandbox. |
merchant_id | string or null | Merchant the application is under. |
merchant_reference | string or null | Your job / quote / estimate ID, if you sent one on the quote request. |
finmatch_reference | string | Our application ID. Always present. |
lender | string or null | Lender, for example zopa. |
lender_reference | string or null | The lender’s reference for this application. |
credit_application_status | string or null | Lender status, for example CONDITIONALLY_APPROVED. See Zopa statuses and Propensio statuses. |
loan_amount | string or null | Amount applied for, two decimal places, when the lender sends it. Zopa is also purchase price minus deposit when both are present and numeric. Not a final drawn-down amount. |
deposit | string or null | Deposit, two decimal places, when the lender sends it. |
purchase_price | string or null | Purchase price, two decimal places, when the lender sends it. |
credit_product | string or null | Credit product display name, when the lender sends it. |
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | FinMatch-Webhooks/1 |
FinMatch-Signature | t=<unix seconds>,v1=<hex>. During a key change there are two v1 values. See Verifying notifications. |
FinMatch-Key-Id | Which of your keys signed it. During a key change, both, comma-separated. |
FinMatch-Event-Id | Same as event_id |
FinMatch-Event-Type | Same as event_type |
FinMatch-Delivery-Attempt | 1 on the first try, then counts up |
FinMatch-Test | true on test events only |
Matching notifications
Match on merchant_reference and/or finmatch_reference. finmatch_reference is on every notification.
If the customer applies using a merchant_finance_url without our parameters attached, we cannot attribute the application to you. The application still runs. You do not get a webhook for it. The merchant may still get an email.
To minimise this, send finance links exactly as we return them. Do not add, remove or reorder query parameters.
Set up
1. Send us two HTTPS URLs
Email partners@finmatch.io:
Test: https://api.quotebuilder.example/finmatch/webhooks/test
Live: https://api.quotebuilder.example/finmatch/webhooks/live
Each URL must use https://, have a valid public certificate, have no query string and no username or password, resolve to a public address, and accept POST directly.
We do not follow redirects. Never put a secret in the URL.
2. Receive your signing secrets
One secret for test, one for live, sent once. Each has a key id.
During a key change both secrets are valid. Accept the request if any v1 matches any secret you hold.
3. Verify every request
Follow Verifying notifications.
4. Reply fast, then process
Reply with any 2xx within 10 seconds. Verify, store, reply, then process in the background.
Ignore duplicates by event_id. Delivery is at least once.
Apply an event only if its timestamp is newer than the last one you applied.
Ignore credit_application.test after verifying.
5. Receive a test notification
Send a test yourself: Send a test notification.
6. Test end to end
We can run a test application on a merchant that has agreed to share outcomes with you.
Retries
Non-2xx, timeout, connection failure or redirect: we retry for about 24 hours (20 attempts, backing off). Same event_id. FinMatch-Delivery-Attempt counts up.
After that, delivery stops. Nothing is lost on our side. If you were down longer, tell us the window and we replay with the same event_ids.
For planned downtime, tell us first and we pause delivery.
Your quotes and your merchants
Each merchant’s finance link must open that merchant’s finance page.
You only receive notifications for merchants that have agreed to share credit outcomes with you.
Need help?
Contact partners@finmatch.io.