PaymentDetails

PaymentDetails era a parte que o comerciante de fato assinava, e o envelope externo apenas carregava o certificado que a comprovava. Continha sete campos: um nome de rede com valor padrão main, uma lista de saídas, um carimbo de data e hora obrigatório, uma expiração opcional, um memo, uma URL de callback e um bloco opaco de merchant_data. Hoje um URI BIP21 mais uma página de checkout fazem o mesmo trabalho sem assinatura e sem servidor.

Como funciona

Status: histórico. O Bitcoin Core removeu o BIP70 na versão 0.20.0 em 3 de junho de 2020, e o PaymentDetails não tem nenhuma implementação ativa. Este site o documenta porque os nomes dos campos ainda aparecem em guias de integração antigos e na referência para desenvolvedores do bitcoin.org.

A estrutura era carregada em Protocol Buffers, não em JSON. Essa escolha importava por um motivo que vale a pena destacar: o comerciante serializava o PaymentDetails em uma cadeia de bytes e colocava esses bytes exatos dentro do PaymentRequest externo como um campo opaco, e não como uma mensagem aninhada. A assinatura cobria a cadeia de bytes, de modo que nenhuma biblioteca que recodificasse os mesmos campos em uma ordem diferente poderia invalidar uma assinatura válida.

Os sete campos se dividiam em instruções e contabilidade.

• network, uma string com valor padrão "main", sendo "test" o único outro valor definido.
• outputs, uma lista repetida, em que cada entrada combina um valor em satoshis com um script. Mais de uma saída era permitida, e os comerciantes usavam isso para dividir um único pagamento do cliente entre uma carteira quente e o armazenamento a frio sem pedir ao cliente que enviasse duas vezes.
• time, um carimbo de data e hora Unix obrigatório que registra quando a solicitação foi criada.
• expires, um carimbo de data e hora Unix opcional após o qual a carteira deveria recusar. Este é o campo que fazia o BIP70 parecer um terminal de cartão, porque o comerciante podia cotar um preço em moeda fiduciária e garanti-lo por um período fixo.
• memo, uma nota em UTF-8 exibida ao pagador.
• payment_url, para onde a carteira enviava sua mensagem Payment depois de transmitir a transação.
• merchant_data, bytes opacos devolvidos sem alteração para que o comerciante pudesse associar um pagamento a um carrinho de compras.

Apenas time e os scripts das saídas eram obrigatórios. Todo o resto o comerciante podia omitir, e a maioria omitia.

Onde você o encontra

A ideia por trás do PaymentDetails sobreviveu à mensagem, e é isso que vale a pena observar.

Hoje a expiração do preço é tratada na corretora, e não na sua carteira. Ao comprar em uma tela de compra instantânea, você recebe uma cotação com um contador ao lado; se o contador chegar a zero, a cotação é refeita ao novo preço. Isso é o expires reimplementado em um aplicativo web, e protege o vendedor da volatilidade exatamente do mesmo modo. O casamento de ordens no livro de ofertas de uma corretora faz o mesmo trabalho de outra forma: nunca cota um preço fixo.

Do lado do comerciante, o equivalente da mensagem inteira é um registro de fatura no software de checkout. O BTCPay Server e ferramentas semelhantes geram um URI BIP21, o mantêm aberto por um número configurado de minutos e conciliam a transação recebida com um identificador interno do pedido, que é precisamente para o que servia o merchant_data.

PaymentDetails vs recibo

O PaymentDetails era a solicitação; o recibo no BIP70 era o PaymentACK que o comerciante devolvia depois. Um descrevia o que deveria acontecer, o outro confirmava que o comerciante tinha visto isso acontecer. Nenhum dos dois era um fato da blockchain, e essa é a limitação que as pessoas subestimaram: um aviso de recebimento assinado por um comerciante prova que o servidor do comerciante disse algo, não que uma transação foi confirmada. São as confirmações, e não os recibos, que liquidam um pagamento em bitcoin.