# Match a payment to an invoice

## Overview

In the vast majority of cases, customers pay exactly the amount stated in the invoice to your crypto wallet. But sometimes a customer makes a mistake and pays something other than the reserved amount. In that case, the service cannot automatically match the payment to the invoice and mark the invoice as paid. If this happens, you as the merchant can match the payment to the invoice manually, provided you are certain which payment you are expecting. You can do this in the dashboard or via the API.

## Matching conditions

The match goes through only when all of the conditions hold at once:

1. **Invoice status**—`unpaid` or `expired`. Canceled and already paid invoices cannot be matched. Cancellation is irreversible.
2. **The payment is not yet matched to another invoice.** One payment can be tied to only one invoice.
3. **The payment arrived at a wallet involved in this invoice.**
4. **The payment fits within the available payment window**—24 hours before and 24 hours after invoice creation. A payment that arrived before the invoice was created can be matched; one outside the window cannot.

If the invoice belongs to another project and the key is restricted to a project, the method responds with `Restricted project`. If any other condition fails, a generic error comes back with no reason given—check the conditions on your side.

## What happens after matching

* The invoice moves to **Paid**.
* Notifications go out to email, the Telegram bot, and the Webhook URL—just as with automatic matching.
* The invoice amount `invoice.amountFiatUSD` **is overwritten with the amount actually received**, converted to USD at the rate at the moment of matching. The original amount in `invoice.amountFiat` does not change.
* The service fee is recalculated at the project's fee rate on the amount you received. On overpayment it is higher than calculated at invoice creation; on underpayment, lower.

## Request

```bash
curl -X POST https://api.bitsby.app/invoices/bindPayment \
  -H "Authorization: Token MSvL2ltaDZdWVjmZURURMVWhqSJLT2NURjhL2Fla1Z1T1IxQTltKs1T3Ay" \
	-F "invoiceId=ade9550d-3dc7-4fd3-b94e-3b4c12aaaa0c" \
	-F "paymentId=a4c9e2ee-9a03-43e5-a1a1-00caf679d16a"
```

## Request parameters

| Parameter   | Data type | Description               | Example                              | Required? |
| ----------- | --------- | ------------------------- | ------------------------------------ | --------- |
| `invoiceId` | UUID      | Invoice ID in UUID format | ade9550d-3dc7-4fd3-b94e-3b4c12aaaa0c | yes       |
| `paymentId` | UUID      | Payment ID in UUID format | a4c9e2ee-9a03-43e5-a1a1-00caf679d16a | yes       |

## Response example

```json
{
   "result":"success",
   "data":"Invoice binded to payment"
}
```