Download the PHP package bhaidar/laravel-checkeeper without Composer

Laravel Checkeeper

A comprehensive Laravel package for the Checkeeper API v3. Send physical checks via USPS, UPS, or FedEx, or generate PDFs for self-printing.

Features

• Full API Coverage - Complete implementation of Checkeeper API v3
• Type-Safe - Readonly DTOs with typed properties throughout
• Fluent Queries - Powerful filter builder for searching checks
• Webhook Support - Automatic signature verification and event dispatching
• Queue Integration - Async check creation
• Event-Driven - Laravel events for check operations
• Well Tested - Comprehensive Pest test suite
• Laravel 11+ - Built for modern Laravel applications

Table of Contents

• Requirements
• Installation
• Configuration
• How It Works
• Creating Checks
  • Basic Check Creation
  • Using Type-Safe DTOs
  • Delivery Methods
  • Bulk Check Creation
  • Async Check Creation
• Querying Checks
  • List All Checks
  • Filtering Checks
  • Check Status
  • Tracking Events
  • Cancel Check
  • Download Check Images
• Webhooks
  • Webhook Setup
  • Listening to Events
  • Example Listeners
  • Webhook Security
• Team & Templates
• Events
• Exception Handling
• Complete Application Example
• Testing Your Integration
• API Reference
• Contributing
• License

Requirements

• PHP 8.2+
• Laravel 11.0+

Installation

Install via Composer:

Publish the configuration file:

Add your API credentials to .env:

Optional queue configuration:

Configuration

The package configuration file is located at config/checkeeper.php:

How It Works

The Laravel Checkeeper package provides a clean, Laravel-friendly interface to the Checkeeper API. Here's how the components work together:

Architecture Overview

Core Components

1. Facade (Checkeeper) - Main entry point for all operations
2. Resources - Organized API endpoints (Checks, Team, Templates)
3. DTOs - Type-safe data transfer objects
4. Events - Laravel events for check operations and webhooks
5. Jobs - Queue jobs for async operations
6. Filter Builder - Fluent query builder for searching checks

Request Flow

Creating Checks

Basic Check Creation

Create a check using a simple array:

Using Type-Safe DTOs

Recommended approach for type safety and IDE autocomplete:

Adding a Company Logo:

Using Image Signature:

Delivery Methods

Delivery is specified separately from check data and passed as the second argument to create() or createBulk(). This matches the Checkeeper API payload structure where delivery is a sibling to checks:

No delivery specified defaults to the team's configured delivery method:

Available Delivery Methods:

Bulk Check Creation

Create multiple checks in a single API request. Delivery applies to all checks in the batch:

Using DTOs for bulk:

Async Check Creation

Recommended for production to avoid blocking your application:

Listen for completion:

Querying Checks

List All Checks

Filtering Checks

Use the fluent filter builder for powerful queries:

Available Filter Methods:

Filterable Fields:

• id, request_id, template_id
• status, ship_method, test
• number, date, amount, memo, note
• payer_line1, payer_line2, payer_line3, payer_line4
• payee_line1, payee_line2, payee_line3, payee_line4
• meta, created, updated

Raw filter array:

Check Status

Get current status of a check:

Available Check Statuses:

Tracking Events

Get detailed tracking information:

Cancel Check

Cancel a check before it's printed or mailed:

Note: Checks can only be cancelled if they haven't been printed yet.

Download Check Images

Download check images as JPG or PDF:

Get voucher image:

Webhooks

Webhooks allow Checkeeper to notify your application in real-time when check statuses change.

Webhook Setup

1. The webhook route is auto-registered at /checkeeper/webhook
2. Configure the URL in Checkeeper dashboard: https://yourapp.com/checkeeper/webhook
3. Set webhook secret in .env:

The package automatically:

• Verifies webhook signatures using HMAC SHA256
• Dispatches WebhookReceived event
• Returns 200 OK immediately

Listening to Events

Register listeners in your EventServiceProvider:

Example Listeners

Update Invoice When Check Delivered

Log All Webhook Activity

Webhook Security

The package automatically verifies webhook signatures using the VerifyWebhookSignature middleware:

1. Extracts X-Checkeeper-Signature header
2. Validates using HMAC SHA256 with your webhook secret
3. Rejects invalid signatures with 401 Unauthorized

No additional configuration needed - just ensure your webhook secret is set in .env.

Disable webhooks if needed:

Team & Templates

Get Team Information

List Available Templates

Use a template when creating checks:

Events

The package dispatches Laravel events for key operations:

CheckCreated

Fired after successful check creation.

CheckCancelled

Fired after check cancellation.

WebhookReceived

Fired when webhook is received and verified.

Exception Handling

The package throws typed exceptions for different error scenarios:

Complete Application Example

Here's a complete example of a vendor payment system:

Testing Your Integration

Use HTTP fakes to test your Checkeeper integration:

API Reference

Check Operations

Team Operations

Template Operations

Available DTOs

Available Enums

Testing

Run the package test suite:

Changelog

Please see CHANGELOG.md for recent changes.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Security

If you discover any security issues, please email [email protected] instead of using the issue tracker.

Credits

• Bilal Haidar
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.