Technical Reference

This document provides technical details and implementation patterns for specific Billy features and integrations.

Payment Status Integration

Overview

Billy implements bidirectional payment status synchronization between Pennylane and various integration sources. This allows payment updates to flow in both directions, ensuring data consistency across systems.

Architecture

Dest to Source (Pennylane → Integration)

When Pennylane updates payment status, Billy syncs this information to the source integration: Requirements:

PennylaneIntegration must implement UpdatePaymentStatusIntegration
Source integration must implement PushPaymentStatusIntegration

Implementation Steps:

Ensure getAllowedSourcesForInvoiceSynchronization works for your integration
Update getDestToSourceSyncableSourceIntegrations to include your integration
Implement the required interfaces

Testing:

# Test synchronization with Pennylane
pnpm tsx scripts/pennylane/test-sync-dest-invoices.ts

# Debug mode available
pnpm tsx scripts/pennylane/test-sync-dest-invoices.ts --debug

Source to Dest (Integration → Pennylane)

When source systems update payment status, Billy syncs to Pennylane: Requirements:

Update getAllowedSourcesForInvoiceSynchronization
Specifically update getSourceToDestSyncableSourceIntegrations
This prevents querying non-existing fields

Post-filtering Considerations:

Check filterDestSyncableInvoices function
Review getSyncablePennylaneGateways for gateway restrictions
Consider implementing refresh_unpaid_client_invoices or refresh_unpaid_supplier_invoices

Implementation Patterns

UpdatePaymentStatusIntegration

Render this field in your integration component:

<UpdatePaymentStatusField
  integration={integration}
  source={InvoiceIntegrationSource.Pennylane}
/>

PushPaymentStatusIntegration

Render this field in your integration component:

<PushPaymentStatusField
  integration={integration}
  source={InvoiceIntegrationSource.Hyperline}
/>

Development Workflow

# 1. Push invoice to Pennylane
pnpm tsx scripts/pennylane/test-push-client-invoice.ts

# 2. Mark as paid on Pennylane (via UI or API)

# 3. Test synchronization
pnpm tsx scripts/pennylane/test-sync-dest-invoice.ts

Cron Jobs

Payment synchronization is managed by Vercel cron jobs:

Pennylane-only sync: /api/invoices/cron/synchronize_payments_with_pennylane_dest_invoices
Integration sync (200 at a time): /api/integrations/internal/[source]/cron/synchronize_payments_with_pennylane_dest_invoices
Individual integration sync: /api/integrations/internal/[source]/[id]/synchronize_payments_with_pennylane_dest_invoices

View cron jobs: Vercel Dashboard

Database Development

PostgreSQL Constraints

List constraints on a specific table:

SELECT con.conname, pg_get_constraintdef(con.oid)
FROM pg_catalog.pg_constraint con
INNER JOIN pg_catalog.pg_class rel ON rel.oid = con.conrelid
INNER JOIN pg_catalog.pg_namespace nsp ON nsp.oid = connamespace
WHERE nsp.nspname = 'public' AND rel.relname = 'invoices';

Database Migrations

# Create new migration
supabase migration new "add_payment_status_field"

# Test locally
supabase migration up --local

# Apply to production
supabase migration up --linked

Integration Development

Webhook Development

Local Testing with Tunnels

For local webhook development, use Cloudflare tunnels:

# Start tunnel for main app
cloudflared tunnel --url https://localhost:3000

# Start tunnel for Supabase storage
cloudflared tunnel --url http://localhost:54321

Permanent Tunnel Setup

# Install cloudflared
brew untap cloudflare/cloudflare # if needed
brew install cloudflared

# Login (requires HeyBilly Cloudflare account access)
cloudflared tunnel login

# Create personal tunnel
cloudflared tunnel create your-name

# Route DNS
cloudflared tunnel route dns your-name your-name.tunnels.heybilly.io

Configuration file .cloudflared/your-name.yml:

url: https://localhost:3000
tunnel: <Tunnel-UUID>
credentials-file: /Users/<Your-user>/.cloudflared/<Tunnel-UUID>.json

Run tunnel:

cloudflared tunnel --config=.cloudflared/your-name.yml run your-name

Environment variables:

# Local tunnels
SUPABASE_STORAGE_TUNNEL_URL=https://your-name-storage.tunnels.heybilly.io
APP_TUNNEL_URL=https://your-name.tunnels.heybilly.io

OAuth Development

Spendesk OAuth

Spendesk doesn’t allow ports in redirect URIs:

# Set port to 443 for HTTPS
PORT=443

HubSpot Development

Go to HubSpot Developer Account
Create application with redirect URI: https://localhost:3000/oauth/hubspot/redirect_uri
Add credentials to .env.local:

# HubSpot [Dev]
HUBSPOT_REDIRECT_URI=https://localhost:3000/oauth/hubspot/redirect_uri
HUBSPOT_PENNYLANE_API_KEY=XXX
HUBSPOT_PENNYLANE_CLIENT_SECRET=XXX
HUBSPOT_PENNYLANE_CLIENT_ID=XXX

Pipedrive Development

