> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nocotax.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments and payouts

> Record customer payments on sales invoices and supplier payouts on purchase invoices.

Nocotax does not collect payments or execute payouts. It records them against invoices, so that balances and reports reflect what was actually settled. Your payment provider and payout system stay the source of truth for the money movements.

## Rules

* Payments are attached to a **finalized** invoice, one invoice at a time.
* The currency of the transaction must be the invoice currency.
* Amounts are integers in the smallest currency unit.
* The payment date is the moment you record it in Nocotax, not the bank date. **Record each payment or payout when it happens**, so that reports show the right payment period.
* Attaching a payment without `transaction_data` pays the full `amount_remaining`.

## Customer payment on a sales invoice

```bash theme={null}
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": 10000,
      "currency": "EUR",
      "transaction_type": "payment",
      "reference": "pi_abc123"
    }
  }'
```

Use your payment provider reference in `reference` to find the payment later.

## Supplier payout on a purchase invoice

```bash theme={null}
curl https://api.nocotax.app/invoices/inv_456/attach_payment \
  -X POST \
  -u ${ACCOUNT_ID}:${YOUR_API_KEY} \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_data": {
      "amount": 11200,
      "currency": "EUR",
      "transaction_type": "transfer",
      "reference": "PAYOUT-2025-12-001"
    }
  }'
```

### One payout covering several invoices

`attach_payment` works per invoice. If one payout settles several purchase invoices, call it once per invoice with the amount allocated to each, and use the same `reference` for all of them.

### Several payout types

Nocotax only counts the costs you record. If your platform has several payout types (for example payouts to individuals, to businesses, or through a third-party payout provider), make sure each one results in purchase invoice lines and a recorded transfer. Then compare, per period, the total of each type in your payout system with the purchase totals in Nocotax: see [Reconciliation and close](https://docs.nocotax.app/undisclosed-agents/reconciliation-and-close.md).

## Transaction types

| `transaction_type` | Use for |
| - | - |
| `payment` | A payment made toward an invoice (card, PayPal...). |
| `transfer` | A movement of funds between accounts, for instance a payout to a supplier. |
| `balance_adjustment` | An existing cash balance applied to an invoice. |

## Payment status

An invoice is `open` before its due date, `due` after it, and `paid` once `amount_remaining` is 0. A partial payment reduces `amount_remaining` and keeps the invoice `open` or `due`. See [Invoice payments](https://docs.nocotax.app/billing-invoicing/invoices/payments.md) for payment terms and examples.

## Refunding a payment

When a credit note has to be refunded or transferred back, attach the money movement to the credit note: see [Refunds and cancellations](https://docs.nocotax.app/undisclosed-agents/refunds-and-cancellations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.