Our payment webhooks are designed to be used by our strategic accounts to enable them to receive real-time updates about payment events for Checkatrade Pay payments. These webhooks provide comprehensive payment information including amounts, fees, and status changes. If you want to start making use of these webhooks please reach out to your account manager.

If you use Zapier we have a handy integration guide to help you get started here

How to proceed with the integration

To set up this integration, please follow these steps:

Read the API specs
Send your webhook URL to your Checkatrade Account Manager
Whitelist the IPs (if necessary)
We will then configure the integration and send over test payloads
Map the fields from the payload into your financial/CRM system

Payment Webhook Types

There are three types of payment webhooks available:

1. Payment Requested (`PAYMENT_REQUESTED`)

This webhook is triggered when a payment is initially requested for a job. It provides all the details about the payment request including amounts and fee calculations.

2. Payment Paid (`PAYMENT_PAID`)

This webhook is triggered when a payment has been successfully processed and completed. It confirms that the payment has been received and processed.

3. Payment Cancelled (`PAYMENT_CANCELLED`)

This webhook is triggered when a payment has been cancelled or has failed. This allows you to update your systems accordingly and handle any necessary reconciliation.

The Request Object

Below is a breakdown of the response JSON object providing an overview of what each field means.

Payment Object:

Field	Type	Description
`jobId`	STRING	A unique identifier for the job associated with this payment. Used to link the payment to the specific checkatrade job if applicable.
`companyId`	NUMBER	The unique identifier for the trade company receiving the payment.
`paymentAmount`	NUMBER	The amount of the payment in the specified currency (e.g., 500.00 for £500).
`paymentCurrency`	STRING	The currency code for the payment in ISO 4217 format (e.g., "GBP" for British Pounds).
`paymentReference`	STRING	A unique reference identifier for this specific payment transaction, provided by checkatrade.
`jobReference`	STRING	A reference identifier for the job associated with this payment.
`homeownerFirstName`	STRING	The first name of the homeowner making the payment.
`homeownerLastName`	STRING	The last name of the homeowner making the payment.
`dateCreated`	STRING	The date and time when the payment event was created in ISO 8601 format (RFC3339).
`description`	STRING	The reference you give checkatrade when creating the payment.
`tradeFeeIncludingVatPercent`	NUMBER	The percentage of the trade fee including VAT (e.g., 20.0 for 20%).
`tradeFeeIncludingVatAmount`	NUMBER	The monetary amount of the trade fee including VAT.
`tradeFeeExcludingVatPercent`	NUMBER	The percentage of the trade fee excluding VAT.
`tradeFeeExcludingVatAmount`	NUMBER	The monetary amount of the trade fee excluding VAT.
`tradeAmount`	NUMBER	The total amount that will be paid to the trade (payment amount plus any applicable fees).

The Response

The webhook has a response type of 201. Sending this response to the webhook endpoint confirms a successful receipt and acknowledgement of the data transmitted.

Example Payloads

Payment Requested Example

{
  "jobId": "job-uuid-12345",
  "companyId": 1234,
  "paymentAmount": 500.00,
  "paymentCurrency": "GBP",
  "paymentReference": "PAY-REF-001",
  "jobReference": "JOB-REF-001",
  "homeownerFirstName": "Jane",
  "homeownerLastName": "Doe",
  "dateCreated": "2024-07-16T16:46:12.707Z",
  "description": "Payment request for bathroom renovation",
  "tradeFeeIncludingVatPercent": 20.0,
  "tradeFeeIncludingVatAmount": 100.00,
  "tradeFeeExcludingVatPercent": 16.67,
  "tradeFeeExcludingVatAmount": 83.33,
  "tradeAmount": 600.00
}

Payment Paid Example

