Description

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

Code	Description
payers_m.failed_to_create_payer	Failed to create payer
errs.invalid_input	Invalid input data
errs.forbidden	Insufficient permissions
errs.database_error	Database operation failed

Implementation Notes

Service Layer

The service layer handles:

Permission validation
Business logic
Data validation
Database operations

Initialization

The module automatically:

Creates required schema
Migrates tables
Sets up initial permissions
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
  }
}

Description

On this page