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

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

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