# Vincular um pagamento a uma cobrança

## Visão geral

Na grande maioria dos casos, os clientes pagam exatamente o valor indicado na cobrança para a sua carteira cripto. Mas às vezes um cliente se engana e paga algo diferente do valor reservado. Nesse caso, o serviço não consegue vincular automaticamente o pagamento à cobrança e marcar a cobrança como paga. Se isso acontecer, você, como lojista, pode vincular o pagamento à cobrança manualmente, desde que tenha certeza de qual pagamento está esperando. Você pode fazer isso no painel ou pela API.

## Condições de vinculação

A vinculação só acontece quando todas as condições valem ao mesmo tempo:

1. **Status da cobrança** — `unpaid` ou `expired`. Cobranças canceladas e já pagas não podem ser vinculadas. O cancelamento é irreversível.
2. **O pagamento ainda não está vinculado a outra cobrança.** Um pagamento pode ser ligado a apenas uma cobrança.
3. **O pagamento chegou a uma carteira envolvida nessa cobrança.**
4. **O pagamento cabe na janela de pagamento disponível** — 24 horas antes e 24 horas depois da criação da cobrança. Um pagamento que chegou antes de a cobrança ser criada pode ser vinculado; um fora da janela, não.

Se a cobrança pertencer a outro projeto e a chave estiver restrita a um projeto, o método responde com `Restricted project`. Se qualquer outra condição falhar, volta um erro genérico sem indicar o motivo — verifique as condições do seu lado.

## O que acontece depois da vinculação

* A cobrança passa a **Paga**.
* As notificações saem para o e-mail, o bot do Telegram e a Webhook URL — exatamente como na vinculação automática.
* O valor da cobrança `invoice.amountFiatUSD` **é sobrescrito com o valor efetivamente recebido**, convertido para USD pela cotação do momento da vinculação. O valor original em `invoice.amountFiat` não muda.
* A taxa do serviço é recalculada pela taxa do projeto sobre o valor que você recebeu. Em um pagamento a maior, ela fica mais alta do que a calculada na criação da cobrança; em um pagamento a menor, mais baixa.

## Requisição

```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"
```

## Parâmetros da requisição

| Parâmetro   | Tipo de dado | Descrição                 | Exemplo                              | Obrigatório? |
| ----------- | --------- | ------------------------- | ------------------------------------ | --------- |
| `invoiceId` | UUID      | ID da cobrança no formato UUID | ade9550d-3dc7-4fd3-b94e-3b4c12aaaa0c | sim       |
| `paymentId` | UUID      | ID do pagamento no formato UUID | a4c9e2ee-9a03-43e5-a1a1-00caf679d16a | sim       |

## Exemplo de resposta

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