Description

Purpose and use

Payers identify the person or organization expected to pay an invoice. They keep contact, address, customer, and metadata details so billing teams can issue invoices, follow up receivables, and keep payer history separate from the invoice itself.

Who uses this. Finance operations, billing teams, customer service, and relationship managers use payer records when creating invoices and answering payment questions.

How it works. A payer is linked to a customer and carries validated country, address, email, phone, and metadata fields. Active payer records can be selected when creating or filtering invoices.

What users do. Users create a payer before billing, update contact or address information, search payers by customer or country, and retire obsolete payer records without losing invoice history.

Outcomes and side effects. Payer changes affect future invoice creation and communication. Existing invoices retain their own issued data, while the payer record remains useful for later collection and support work.

Related manuals: Invoices, Customers, Addresses, Counterparties.

Overview

The Payers API provides functionality for managing invoice payers, including:

• Payer creation and management
• Customer association
• Email and contact information
• Country validation
• Permission-based access control

Endpoints

Create New Payer

POST /v1/payers

Create a new payer associated with a customer.

Request Body:

{
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "payer@example.com",
  "name": "John Doe",
  "phone": "+41441234567",
  "street": "Bahnhofstrasse",
  "number": "1A",
  "postal_code": "8001",
  "city": "Zürich",
  "state": "ZH",
  "country": "CHE",
  "metadata": {
    "department": "Finance",
    "reference": "PAY001"
  }
}

Success Response (200):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "payer@example.com",
  "name": "John Doe",
  "phone": "+41441234567",
  "address": {
    "street": "Bahnhofstrasse",
    "number": "1A",
    "postal_code": "8001",
    "city": "Zürich",
    "state": "ZH",
    "country": "CHE"
  },
  "active": true,
  "metadata": {
    "department": "Finance",
    "reference": "PAY001"
  },
  "created_at": "2024-03-21T10:00:00Z",
  "created_by": "558df07d-46cf-4131-90a8-62a3e543cad0"
}

List Payers

GET /v1/payers

Retrieve payers with filtering and pagination.

Query Parameters:

• limit: Maximum number of records (optional)
• offset: Number of records to skip (optional)
• country: ISO3 country code filter (optional)
• email: Exact email filter (optional)
• active: Filter by active status (optional)

Success Response (200):

{
  "payers": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "payer@example.com",
      "name": "John Doe",
      "phone": "+41441234567",
      "address": {
        "street": "Bahnhofstrasse",
        "number": "1A",
        "postal_code": "8001",
        "city": "Zürich",
        "state": "ZH",
        "country": "CHE"
      },
      "active": true,
      "metadata": {
        "department": "Finance",
        "reference": "PAY001"
      }
    }
  ],
  "total": 50,
  "has_more": true
}

Update Payer

PUT /v1/payers/{id}

Update an existing payer's information.

Path Parameters:

• id: Payer UUID

Request Body:

{
  "name": "John Smith",
  "phone": "+4930123456",
  "active": false,
  "metadata": {
    "department": "Accounting",
    "reference": "PAY001-UPD"
  }
}

Delete Payer

DELETE /v1/payers/{id}

Delete a payer record.

Path Parameters:

• id: Payer UUID

Success Response (200): Empty response with status code 200

Data Validation

Country Code Validation

• Must be ISO 3166-1 alpha-3 format (e.g., "CHE", "DEU")
• Validated using regex pattern: ^[A-Z]{3}$

Required Fields

• customer_id: UUID of associated customer
• email: Valid email address

Query Filtering

The list endpoint supports dynamic filtering:

GET /v1/payers?country=CHE&limit=10&offset=0

Query parameters are automatically converted to database filters.

Error Responses

Error Codes

Implementation Notes

Service Layer

The service layer handles:

1. Permission validation
2. Business logic
3. Data validation
4. Database operations

Initialization

The module automatically:

1. Creates required schema
2. Migrates tables
3. Sets up initial permissions
4. Registers record types

Usage Examples

Filter Payers by Multiple Criteria

GET /v1/payers?country=CHE&active=true&limit=20&offset=40

Update Payer with New Metadata

{
  "metadata": {
    "department": "Accounting",
    "cost_center": "CC002",
    "payment_terms": "net60",
    "credit_limit": 50000
  }
}