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

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

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