{
  "jobId": "job-uuid-12345",
  "companyId": 1234,
  "paymentAmount": 500.00,
  "paymentCurrency": "GBP",
  "paymentReference": "PAY-REF-001",
  "jobReference": "JOB-REF-001",
  "homeownerFirstName": "Jane",
  "homeownerLastName": "Doe",
  "dateCreated": "2024-07-16T16:46:12.707Z",
  "description": "Payment completed for bathroom renovation",
  "tradeFeeIncludingVatPercent": 20.0,
  "tradeFeeIncludingVatAmount": 100.00,
  "tradeFeeExcludingVatPercent": 16.67,
  "tradeFeeExcludingVatAmount": 83.33,
  "tradeAmount": 600.00
}

Payment Cancelled Example

{
  "jobId": "job-uuid-12345",
  "companyId": 1234,
  "paymentAmount": 500.00,
  "paymentCurrency": "GBP",
  "paymentReference": "PAY-REF-001",
  "jobReference": "JOB-REF-001",
  "homeownerFirstName": "Jane",
  "homeownerLastName": "Doe",
  "dateCreated": "2024-07-16T16:46:12.707Z",
  "description": "Payment cancelled for bathroom renovation",
  "tradeFeeIncludingVatPercent": 20.0,
  "tradeFeeIncludingVatAmount": 100.00,
  "tradeFeeExcludingVatPercent": 16.67,
  "tradeFeeExcludingVatAmount": 83.33,
  "tradeAmount": 600.00
}

Understanding Payment Amounts and Fees

The payment webhooks include detailed fee information to help you understand the financial breakdown:

Payment Amount: This is the amount the homeowner pays for the job
Trade Fee: This is Checkatrade's fee for facilitating the transaction
Trade Amount: This is the total amount that goes to the trade (payment amount + fees)

The fee information is provided both as percentages and monetary amounts, with and without VAT, giving you complete visibility into the financial structure.

Other Info

Checkatrade reserve the right to add extra fields into the payload, therefore please implement this in a way that the presence of additional fields will not break your integration. We will notify you with advanced warning if we plan to remove or modify any existing fields within the payload.

Static IPs

Static IP addresses enhance webhook security by allowing for easy verification of incoming requests and preventing unauthorised access. This helps secure the transmission of data and reduces risk of malicious activities.

For Checkatrade's API there are two main static IP addresses:

Note the old IP addresses are only used for existing trades, if you are new to our webhooks you only need to whitelist our new IPs.

Environment	IP Address	Description
Development	34.105.162.121 34.89.85.173 35.234.151.94	This is the main test environment which can be used when initially integrating for validation testing.
Production	35.246.15.126 35.242.187.239 34.39.18.129	Main IP addresses to receive live payment events.

Security

Currently the main security around these webhooks is based on IP whitelisting. This is subject to change for more advanced security measures in the future.

Billing and Reconciliation

Payment webhooks are provided as part of our strategic account services. The webhooks include unique payment references and job references to help with reconciliation and tracking. Should you need to correlate payments with invoices or reports, these reference fields provide the necessary linkage.

Linking Payments to Jobs

If you also receive our lead delivery webhooks, you can use the jobId field in the payment webhook to link payments directly to the corresponding Checkatrade job. This enables full end-to-end tracking from initial lead through to payment completion.

Payment Reference Field

The paymentReference field contains a unique identifier that we apply to each payment transaction. This reference is the PSP (Payment Service Provider) reference from our underlying payment provider, ensuring traceability through the entire payment processing chain.

Description Field for Custom References

The description field contains any custom reference that the payer entered during the Checkatrade Pay user experience. This is the field where customers can input their own unique references, purchase order numbers, or other identifiers that help them track the payment on their end. You can use this field to match payments with your internal systems or customer records.

Idempotency

Payment events may be sent multiple times in edge cases (e.g., network issues, retries). Use the paymentReference field to implement idempotency in your system and avoid processing the same payment event multiple times.

Error Handling

If your webhook endpoint returns an error (non-2xx response), Checkatrade will attempt to retry the webhook delivery. Ensure your endpoint can handle duplicate deliveries gracefully and returns appropriate HTTP status codes:

201: Successfully received and processed
4xx: Client error - will not be retried
5xx: Server error - will be retried with exponential backoff