Invoice Payment

Invoice payments represent incoming payments received from customers to settle invoices. They track payment details including payment type, bank accounts, execution dates, and amounts. The system automatically handles overpayments by creating customer debit entries and supports various payment types including customer payments, debits, and credits.

• Create an invoice payment
• Update an invoice payment
• Retrieve an invoice payment
• Delete an invoice payment
• List invoice payments
• Payment Types and Behavior
  • Payment Types
  • Automatic Processing
  • Customer Account Integration

Create an invoice payment

post

/invoice/{invoice_id}/payment

Attribute (* required)	Type	Description
type	String?	Payment type: customer_payment, customer_debit, customer_credit, cash_discount, credit_note, receivables_loss (defaults to customer_payment)
bank_account_id	String?	Bank account ID for payment processing
amount *	Float	Payment amount (must be > 0)
message	String?	Payment description or reference
executed_at	Date?	Payment execution date (defaults to current date)

Overpayment Handling

When the payment amount exceeds the invoice's open amount, the system automatically:

1. Creates a payment for the exact open amount
2. Creates a separate customer debit entry for the excess amount

Example response

// HTTP 201 Created
{
    "id": "v7rnRjBn9o",
    "type": "customer_payment",
    "invoice_id": "AG52olvLXP",
    "invoice": null,
    "bank_account": null,
    "amount": 1250.00,
    "message": "Bank transfer payment",
    "executed_at": "2024-01-15"
}

Update an invoice payment

put

/invoice/{invoice_id}/payment/{id}

Attribute	Type	Description
type	String?	Payment type: customer_payment, customer_debit, customer_credit, cash_discount, credit_note, receivables_loss
bank_account_id	String?	Bank account ID for payment processing
amount	Float?	Payment amount (must be > 0)
message	String?	Payment description or reference
executed_at	Date?	Payment execution date

Example response

// HTTP 200 OK
{
    // an invoice payment object
}

Retrieve an invoice payment

get

/invoice/{invoice_id}/payment/{id}

Example response

// HTTP 200 OK
{
    "id": "v7rnRjBn9o",
    "type": "customer_payment",
    "invoice_id": "AG52olvLXP",
    "invoice": {
        "id": "AG52olvLXP",
        "number": "R-2024-0001",
        "name": "Website Development",
        "total": 1250.00,
        "total_paid": 1250.00,
        "total_open": 0
    },
    "bank_account": {
        "id": "bk1nRjBn9o",
        "name": "UBS Business Account",
        "currency": "CHF",
        "iban": "CH9300762011623852957"
    },
    "amount": 1250.00,
    "message": "Bank transfer payment - Invoice R-2024-0001",
    "executed_at": "2024-01-15"
}

Delete an invoice payment

delete

/invoice/{invoice_id}/payment/{id}

Example response

// HTTP 204 No Content

List invoice payments

get

/invoice/{invoice_id}/payment

The list endpoint accepts the same parameters as in Retrieve an invoice payment and returns a paginated array of the same invoice payment object in the data property.

Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.

Payment Types and Behavior

Payment Types

• customer_payment: Standard incoming payment from customer (default)
• customer_debit: Debit entry in customer account (e.g., from overpayments)
• customer_credit: Credit entry in customer account (e.g., refunds, adjustments)
• cash_discount: Cash discount applied to invoice (early payment discount)
• credit_note: Credit note applied against invoice
• receivables_loss: Write-off of uncollectable receivable

Automatic Processing

When an invoice payment is created, the system automatically:

1. Validates amount: Prevents payments with zero or negative amounts
2. Sets defaults: Assigns default bank account and payment type if not specified
3. Handles overpayments: Splits overpayments into payment + customer debit
4. Updates invoice: Recalculates total_paid and marks invoice as paid when fully settled
5. Creates customer transactions: For debit/credit payments, creates corresponding customer account entries
6. Logs activity: Records payment creation/deletion in the invoice activity log

Customer Account Integration

Customer debit and credit payments automatically create entries in the customer's account ledger, allowing for:

• Account balance tracking
• Credit/debit management
• Payment reconciliation across multiple invoices

When a payment is deleted, any associated customer transaction is also removed to maintain data consistency.