---
title: "Record a new payment | Nuvio Docs"
description: "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."
url: https://nuvio.io/docs/api/add-payment
---

# Record a new payment

POST `/v1/add-payment`

Needs an API key with the [`write`](https://nuvio.io/docs/api/authentication#scopes) 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"
  }'
```

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
      }
    ]
  }
}
```