Integração H2H (White Label)

Criação de uma fatura para integração Host2Host: parâmetros da requisição, resposta e apresentação dos detalhes de pagamento na sua interface.

Host2Host (H2H) é um método de integração em que os dados de pagamento são devolvidos na resposta da API, e o cliente paga a fatura na sua interface sem ser redirecionado para a página de pagamento da Trybit. Adequa-se a checkouts personalizados, aplicações móveis e terminais. Saiba mais sobre o cenário na página Host2Host (White Label) na Base de Conhecimento.

Campos de resposta necessários para um checkout personalizado

Campo	O que mostrar ao cliente
address	Endereço de transferência
amount	Montante exato a pagar em criptomoeda
currency.code, currency.name	Criptomoeda de pagamento
currency.network.code, currency.network.fullname	Rede de transferência
expiry_date	Hora de expiração da fatura — para o temporizador. A hora está em UTC+0
uuid	Número da fatura (INV)
amount_in_fiat, fiat_currency	Montante da fatura em moeda fiduciária
MEMO / Comentário	MEMO / Comentário — para a rede TON

O que deve ser mostrado ao cliente

• Endereço e rede de transferência.

• Montante exato em criptomoeda.

• MEMO / Comentário — para a rede TON.

• Um temporizador de contagem decrescente até a fatura expirar.

• Um código QR com o endereço.

• Um aviso: o remetente paga a taxa da rede, da carteira ou da exchange por cima do valor da fatura. Se for recebido menos, a fatura receberá o estado "Parcialmente paga".

MEMO / Comentário

O MEMO / Comentário é obrigatório para pagamentos na rede TON. Sem ele, o sistema não consegue identificar o pagamento, e este não será creditado automaticamente — esse pagamento só pode ser creditado na fatura manualmente através do suporte. Para faturas na rede TON, apresente o MEMO / Comentário junto ao endereço e avise o cliente de que deve ser especificado ao fazer a transferência.

Subpagamento, sobrepagamento e pagamento adicional

Subpagamento. Se for recebido menos do que o valor da fatura, a fatura fica com o estado parcial ("Parcialmente paga"). Antes de a fatura expirar, o cliente pode pagar a diferença para o mesmo endereço. Mostre o montante em falta na sua interface. Também pode confirmar a fatura manualmente na secção "Pagamentos" ou configurar a confirmação automática para pequenas diferenças na secção "Taxas".

Sobrepagamento. A fatura recebe o estado de sobrepaga ("Sobrepaga") e é creditada na íntegra.

O que acontece quando uma fatura expira

Se o pagamento não for recebido antes de expiry_date, a fatura passa para o estado cancelado. O pagamento de uma fatura expirada não é creditado automaticamente — para que seja creditado, contacte o suporte com o número INV e o TXID. Para permitir que o cliente pague a encomenda, crie uma nova fatura — será emitido um novo endereço para ela.

Pagamento repetido para o mesmo endereço

Um endereço é válido apenas para uma fatura. Uma transferência repetida para o endereço de uma fatura já paga não é creditada automaticamente — apenas através do suporte. Se os clientes precisarem de pagar para um endereço permanente, use carteiras estáticas.

Como processar um POSTBACK

• Após o pagamento, a Trybit envia um pedido POST para o URL de notificação do projeto — apenas para as portas 443 e 80.

• O parâmetro token é um JWT assinado com a CHAVE SECRETA do projeto usando o algoritmo HS256. O token é válido por 5 minutos a partir do momento em que é enviado, pelo que a hora do servidor deve estar sincronizada.

• Processe cada fatura apenas uma vez: se chegar uma notificação repetida para o mesmo invoice_id, não entregue os produtos novamente.

• Se a notificação não tiver chegado, verifique o estado com uma Informação da Fatura pedido por número INV.

Os parâmetros de notificação e exemplos de manipuladores estão disponíveis na página de POSTBACK Automático.

Como testar H2H

1. No modo de teste, crie uma fatura com o parâmetro cryptocurrency — da mesma forma que acontecerá quando um cliente fizer uma encomenda.

2. Verifique se os detalhes de pagamento são apresentados corretamente na sua interface.

3. Na secção "Pagamentos", mude para "Teste", abra a fatura e clique em "Confirmar fatura sem pagamento".

4. Certifique-se de que o POSTBACK é entregue e que o estado da encomenda é atualizado.

Saiba mais na página Testar a Integração.

Acesso e restrições

O H2H está disponível para todos os projetos sem ativação separada — basta passar o parâmetro cryptocurrency ao criar uma fatura. As moedas, redes, limites e requisitos do projeto são os mesmos que para outros métodos de integração.

• Os montantes mínimos por moeda estão listados na página Moedas, Redes e Limites.

• A criptomoeda especificada no parâmetro cryptocurrency deve estar ativada na secção "Moedas do projeto".

Diagrama de sequência do pedido

Plataforma do cliente → API da Trybit (criação de fatura com criptomoeda) → detalhes de pagamento na interface da plataforma → cliente → blockchain → POSTBACK para o URL de notificação → verificação de estado por INV.

Se tiver alguma dúvida ou precisar de assistência, contacte o nosso chat de apoio no website e no painel, ou fale connosco no Telegram. Os contactos de suporte estão listados no nosso sítio Web.