Record a new payment

Adds a new payment into for an income or expense. This endpoint also creates a new transaction in the provided account automatically. It works only for manually tracked accounts. If you would like to match an existing transaction with and income or expense please use 'Match Payment' endpoint.

View as Markdown

POST /v1/add-payment

Needs an API key with the write scope.

Parameters

accountId string Required

32-character unique ID of the bank or cash account of the transaction. This payment will be recorded into this account.
description string Required

Description of the payment. Will also be used as the description of the added transaction.

More parameters

invoiceId string

32-character unique ID of the matching Invoice. If this payment does not match with an income, do not include this field while sending your request. you can include expenseId to match with an expense.
expenseId string

32-character unique ID of the matching Expense. If this payment does not match with an expense, do not include this field while sending your request. you can include incomeId to match with an income.
transactionTimestamp integer

Epoch timestamp for the transaction date and time. If both of the fields are provided, transactionTimestamp will be used.
transactionDate string

Date of the transaction, yyyy-MM-dd. If both of the fields are provided, transactionTimestamp will be used.
amount number

The amount of the payment. This amount should be less or equal to matched income or expense's remaining balance.

Returns

The transaction the payment was recorded as.

401: No usable Authorization: Bearer {token} header (1002).
403: The access token is unknown, or lacks the scope this route needs (1001).

POST /v1/add-payment

curl -X POST https://api.nuvio.io/v1/add-payment \
  -H "Authorization: Bearer $NUVIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "description": "Office supplies"
  }'

const response = await fetch('https://api.nuvio.io/v1/add-payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NUVIO_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "description": "Office supplies"
  }),
});
const { data } = await response.json();

import os
import requests

response = requests.post(
    "https://api.nuvio.io/v1/add-payment",
    headers={"Authorization": f"Bearer {os.environ['NUVIO_API_TOKEN']}"},
    json={
        "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "description": "Office supplies",
    },
)
data = response.json()["data"]

Response

{
  "success": true,
  "errors": null,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "accountName": "Acme Supplies",
    "description": "Office supplies",
    "transactionTimestamp": 1,
    "transactionDate": "2026-11-05",
    "amount": 100,
    "currency": "USD",
    "transactionType": "Money In",
    "matchedEntity": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "code": "ACME-01"
    },
    "matchedIncomes": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "invoiceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "matchedAmount": 100
      }
    ],
    "matchedExpenses": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "expenseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "matchedAmount": 100
      }
    ]
  }
}