PHPackages                             emeq/moneybird - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. emeq/moneybird

ActiveLibrary[Authentication & Authorization](/categories/authentication)

emeq/moneybird
==============

Laravel package for Moneybird integration with OAuth token management

v1.2.0(5mo ago)020[3 PRs](https://github.com/yusufkaracaburun/emeq-moneybird/pulls)MITPHPPHP ^8.3CI passing

Since Nov 23Pushed 1mo agoCompare

[ Source](https://github.com/yusufkaracaburun/emeq-moneybird)[ Packagist](https://packagist.org/packages/emeq/moneybird)[ Docs](https://github.com/emeq/moneybird)[ GitHub Sponsors](https://github.com/:vendor_name)[ RSS](/packages/emeq-moneybird/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (15)Versions (11)Used By (0)

EMEQ Moneybird
==============

[](#emeq-moneybird)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b22812986ffbd2176a5fedc5fcfa452ef6ea5f777ea2ca77571e3172d851a6e1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f656d65712f6d6f6e6579626972642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/emeq/moneybird)

Laravel package for Moneybird integration with OAuth token management and extended API features.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require emeq/moneybird
```

The package will automatically publish the config file and migration to your application during installation. If you need to republish them manually:

```
# Publish config file
php artisan vendor:publish --tag="moneybird-config"

# Publish migrations
php artisan vendor:publish --tag="moneybird-migrations"
```

After installation, run the migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

Add the following environment variables to your `.env` file:

```
MONEYBIRD_CLIENT_ID=your_client_id
MONEYBIRD_CLIENT_SECRET=your_client_secret
MONEYBIRD_REDIRECT_URI=https://your-app.com/moneybird/callback
MONEYBIRD_WEBHOOK_SECRET=your_webhook_secret
MONEYBIRD_API_TIMEOUT=30
```

### OAuth Setup

[](#oauth-setup)

1. Create a Moneybird application at
2. Set your redirect URI to match `MONEYBIRD_REDIRECT_URI` (e.g., `https://your-app.com/moneybird/auth/callback`)
3. Copy the Client ID and Client Secret to your `.env` file

Usage
-----

[](#usage)

### Connecting to Moneybird

[](#connecting-to-moneybird)

#### Via Routes (Recommended for Web Applications)

[](#via-routes-recommended-for-web-applications)

The package provides web routes for easy OAuth connection:

1. **Start the connection**: Visit `/moneybird/connect` while authenticated

    - This route requires authentication (`auth` middleware)
    - It will redirect you to Moneybird's authorization page
2. **Handle the callback**: After authorization, Moneybird redirects to `/moneybird/auth/callback`

    - The callback route automatically exchanges the authorization code for tokens
    - On success, you'll be redirected to your dashboard with a success message
    - On error, you'll be redirected with an error message

**Example in your Blade template:**

```

    Connect to Moneybird

```

**Example redirect in your controller:**

```
return redirect()->route('moneybird.connect');
```

#### Via Artisan Command

[](#via-artisan-command)

Use the artisan command for CLI-based connections:

```
php artisan moneybird:connect --user-id=1
```

#### Programmatically

[](#programmatically)

```
use Emeq\Moneybird\Services\OAuthService;

$oauthService = app(OAuthService::class);
$authorizationUrl = $oauthService->getAuthorizationUrl();

// Redirect user to $authorizationUrl
// After authorization, exchange the code:
$connection = $oauthService->exchangeCodeForTokens($authorizationCode, $userId);
```

### Testing the Connection

[](#testing-the-connection)

#### Via Routes

[](#via-routes)

After connecting, you can test the connection by accessing any route that uses the Moneybird service. The package will automatically handle token refresh if needed.

**Example test route in your application:**

```
Route::middleware('auth')->get('/moneybird/test', function () {
    $userId = auth()->id();
    $service = \Emeq\Moneybird\Facades\Moneybird::connection($userId);

    try {
        $administrations = $service->administrations()->list();
        return response()->json([
            'success' => true,
            'message' => 'Connection successful!',
            'administrations' => $administrations,
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'success' => false,
            'message' => 'Connection failed: ' . $e->getMessage(),
        ], 500);
    }
});
```

#### Via Artisan Command

[](#via-artisan-command-1)

```
php artisan moneybird:test-connection --user-id=1
```

### Using the Moneybird Service

[](#using-the-moneybird-service)

```
use Emeq\Moneybird\Facades\Moneybird;

// Get connection for a user
$service = Moneybird::connection($userId);

// Or for a specific connection
$service = Moneybird::connection(connectionId: $connectionId);

// List administrations
$administrations = $service->administrations()->list();

// Work with contacts
$contacts = $service->contacts()->list();
$contact = $service->contacts()->create([
    'company_name' => 'Example Company',
    'email' => 'contact@example.com',
]);

// Work with sales invoices
$invoices = $service->salesInvoices()->list();
$invoice = $service->salesInvoices()->create([
    'contact_id' => $contact->id,
    'invoice_date' => now()->format('Y-m-d'),
    'details' => [
        [
            'description' => 'Product 1',
            'price' => 100.00,
            'amount' => 1,
        ],
    ],
]);

// Find invoice by invoice ID (invoice number)
$invoice = $service->salesInvoices()->findByInvoiceId('2023-001');

// Send invoice
$service->salesInvoices()->send($invoice->id);
```

### Frontend Components

[](#frontend-components)

The package includes reusable Vue components for displaying integrations in your frontend:

**IntegrationCard Component** (`resources/views/IntegrationCard.vue`)

A Vue component for displaying integration information in a card format or connection prompt. It supports:

- Integration logos (with automatic placeholder for missing logos)
- Clickable integration names with external links
- Connection status display
- Action buttons (Connect/Manage for available integrations, "Coming soon" for unavailable ones)
- Connection prompt mode (when `showPrompt` prop is true and integration is not connected)

**Usage Example - Card Mode:**

```

import IntegrationCard from "vendor/emeq/moneybird/resources/views/IntegrationCard.vue";

export default {
    components: {
        IntegrationCard,
    },
    methods: {
        handleIntegrationClick(integrationId) {
            // Handle integration click
        },
    },
};

```

**Usage Example - Connection Prompt Mode:**

```

import IntegrationCard from "vendor/emeq/moneybird/resources/views/IntegrationCard.vue";

export default {
    components: {
        IntegrationCard,
    },
};

```

**Integration Object Structure:**

```
interface Integration {
    id: string; // Unique identifier (e.g., 'moneybird', 'mollie')
    name: string; // Display name
    description: string; // Short description
    logo: string; // Logo URL (SVG or image)
    url: string; // External website URL
    available: boolean; // Whether integration is available
    connected: boolean; // Whether user has connected
    connectUrl: string; // URL to start connection flow
}
```

### API Routes

[](#api-routes)

The package provides RESTful API routes for accessing Moneybird data. All routes are prefixed with `/api/moneybird` and require Laravel Sanctum authentication.

#### Authentication

[](#authentication)

All API routes require authentication via Laravel Sanctum. Include the Bearer token in the Authorization header:

```
Authorization: Bearer {your-sanctum-token}

```

#### Connection Parameters

[](#connection-parameters)

You can specify which Moneybird connection to use by including one of these query parameters:

- `connection_id` - Use a specific connection by ID
- `user_id` - Use the first active connection for a user
- `tenant_id` - Use the first active connection for a tenant
- If none provided, uses the first active connection

**Example:**

```
GET /api/moneybird/administrations?connection_id=1
GET /api/moneybird/contacts?user_id=5&tenant_id=tenant1

```

#### Response Format

[](#response-format)

All endpoints return JSON with the following structure:

**Success:**

```
{
  "success": true,
  "data": { ... }
}
```

**Error:**

```
{
    "success": false,
    "message": "Error message"
}
```

#### Available Endpoints

[](#available-endpoints)

##### Administrations

[](#administrations)

- `GET /api/moneybird/administrations` - List all administrations
- `GET /api/moneybird/administrations/{id}` - Get a specific administration

**Example:**

```
curl -X GET "https://your-app.com/api/moneybird/administrations" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

##### Contacts

[](#contacts)

- `GET /api/moneybird/contacts` - List all contacts (supports filters: `firstname`, `lastname`, `company_name`, `email`)
- `GET /api/moneybird/contacts/search?q={query}` - Search contacts
- `GET /api/moneybird/contacts/{id}` - Get a specific contact
- `POST /api/moneybird/contacts` - Create a new contact
- `PUT /api/moneybird/contacts/{id}` - Update a contact
- `DELETE /api/moneybird/contacts/{id}` - Delete a contact

**Examples:**

```
# List contacts with filters
curl -X GET "https://your-app.com/api/moneybird/contacts?firstname=John&lastname=Doe" \
  -H "Authorization: Bearer {token}"

# Search contacts
curl -X GET "https://your-app.com/api/moneybird/contacts/search?q=john" \
  -H "Authorization: Bearer {token}"

# Create a contact
curl -X POST "https://your-app.com/api/moneybird/contacts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@example.com"
  }'

# Update a contact
curl -X PUT "https://your-app.com/api/moneybird/contacts/123456" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Jane",
    "lastname": "Doe"
  }'
```

##### Sales Invoices

[](#sales-invoices)

- `GET /api/moneybird/sales-invoices` - List all sales invoices (supports filters: `contact_id`, `state`, `invoice_id`)
- `GET /api/moneybird/sales-invoices/by-invoice-id/{invoiceId}` - Find invoice by invoice number
- `GET /api/moneybird/sales-invoices/{id}` - Get a specific sales invoice
- `POST /api/moneybird/sales-invoices` - Create a new sales invoice
- `PUT /api/moneybird/sales-invoices/{id}` - Update a sales invoice
- `DELETE /api/moneybird/sales-invoices/{id}` - Delete a sales invoice
- `POST /api/moneybird/sales-invoices/{id}/send` - Send a sales invoice
- `GET /api/moneybird/sales-invoices/{id}/download/pdf` - Download invoice as PDF
- `GET /api/moneybird/sales-invoices/{id}/download/ubl` - Download invoice as UBL

**Examples:**

```
# List invoices with filters
curl -X GET "https://your-app.com/api/moneybird/sales-invoices?contact_id=123456&state=open" \
  -H "Authorization: Bearer {token}"

# Find by invoice ID
curl -X GET "https://your-app.com/api/moneybird/sales-invoices/by-invoice-id/INV-2024-001" \
  -H "Authorization: Bearer {token}"

# Create an invoice
curl -X POST "https://your-app.com/api/moneybird/sales-invoices" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "123456",
    "invoice_id": "INV-2024-001",
    "details": [
      {
        "description": "Product 1",
        "price": 100.00,
        "amount": 1
      }
    ]
  }'

# Send an invoice
curl -X POST "https://your-app.com/api/moneybird/sales-invoices/123456/send" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_method": "Email",
    "email_address": "customer@example.com"
  }'

# Download PDF
curl -X GET "https://your-app.com/api/moneybird/sales-invoices/123456/download/pdf" \
  -H "Authorization: Bearer {token}" \
  --output invoice.pdf
```

### Webhooks

[](#webhooks)

The package automatically registers a webhook route at `/moneybird/webhook` (configurable in `config/moneybird.php`).

Listen to webhook events:

```
use Emeq\Moneybird\Events\SalesInvoiceCreated;
use Emeq\Moneybird\Events\ContactUpdated;

Event::listen(SalesInvoiceCreated::class, function ($event) {
    // Handle sales invoice created
    $invoiceData = $event->payload;
});

Event::listen(ContactUpdated::class, function ($event) {
    // Handle contact updated
    $contactData = $event->payload;
});
```

### Commands

[](#commands)

- `php artisan moneybird:connect` - Connect to Moneybird via OAuth
- `php artisan moneybird:test-connection` - Test an existing connection
- `php artisan moneybird:refresh-tokens` - Refresh expired tokens

Features
--------

[](#features)

- OAuth 2.0 authentication with automatic token refresh
- Database-backed token storage
- Support for multiple administrations
- Extended API features:
    - Contacts (CRUD operations)
    - Sales Invoices (create, update, send, download, findByInvoiceId)
    - Administrations (list, get)

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information. [EMEQ](https://emeq.nl)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance81

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 85.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

7

Last Release

173d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f06068bef50b1d1191949a83d44a153778590813201d5eb477647ea1528ebc5d?d=identicon)[yusufkaracaburun](/maintainers/yusufkaracaburun)

---

Top Contributors

[![yusufkaracaburun](https://avatars.githubusercontent.com/u/25748114?v=4)](https://github.com/yusufkaracaburun "yusufkaracaburun (23 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

apilaraveloauthmoneybirdemeq

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/emeq-moneybird/health.svg)

```
[![Health](https://phpackages.com/badges/emeq-moneybird/health.svg)](https://phpackages.com/packages/emeq-moneybird)
```

###  Alternatives

[auth0/login

Auth0 Laravel SDK. Straight-forward and tested methods for implementing authentication, and accessing Auth0's Management API endpoints.

2745.0M3](/packages/auth0-login)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)