Payment Webhooks

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:

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.

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