Checkout redirecionado

O checkout é a página de pagamento da Bitpayway onde o seu cliente paga uma ordem de pagamento. Você não precisa construir uma tela de pagamento: crie a ordem pela API, redirecione o cliente ao gatewayUrl retornado para ela, e o checkout cuida da conexão da carteira, da transferência on-chain e do retorno ao seu site.

Como funciona

1. O seu servidor cria uma ordem de pagamento com POST /api/order. A resposta contém o gatewayUrl, o endereço do checkout da ordem.
2. A sua aplicação redireciona o cliente para o gatewayUrl.
3. O cliente confere a ordem, conecta uma carteira e confirma o pagamento.
4. O checkout acompanha a confirmação na rede e redireciona o cliente para a sua Redirect Success URL.
5. O seu servidor recebe o webhook com o status paid.

Redirecionando o cliente ao checkout

Utilize o gatewayUrl exatamente como a API o retorna. O link identifica a ordem pelo parâmetro de query id:

https://pay.example.com/?id=7f7f5a2a-5c4f-4c6b-9cbb-1f0f4b4e42f2

• O cliente pode pagar enquanto a ordem aceita pagamentos: 30 minutos após a criação. Depois disso, o link exibe a ordem como expirada.
• Qualquer pessoa com o link vê a descrição, o valor e o request ID da ordem. Não coloque dados pessoais ou sensíveis na description da ordem, pois ela é exibida ao cliente como título da ordem.
• Um link sem o parâmetro id exibe Invalid payment link, e um id desconhecido exibe Payment not found.

O que o cliente precisa

• Uma carteira suportada: MetaMask, Coinbase Wallet ou Binance Wallet. A Coinbase Wallet também pode ser usada pelo celular.
• O token da ordem na rede da ordem, como USDT na Ethereum ou USDC na Arbitrum. Veja os ativos e redes suportados.
• ETH na mesma rede para pagar as taxas de rede (gas) das transações da carteira.

Passo a passo

1. Conferir a ordem

O checkout abre com o resumo da ordem:

• Order total: o valor total da ordem e o seu token.
• Status: a situação atual da ordem, como Awaiting payment.
• Título: a description que você enviou ao criar a ordem.
• Request ID: o requestId que você enviou, para que o cliente relacione o pagamento à compra.
• Network e Currency: em qual rede e com qual token a ordem é paga.
• Amount due now: o valor que o cliente vai transferir. É igual ao total da ordem, exceto quando parte dela já foi paga (veja pagamentos parciais).

2. Conectar uma carteira

O cliente clica em Connect wallet e escolhe uma carteira. Em seguida, a carteira pede ao cliente que autorize a conexão.

3. Pagar

Com a carteira conectada, o checkout exibe o nome e o endereço dela. O cliente pode usar Change wallet para escolher outra ou clicar em Pay with <carteira> para iniciar o pagamento.

Ao iniciar o pagamento, o checkout pede à carteira que troque para a rede da ordem, caso ela esteja em outra. Depois, o cliente confirma as transações na carteira:

1. Aprovação: autoriza o contrato de pagamento da Bitpayway a transferir exatamente o valor devido. Ela é dispensada quando a carteira já aprovou pelo menos esse valor. Se existir uma aprovação menor, a carteira primeiro pede para zerá-la, como exigem tokens como o USDT.
2. Pagamento: transfere o valor devido ao contrato de pagamento, que o envia para a sua carteira de liquidação na mesma transação.

A Bitpayway nunca pede chaves privadas ou frases de recuperação. Cada transação é conferida e assinada na própria carteira do cliente.

4. Aguardar a confirmação

Depois do envio da transferência, o status muda para Confirming payment enquanto a rede confirma a transação. A página se atualiza sozinha, e o cliente não deve enviar outro pagamento.

5. Voltar ao seu site

Quando o pagamento é confirmado, o status muda para Paid e, cerca de dois segundos depois, o navegador é redirecionado para a sua Redirect Success URL com ?request=<requestId>. Se essa URL não estiver configurada, o cliente permanece no checkout.

O redirecionamento apenas guia o cliente de volta ao seu site. Confirme o pagamento no seu servidor pelo webhook ou consultando a ordem, nunca somente pelo redirecionamento. Os parâmetros do redirecionamento estão descritos em Configuração da conta.

Quando o pagamento não é concluído

Tentativa com falha

Se o cliente rejeitar uma transação na carteira, ou se a transação falhar, o navegador é redirecionado para a sua Redirect Failure URL com ?request=<requestId>. Uma tentativa com falha não encerra a ordem: enquanto ela não expirar, o cliente pode abrir o mesmo gatewayUrl e pagar.

O cliente permanece no checkout, com o botão Try payment again, quando a Redirect Failure URL não está configurada ou quando a ordem é um pagamento multidestino.

Ordem expirada ou cancelada

Uma ordem expirada ou cancelada não pode mais ser paga. O checkout exibe o botão Return to merchant, que leva o cliente para a sua Redirect Failure URL com ?order=<requestId>. Para cobrar o cliente novamente, crie uma nova ordem.

Pagamentos parciais

Se parte da ordem já foi paga, Amount due now exibe apenas o saldo em aberto, e é esse o valor que a carteira é solicitada a transferir. Order total continua exibindo o valor total da ordem.

Pagamentos multidestino

Em um pagamento multidestino, o cliente vê o mesmo checkout: o total da ordem e o valor devido. A divisão do pagamento entre você e o seu parceiro não é exibida.

O cliente não pode pagar com uma carteira que recebe parte da ordem, seja a sua ou a do seu parceiro. O checkout recusa o pagamento e pede outra carteira.

Status exibidos no checkout

Status no checkout	Quando aparece	O que o cliente faz
Awaiting payment	A ordem está pending ou partial paid.	Conecta uma carteira e paga o valor devido.
Confirming payment	A transferência foi enviada e aguarda confirmações de bloco (paid waiting confirmations).	Aguarda na página. Não deve pagar novamente.
Paid	A ordem está paid.	É redirecionado para a sua Redirect Success URL.
Payment failed	A carteira rejeitou a transação ou ela falhou.	É redirecionado para a sua Redirect Failure URL ou tenta novamente no checkout (veja Tentativa com falha).
Expired	A ordem está expired ou expired partial paid.	Volta ao seu site com Return to merchant.
Canceled	A ordem está canceled.	Volta ao seu site com Return to merchant.
Action required	A transferência foi confirmada, mas o checkout não conseguiu registrá-la na Bitpayway.	Clica em Retry notification. Não deve pagar novamente.
Under review	Uma ordem multidestino recebeu valores diferentes da divisão combinada (settlementStatus: mismatch).	Aguarda a sua análise. Não deve pagar novamente.
Payment under review	A Bitpayway ainda não conseguiu verificar a ordem e tenta novamente de forma automática.	Aguarda. Não deve pagar novamente.
Manual review required	A Bitpayway não conseguiu verificar a ordem automaticamente.	Não deve pagar novamente e deve entrar em contato com você. Envie o id da ordem ao suporte da Bitpayway.

Temas claro e escuro

O checkout segue o tema do dispositivo do cliente. O cliente pode alternar entre os temas claro e escuro pelo botão no menu lateral.