Go to Pipedrive Developer Hub
Create OAuth application with redirect URI: https://localhost:3000/oauth/pipedrive/redirect_uri
Add credentials to .env.local:

# Pipedrive x Pennylane [Local]
PIPEDRIVE_REDIRECT_URI=https://localhost:3000/oauth/pipedrive/redirect_uri
PIPEDRIVE_PENNYLANE_CLIENT_ID=xxx
PIPEDRIVE_PENNYLANE_CLIENT_SECRET=xxx

Pipedrive Extensions

Custom Modals

Add these modals to your Pipedrive application:

Name	Iframe URL
Créer une facture Pennylane	`<Tunnel URL>/iframes/pipedrive/pennylane/deals`
Créer un devis Pennylane	`<Tunnel URL>/iframes/pipedrive/pennylane/quotes`
Associer une facture	`<Tunnel URL>/iframes/pipedrive/pennylane/associate_invoices`
Associer un devis	`<Tunnel URL>/iframes/pipedrive/pennylane/associate_quotes`
Créer un client	`<Tunnel URL>/iframes/pipedrive/pennylane/organization/create_client`
Configuration	`<Tunnel URL>/iframes/pipedrive/pennylane/configuration_fields`

Note: Clear any entrypoint selection in the dropdown for all modals.

Custom Panels

Add these panels to your Pipedrive application:

Name	API Endpoint	Panel Locations	Main Action
Pennylane (Your Name [Dev])	`<Tunnel URL>/iframes/pipedrive/pennylane/invoice_panel`	deals	Default
Pennylane (Your Name [Dev])	`<Tunnel URL>/iframes/pipedrive/pennylane/organization_panel`	organizations	Default

JWT Secret: Use the same value as PIPEDRIVE_PENNYLANE_CLIENT_SECRET if required.

Development Tools

Cloudflare Workers

# Start workers in development mode
pnpm run workers-dev

Hookdeck

# Login to Hookdeck
hookdeck login

# Listen to local port
hookdeck listen 3000

GraphQL Development

# Install watchman for file watching
brew install watchman

# Start GraphQL relay in watch mode
pnpm relay:watch

Gotenberg (PDF Generation)

Gotenberg is accessible at: http://localhost:3045/health

Environment Management

Pennylane Sandbox

Go to Pennylane Sandbox
Create your own sandbox
Get API key from developer settings
Add to .env.local:

FIXTURES_BILLY_PENNYLANE_INTEGRATION_API_TOKEN=YOUR_SECRET_VALUE_GOES_HERE

Reset SQL schema and run pnpm populate

Country Codes

Refresh country list and AlphaCode:

pnpm get-all-country-code

Dev Docs

Technical reference

Technical Reference

Payment Status Integration

Overview

Architecture

Dest to Source (Pennylane → Integration)

Source to Dest (Integration → Pennylane)

Implementation Patterns

UpdatePaymentStatusIntegration

PushPaymentStatusIntegration

Development Workflow

Cron Jobs

Database Development

PostgreSQL Constraints

Database Migrations

Integration Development

Webhook Development

Local Testing with Tunnels

Permanent Tunnel Setup

OAuth Development

Spendesk OAuth

HubSpot Development

Pipedrive Development

Pipedrive Extensions

Custom Modals

Custom Panels

Development Tools

Cloudflare Workers

Hookdeck

GraphQL Development

Gotenberg (PDF Generation)

Environment Management

Pennylane Sandbox

Country Codes

Dev Docs

​Technical Reference

​Payment Status Integration

​Overview

​Architecture

​Dest to Source (Pennylane → Integration)

​Source to Dest (Integration → Pennylane)

​Implementation Patterns

​UpdatePaymentStatusIntegration

​PushPaymentStatusIntegration

​Development Workflow

​Cron Jobs

​Database Development

​PostgreSQL Constraints

​Database Migrations

​Integration Development

​Webhook Development

​Local Testing with Tunnels

​Permanent Tunnel Setup

​OAuth Development

​Spendesk OAuth

​HubSpot Development

​Pipedrive Development

​Pipedrive Extensions

​Custom Modals

​Custom Panels

​Development Tools

​Cloudflare Workers

​Hookdeck

​GraphQL Development

​Gotenberg (PDF Generation)

​Environment Management

​Pennylane Sandbox

​Country Codes

Technical Reference

Payment Status Integration

Overview

Architecture

Dest to Source (Pennylane → Integration)

Source to Dest (Integration → Pennylane)

Implementation Patterns

UpdatePaymentStatusIntegration

PushPaymentStatusIntegration

Development Workflow

Cron Jobs

Database Development

PostgreSQL Constraints

Database Migrations

Integration Development

Webhook Development

Local Testing with Tunnels

Permanent Tunnel Setup

OAuth Development

Spendesk OAuth

HubSpot Development

Pipedrive Development

Pipedrive Extensions

Custom Modals

Custom Panels

Development Tools

Cloudflare Workers

Hookdeck

GraphQL Development

Gotenberg (PDF Generation)

Environment Management

Pennylane Sandbox

Country Codes