---
title: "Match payment with an existing Transaction | Nuvio Docs"
description: "Matches an existing transaction as the payment for an income or expense."
url: https://nuvio.io/docs/api/match-payment
---

# Match payment with an existing Transaction

POST `/v1/match-payment/{transactionId}`

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

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