Invoice Payments

Overview

Managing invoice payments involves three key aspects:

Payment terms: When payment is expected
Payment tracking: Monitoring what’s been paid
Payment reconciliation: Matching payments to invoices

Payment terms

Payment terms define when an invoice must be paid. They consist of two components: a type and a days value.

Payment term types

NET

Payment due a fixed number of days from the invoice date.

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "payment_terms": {
      "type": "NET",
      "days": 30
    },
    "items": [...]
  }'

Examples:

NET 30: Due 30 days from invoice date
NET 15: Due 15 days from invoice date
NET 60: Due 60 days from invoice date

Due date calculation:

Invoice date: January 15, 2025
Payment terms: NET 30
Due date: February 14, 2025

END_OF_MONTH

Payment due a certain number of days after the end of the invoice month.

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "payment_terms": {
      "type": "END_OF_MONTH",
      "days": 30
    },
    "items": [...]
  }'

Examples:

END_OF_MONTH 30: Due the last day of the month of 30 days after
END_OF_MONTH 0: Due on the last day of the invoice month
END_OF_MONTH 45: Due the last day of the month of 45 days after

Due date calculation:

Invoice date: January 15, 2025
Payment terms: END_OF_MONTH 30
+30 days: Feb 14, 2025
Due date: Feb 28, 2025

Setting payment terms

Payment terms can be set when creating an invoice:

curl https://api.nocotax.app/invoices \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "payment_terms": {
      "type": "NET",
      "days": 45
    },
    "items": [
      {
        "title": "Annual Subscription",
        "quantity": 1,
        "unit_extratax_amount": "1200.00"
      }
    ]
  }'

Due date calculation

The due_date is automatically calculated when you finalize the invoice:

# Finalize the invoice
curl https://api.nocotax.app/invoices/inv_123/finalize \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY}

# Response includes calculated due_date
{
  "id": "inv_123",
  "status": "finalized",
  "document_date": "2025-01-15",
  "due_date": "2025-02-28",
  "payment_terms": {
    "type": "NET",
    "days": 30
  }
}

If no payment terms are specified, the due_date is not calculated and payment tracking will be less meaningful.

Payment status

Once finalized, invoices track payment status automatically:

`open`

Invoice is due but the due date hasn’t passed yet.

{
  "payment_status": "open",
  "due_date": "2025-02-14",
  "total_tax_included_amount": 10000,
  "amount_remaining": 10000
}

`due`

Invoice is past its due date and still unpaid.

{
  "payment_status": "due",
  "due_date": "2025-01-10",
  "total_tax_included_amount": 10000,
  "amount_remaining": 10000
}

Partially paid

An invoice that has received a partial payment keeps its open or due status until it is fully paid. Check amount_paid and amount_remaining:

{
  "payment_status": "due",
  "total_tax_included_amount": 10000,
  "amount_paid": 6000,
  "amount_remaining": 4000
}

`paid`

Invoice is fully paid.

{
  "payment_status": "paid",
  "total_tax_included_amount": 10000,
  "amount_paid": 10000,
  "amount_remaining": 0
}

Attaching payments

Record payments received or made on an invoice. All amounts here are accounting amounts: integers in the currency’s smallest unit (5000 = 50.00 EUR).

Full payment

Mark an invoice as fully paid:

curl https://api.nocotax.app/invoices/inv_123/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{}'

This marks the invoice as paid with:

Amount: Full amount_remaining
Payment date: Current date
No external reference

Partial payment or detailed record

Record a partial payment with specific amount:

curl https://api.nocotax.app/invoices/inv_123/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_data": {
      "amount": 5000,
      "currency": "EUR",
      "transaction_type": "payment",
      "reference": "PAYxPSP-ch_abc123"
    }
  }'

Payment parameters

All these parameters must be nested into a transaction_data field.

Parameter	Type	Description
`amount`	integer	Required. Payment amount in the currency’s smallest unit (e.g. `5000` = 50.00 EUR)
`currency`	string	Required. Payment currency. Must be identical to the invoice’s currency
`transaction_type`	string	Required. `payment`, `transfer` or `balance_adjustment`
`reference`	string	External payment reference (e.g., Stripe charge ID, bank transfer reference)

Transaction types:

payment: a payment made toward an invoice, for instance by card or PayPal
transfer: a movement of funds between accounts or entities, for instance a payout to a supplier
balance_adjustment: a customer’s existing cash balance applied to an invoice, reducing the amount due

transaction_data itself is optional: when it is omitted, Nocotax records a payment of the full amount_remaining.

Payment reconciliation

Reconciliation is the process of matching payments to invoices and ensuring balances are accurate.

Automatic reconciliation

When you attach a payment, Nocotax automatically:

Updates amount_remaining: Deducts payment amount
Updates payment_status: Changes to paid once amount_remaining reaches 0. While a balance remains, the status stays open or due
Adjusts AP/AR balances: Updates organization balances
Records payment history: Tracks all payments on the invoice

Multiple payments

An invoice can have multiple payments:

# First partial payment
curl https://api.nocotax.app/invoices/inv_123/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_data": {
      "amount": 3000,
      "currency": "EUR",
      "transaction_type": "payment",
      "reference": "PAYMENT_1"
    }
  }'

# Second partial payment
curl https://api.nocotax.app/invoices/inv_123/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_data": {
      "amount": 7000,
      "currency": "EUR",
      "transaction_type": "payment",
      "reference": "PAYMENT_2"
    }
  }'

Credit notes and payment balance

Credit notes affect the payment balance:

# Original invoice: €100
# Customer pays: €100
# Status: paid

# Issue credit note: -€20
curl https://api.nocotax.app/credit_notes \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -d '{
    "flow": "sales",
    "currency": "EUR",
    "customer_id": "org_customer_123",
    "invoice_id": "inv_123",
    "items": [
      {
        "title": "Correction",
        "quantity": 1,
        "unit_extratax_amount": "-20.00"
      }
    ]
  }'

# After finalizing credit note:
# amount_remaining: -€20 (credit balance)
# Status: paid (but with credit to refund or apply)

The credit note creates a credit balance that can be:

Refunded to the customer
Applied to future invoices
Tracked as credit owed

See Credit Notes for details.

Best practices

Always set payment terms when creating invoices for accurate due date tracking
Use NET terms for fixed payment periods
Use END_OF_MONTH terms for B2B customers who process payments monthly
Include payment references to link to external payment systems
Record partial payments as they’re received
Monitor payment_status to identify overdue invoices

Getting started

Billing and invoicing

Implementation guides

Overview

Payment terms

Payment term types

NET

END_OF_MONTH

Setting payment terms

Due date calculation

Payment status

`open`

`due`

Partially paid

`paid`

Attaching payments

Full payment

Partial payment or detailed record

Payment parameters

Payment reconciliation

Automatic reconciliation

Multiple payments

Credit notes and payment balance

Best practices

​Overview

​Payment terms

​Payment term types

​NET

​END_OF_MONTH

​Setting payment terms

​Due date calculation

​Payment status

​open

​due

​Partially paid

​paid

​Attaching payments

​Full payment

​Partial payment or detailed record

​Payment parameters

​Payment reconciliation

​Automatic reconciliation

​Multiple payments

​Credit notes and payment balance

​Best practices

Overview

Payment terms

Payment term types

NET

END_OF_MONTH

Setting payment terms

Due date calculation

Payment status

`open`

`due`

Partially paid

`paid`

Attaching payments

Full payment

Partial payment or detailed record

Payment parameters

Payment reconciliation

Automatic reconciliation

Multiple payments

Credit notes and payment balance

Best practices