Match payment with an existing Transaction

Matches an existing transaction as the payment for an income or expense.

View as Markdown

POST /v1/match-payment/{transactionId}

Needs an API key with the write scope.

Path parameters

transactionId string Required

Parameters

amount number Required

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

More parameters

incomeId string, nullable

32-character unique ID of the matching income. 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, nullable

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.

Returns

The transaction with its matched items.

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

POST /v1/match-payment/{transactionId}

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

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

import os
import requests

response = requests.post(
    "https://api.nuvio.io/v1/match-payment/7c9e6679-7425-40de-944b-e07fc1f90ae7",
    headers={"Authorization": f"Bearer {os.environ['NUVIO_API_TOKEN']}"},
    json={
        "amount": 100,
    },
)
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
      }
    ]
  }
}