> For the complete documentation index, see [llms.txt](https://docs.trybit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trybit.com/pt/start/how-it-works.md). # Como a integração funciona Cada método de integração é construído em torno de uma fatura: o seu sistema cria-a, o cliente paga-a e a Trybit reporta o resultado. Compreender este ciclo ajuda-o a conceber corretamente o processamento de pagamentos do seu lado — quando entregar os bens, como tratar o pagamento insuficiente e como reconciliar os dados. ### Como funciona a interação A sua plataforma → API da Trybit → página de pagamento da Trybit ou a sua interface (H2H) → cliente → blockchain → POSTBACK para o seu servidor * **A sua plataforma** — um website, app ou bot do Telegram onde o cliente faz uma encomenda. * **API da Trybit** — aceita pedidos de criação de faturas e devolve os dados de pagamento. * **Página de pagamento ou a sua interface** — onde o cliente vê o montante e os detalhes de pagamento: a página de pagamento da Trybit ou, com H2H, a sua própria interface. * **Blockchain** — a rede em que a transação do cliente é processada e confirmada. * **POSTBACK** — uma notificação que a Trybit envia para o seu servidor depois de o pagamento ser confirmado. ### Como uma fatura é paga 1. **Criação da fatura.** O seu sistema envia um [pedido de criação de fatura](/pt/referencia-da-api-v2/create-invoice.md) com a API KEY no cabeçalho, o SHOP ID, o montante, a moeda e, se necessário, o seu número de encomenda (order\_id). 2. **Ligação ou detalhes de pagamento.** Em resposta, a Trybit devolve o número da fatura (INV) e uma ligação para a página de pagamento ou, com H2H, os detalhes de pagamento para mostrar na sua interface. 3. **Pagamento.** O cliente seleciona uma moeda e uma rede e envia uma transferência a partir da sua carteira ou exchange. 4. **Confirmação da rede.** A transação é confirmada na blockchain. O tempo depende da rede: para ERC20, TRC20, BSC (BEP20), TON, SOL, BASE, ARB e OP — de 30 segundos a 5 minutos; para LTC — de 2 a 10 minutos; para BTC — de 10 minutos a várias horas. 5. **POSTBACK.** Assim que o pagamento é confirmado, a Trybit envia um pedido POST para o URL de notificação do projeto no formato selecionado — JSON ou form-data. 6. **Verificação de estado.** Se necessário, o seu sistema pede [informações da fatura](/pt/referencia-da-api-v2/invoice-information.md) pelo número INV. ### Estados da fatura | **Estado** | **Significado** | | -------------------- | ------------------------------------------------- | | Criada | A fatura foi emitida e está à espera de pagamento | | Paga | O pagamento foi creditado na totalidade | | Parcialmente paga | Foi recebido menos do que o valor da fatura | | Pagamento em excesso | Foi recebido mais do que o valor da fatura | | Cancelada | A fatura não foi paga; expirou | Saiba mais [na página de Estados da Fatura na Base de Conhecimento](https://support.trybit.com/payments/invoice-statuses). ### Como os cenários de pagamento diferem | **Cenário** | **Onde o cliente paga** | **O que o seu sistema faz** | | -------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------- | | Página de pagamento (API, módulos CMS) | Na página de pagamento da Trybit | Cria uma fatura, redireciona o cliente através da ligação e processa o POSTBACK | | Host2Host (H2H) | Na sua interface, sem redirecionamento | Cria uma fatura, apresenta os detalhes de pagamento e acompanha o estado via API e POSTBACK | | Widget HTML | Numa janela incorporada no seu website | Insere código pronto; POSTBACK apenas com o método "Widget HTML (com postback)" | | Carteiras estáticas | Por transferência para um endereço permanente | Cria uma carteira uma vez e recebe notificações de depósitos sem criar novas faturas | ### Como processar um POSTBACK do seu lado 1. Aceite o pedido POST no URL de notificação. As notificações são enviadas apenas para as portas 443 e 80. 2. Verifique a autenticidade: o parâmetro token é um JWT assinado com a SECRET KEY do projeto usando o algoritmo HS256. O token é válido por 5 minutos a partir do momento em que é enviado, por isso o tempo do servidor deve estar sincronizado. 3. Compare o número da fatura, o montante e a moeda com os dados da encomenda no seu sistema. 4. Processe cada fatura apenas uma vez: se uma notificação para o mesmo invoice\_id chegar novamente, não entregue os bens outra vez. 5. Devolva uma resposta com o código 200. {% hint style="info" %} O estado de entrega de cada notificação é mostrado na secção "Histórico de postback" do painel, onde a notificação também pode ser reenviada. A secção está localizada na página da fatura paga: "Pagamentos" → a fatura relevante. Os parâmetros e exemplos de manipuladores estão disponíveis [na página de POSTBACK Automático](/pt/referencia-da-api-v2/postback.md). {% endhint %} ### Como reconciliar os dados da fatura Antes de entregar os bens ou em caso de discrepâncias, solicite [informações da fatura](/pt/referencia-da-api-v2/invoice-information.md) pelo número INV — um único pedido devolve dados de até 100 faturas. O montante efetivamente recebido, incluindo o pagamento em excesso, também pode ser verificado na secção "Pagamentos" do painel. ### Pagamento insuficiente, pagamento em excesso e faturas expiradas * **Pagamento insuficiente** — a fatura recebe o estado "Parcialmente paga". O cliente pode pagar o valor restante; pode confirmar a fatura manualmente na secção "Pagamentos" ou configurar a confirmação automática para pequenas diferenças na secção "Taxas" das definições do projeto. * **Pagamento em excesso** — creditado na totalidade. O seu sistema pode mostrar o valor original, uma vez que a fatura foi criada para esse valor. * **Fatura expirada** — se o pagamento não for confirmado antes de a fatura expirar, não é creditado automaticamente. Para que seja creditado, contacte o suporte com o número INV e o TXID. * **Pagamento repetido** — um pagamento repetido para uma fatura já paga não é creditado automaticamente, apenas através do suporte. Saiba mais [na página de Problemas de Pagamento da Fatura](https://docs.trybit.com/api-reference-v2/invoice-information). {% hint style="success" %} Se tiver alguma dúvida ou precisar de assistência, contacte o nosso chat de suporte no website e no painel, ou fale connosco no Telegram. Os contactos de suporte estão listados no nosso [website](https://trybit.com/support). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.trybit.com/pt/start/how-it-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.