# sinnu developers > Construa com a sinnu. Guias de integração, SDK TypeScript, componentes e referência da API de pagamentos. > ## Agent Instructions > Documentação oficial da sinnu, gateway de pagamento brasileiro: Pix e cartão de crédito. O índice de todas as páginas está em https://docs.sinnu.com.br/llms.txt. > A API (https://api.sinnu.com.br) e o checkout (https://pay.sinnu.com.br) documentados são de produção. Não há ambiente público de testes: cada chamada cria ou altera dados reais. > A chave secreta sk_live_ fica só no servidor. O navegador recebe apenas o slug do link ou a URL do checkout. > Unidades: amountCents do link e os valores de /api/transactions/ estão em centavos (inteiro). data.amount do webhook e amount das transações de um link estão em reais. Compare na mesma unidade. > Status: a API de transações usa approved; o corpo do webhook usa paid; o evento é transaction.approved. > Libere o pedido só pelo webhook assinado (X-Sinnu-Signature, validado sobre o corpo cru com constructEvent({ payload, signature, secret })) e confirme com transactions.get. Nunca pelo evento completed do Sinnu Elements nem pelos parâmetros da URL de retorno. > Estorno é sempre do valor total. Não invente métodos, campos ou eventos: confira na referência do SDK e da API. # Atualize um cliente Source: https://docs.sinnu.com.br/api/clientes/atualizar PATCH /api/customers/{id}/ Altere parcialmente os dados de um cliente. Envie somente os campos que deseja modificar. Preserve o identificador usado nos vínculos da sua aplicação. # Consulte um cliente Source: https://docs.sinnu.com.br/api/clientes/consultar GET /api/customers/{id}/ Busque um cliente pelo identificador. O recurso precisa pertencer à empresa vinculada à chave de API. # Crie um cliente Source: https://docs.sinnu.com.br/api/clientes/criar POST /api/customers/ Cadastre os dados de um cliente na empresa. Envie somente os dados necessários ao cadastro (`phone` é opcional). Se você deseja criar o link já com os dados do comprador preenchidos em uma única chamada, envie o objeto `customer` diretamente em [`POST /api/payment-links`](/api/links/criar). # Liste clientes Source: https://docs.sinnu.com.br/api/clientes/listar GET /api/customers/ Consulte os clientes da empresa autenticada. A empresa é determinada pela chave de API. Use os identificadores retornados para buscar os detalhes. # Referência da API Source: https://docs.sinnu.com.br/api/introducao Consulte o contrato público de links de pagamento, clientes e transações. Todas as chamadas desta referência usam a URL base: ```text Produção theme={null} https://api.sinnu.com.br ``` Autentique no servidor com `Authorization: Bearer SUA_CHAVE_SECRETA`. O contexto de empresa vem da chave. > [card] [Links de pagamento](/api/links/criar) > > Crie a oferta e obtenha o slug do checkout. > [card] [Transações](/api/transacoes/listar) > > Consulte o resultado de cada pagamento. > [card] [Clientes](/api/clientes/listar) > > Gerencie os clientes da empresa. > [card] [Eventos](/guias/webhooks) > > Receba mudanças no seu servidor. ## Convenções * **Links** usam caminhos sem barra final, como `/api/payment-links`. * **Transações e clientes** usam barra final, como `/api/transactions/`. * **Listas** usam paginação com `page` e `pageSize`. * **Valores** dependem do recurso. Confira [a tabela de unidades](/fundamentos/valores-e-status). ## Contrato legível por ferramentas [Baixe o OpenAPI público](/api/openapi.yaml) para importar em ferramentas de desenvolvimento. Esta referência contém a superfície para integradores; rotas administrativas não fazem parte dela. Os exemplos são copiáveis. O envio interativo de requisições está desativado neste portal, pois a URL documentada é de produção. # Arquive um link Source: https://docs.sinnu.com.br/api/links/arquivar DELETE /api/payment-links/{id} Retire um link de circulação. Arquivar o link não estorna transações anteriores. O método `sinnu.links.archive(id)` não retorna um objeto. # Atualize um link Source: https://docs.sinnu.com.br/api/links/atualizar PATCH /api/payment-links/{id} Altere os campos de um link da empresa. Envie apenas os campos que deseja alterar, incluindo `customer`, `linkedCustomer` ou `maxPayments`. Os status do link são `active`, `paused` e `archived`. # Consulte um link Source: https://docs.sinnu.com.br/api/links/consultar GET /api/payment-links/{id} Busque um link pelo identificador retornado na criação. Use o `id` do link no caminho. O `slug` serve para a URL pública do checkout. # Crie um link de pagamento Source: https://docs.sinnu.com.br/api/links/criar POST /api/payment-links Defina o preço e os métodos de pagamento da sua oferta. `amountCents` é expresso em centavos. A criação retorna um link; o pagamento ocorre quando o comprador conclui o checkout. Para pré-preencher os dados do comprador em uma única chamada ou limitar a quantidade de pagamentos aprovados, envie `customer` e `maxPayments` conforme o guia de [links de pagamento](/guias/links-de-pagamento#dados-do-comprador-no-checkout). Veja também o [primeiro link](/inicio/primeiro-link). # Liste links de pagamento Source: https://docs.sinnu.com.br/api/links/listar GET /api/payment-links Consulte os links da empresa com paginação. Use `page` e `pageSize`. No SDK, a operação corresponde a `sinnu.links.list()`. # Liste as transações de um link Source: https://docs.sinnu.com.br/api/links/transacoes GET /api/payment-links/{id}/transactions Encontre os pagamentos associados a um link. O campo `amount` desta resposta está em **reais**, diferente da API de transações. Um link pode ter várias transações. # Consulte uma transação Source: https://docs.sinnu.com.br/api/transacoes/consultar GET /api/transactions/{id}/ Confira o estado atual de um pagamento pelo identificador. Use esta consulta para [conciliar um evento](/guias/conciliacao). O `amount` retornado está em centavos. # Estorne uma transação Source: https://docs.sinnu.com.br/api/transacoes/estornar POST /api/transactions/{id}/refund/ Solicite uma devolução total de um pagamento. Esta operação altera uma transação real e exige o escopo `transactions:refund` na chave. Confira a decisão de devolução antes de executar. O contrato não oferece valor parcial. Após timeout, consulte a transação antes de repetir. # Liste transações Source: https://docs.sinnu.com.br/api/transacoes/listar GET /api/transactions/ Consulte os pagamentos da empresa com filtros e paginação. Os valores monetários dessa resposta são expressos em centavos. Uma aprovação aparece com `status: approved`. # Ajuda com sua integração Source: https://docs.sinnu.com.br/comunidade/ajuda Reúna o contexto necessário para investigar uma dúvida ou falha. Envie sua dúvida para [suporte@sinnu.com.br](mailto:suporte@sinnu.com.br). ## Para dúvidas de implementação Conte o resultado desejado, a linguagem ou framework e a página que você está seguindo. Se o problema for de instalação, inclua a versão do runtime e a origem do pacote. ## Para uma requisição que falhou Use este modelo, removendo chaves e dados pessoais: ```text Modelo de atendimento theme={null} Assunto: Integração — resumo do problema Recurso: link / transação / webhook Operação: método HTTP e caminho Horário e fuso: Status HTTP: Identificador do recurso: Resultado esperado: Resultado observado: Exemplo mínimo sem segredos: ``` Não envie `Authorization`, chave de API, segredo de webhook, dados de cartão ou um dump completo do cliente. ## Antes de abrir o chamado | Problema | Confira primeiro | | - | - | | `npm install @sinnu-dev/sdk` retorna `404` | [Disponibilidade do SDK](/sdk/instalacao). | | Chamada não autentica | [Autenticação](/fundamentos/autenticacao). | | Valor parece cem vezes maior ou menor | [Unidades dos valores](/fundamentos/valores-e-status). | | Assinatura inválida | Corpo original e segredo em [webhooks](/guias/webhooks). | | Pagamento repetido na sua aplicação | [Processamento idempotente](/guias/conciliacao). | Para notificações operacionais pelo Discord, consulte a configuração de integrações no painel e peça ao suporte orientação sobre os eventos disponíveis para sua empresa. # Melhore esta documentação Source: https://docs.sinnu.com.br/comunidade/contribuir Ajude a tornar cada instrução mais precisa, útil e fácil de seguir. Você pode contribuir apontando um passo que não funciona, uma explicação ambígua ou um exemplo que ajudaria sua integração. ## Envie uma correção Compartilhe com [suporte@sinnu.com.br](mailto:suporte@sinnu.com.br): 1. O endereço da página. 2. O trecho que precisa mudar. 3. O comportamento que você verificou. 4. Uma sugestão de texto ou um exemplo mínimo, quando possível. ## Compartilhe um exemplo Prefira exemplos com uma tarefa definida e poucas dependências. Informe linguagem, versão, pré-requisitos e resultado esperado. Remova credenciais, dados pessoais e identificadores de clientes reais. ## Como avaliamos uma contribuição O conteúdo precisa refletir o contrato atual, explicar unidades e estados e indicar limites relevantes. Exemplos de pagamento precisam separar interface, servidor e confirmação. Uma sugestão para uma funcionalidade nova não significa que ela já esteja disponível. A documentação deve deixar essa diferença visível para quem está implementando. # Exemplos por tarefa Source: https://docs.sinnu.com.br/comunidade/exemplos Vá direto ao código que resolve a próxima etapa da sua integração. | Sua tarefa | Exemplo | Resultado | | - | - | - | | Fazer a primeira chamada | [Primeiro link com cURL](/inicio/primeiro-link) | Um link e um slug para abrir o checkout. | | Criar um link em TypeScript | [SDK de links](/sdk/links) | Um objeto `PaymentLink` tipado. | | Usar Next.js | [Integração no servidor](/sdk/nextjs) | Serviço de criação separado da interface. | | Receber eventos | [Handler de webhook](/sdk/webhooks) | Validação antes da persistência. | | Acompanhar pagamentos | [Conciliação](/guias/conciliacao) | Atualização idempotente do pedido. | | Percorrer transações | [Paginação](/sdk/paginacao-e-erros) | Processamento progressivo da listagem. | | Abrir o checkout em React | [Botão de pagamento](/elements/botao-de-pagamento) | Navegação sem chave no navegador. | | Embutir o checkout no seu site | [Início rápido do Sinnu Elements](/elements/inicio-rapido) | Pix e cartão num elemento seguro da sinnu, sem chave no navegador. | | Ver uma integração completa | [Exemplo: propostas pagas pelo WhatsApp](/elements/exemplo-propostas) | App Next.js que cria um link por proposta, cobra no elemento `payment` e libera pelo webhook. | | Usar seus campos e seu botão | [Elemento payment](/elements/pagamento) | `confirm()` com o comprador do seu formulário. | | Exibir o estado | [Status de pagamento](/elements/status-de-pagamento) | Mensagem acessível e valor formatado. | ## Convenções dos exemplos Valores, nomes, e-mails e identificadores são fictícios. Substitua placeholders pelo recurso retornado à sua empresa. Os exemplos com SDK pressupõem que você já [obteve o pacote](/sdk/instalacao). Uma demonstração de interface não simula um pagamento. As chamadas para `api.sinnu.com.br` usam produção. # Construa junto com a sinnu Source: https://docs.sinnu.com.br/comunidade/visao-geral Encontre exemplos, compartilhe o contexto da sua integração e ajude a melhorar a documentação. Uma boa integração começa com uma resposta clara e continua com exemplos que funcionam. Esta área reúne os caminhos para quem desenvolve com a sinnu. > [card] [Encontre um exemplo](/comunidade/exemplos) > > Escolha pela tarefa que você precisa resolver. > [card] [Peça ajuda](/comunidade/ajuda) > > Envie o contexto certo para investigar sua integração. > [card] [Sugira uma melhoria](/comunidade/contribuir) > > Mostre o que ficou confuso ou compartilhe um exemplo. > [card] [Explore o Sinnu Elements](/elements/visao-geral) > > Elementos embutidos e receitas de interface para o seu produto. ## Canal de contato Fale com **[suporte@sinnu.com.br](mailto:suporte@sinnu.com.br)**. Informe que o assunto é uma integração e inclua a página ou o recurso relacionado. Os canais públicos de colaboração serão listados aqui quando estiverem disponíveis. Os exemplos e guias deste portal já podem orientar sua implementação pela API. # Acessibilidade nas interfaces Source: https://docs.sinnu.com.br/elements/acessibilidade Faça o fluxo de pagamento funcionar com teclado, leitura assistiva e diferentes tamanhos de tela. ## A ação precisa ser compreensível Use rótulos como “Ir para o pagamento” e “Consultar pagamento”. Para navegação, prefira uma âncora; para uma ação no estado da página, um botão. ## O estado precisa estar escrito “Aguardando pagamento”, “Pagamento aprovado” e “Pagamento não aprovado” devem aparecer como texto. Não dependa de um ponto colorido ou de uma animação. Quando a situação mudar sem recarregar a página, use uma região de status. Evite anunciar o mesmo texto repetidamente a cada consulta. ## Teclado e foco Todos os controles precisam de foco visível. Ao abrir um modal, leve o foco para seu conteúdo, permita fechar por teclado e devolva o foco ao elemento que o abriu. ## Formulários e erros Associe `label` e campo. Mostre o erro próximo ao campo, explique o que corrigir e preserve os valores preenchidos. Erros de comunicação não devem apagar o pedido nem levar a uma nova cobrança automática. ## Tamanho e contraste Mantenha alvos de toque de pelo menos 44 × 44 px nas receitas deste portal. Confira contraste em ambos os temas e teste zoom de 200%, tela de 320 px e preferência por movimento reduzido. ## Verifique o fluxo completo Percorra do botão ao retorno do checkout só com teclado. Confira estados de espera, aprovação, recusa e falha de rede. A revisão visual de uma tela não comprova a acessibilidade da integração inteira. # Aparência Source: https://docs.sinnu.com.br/elements/aparencia As variáveis de cor, cantos e fonte que o Sinnu Elements aceita, e os limites de cada uma. Ajuste o elemento à identidade do seu site com seis variáveis. Elas valem para todos os elementos criados pela mesma instância de `createElements`. ```ts TypeScript theme={null} import { createElements } from "@sinnu-dev/elements"; const elements = createElements({ link: "abc12345", appearance: { variables: { colorPrimary: "#C6F211", colorBackground: "#FFFFFF", colorText: "#111111", colorDanger: "#D92D20", borderRadius: "8px", fontFamily: "system", }, }, }); ``` ![Elemento checkout com a aparência padrão da sinnu.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=f83dab92d073c6351347e3cbe5d74eae) Padrão ![O mesmo elemento checkout com a cor da marca, cantos mais arredondados e a fonte Inter.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/aparencia-marca.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=64a41ab9b076fdba7a60db8ae8d36495) Com a cor, os cantos e a fonte da marca ## Variáveis | Variável | Valores aceitos | Onde aparece | | - | - | - | | `colorPrimary` | `#RGB` ou `#RRGGBB` | Botão de pagar, destaques e anel de foco. O texto sobre essa cor fica preto ou branco, o que tiver mais contraste. | | `colorBackground` | `#RGB` ou `#RRGGBB` | Fundo do elemento e dos painéis. | | `colorText` | `#RGB` ou `#RRGGBB` | Texto principal. | | `colorDanger` | `#RGB` ou `#RRGGBB` | Mensagens de erro. | | `borderRadius` | Inteiro de `0px` a `24px` | Cantos de campos, botões e painéis. | | `fontFamily` | `system`, `inter` ou `geist` | Fonte do elemento. `system` usa a fonte do sistema do comprador. | Sem uma variável, o elemento usa o visual padrão do checkout da sinnu. ## Limites * **Só esses formatos.** Nomes de cor (`red`), `rgb()`, transparência, unidades diferentes de `px` e valores decimais não são aceitos. * **Valor inválido é ignorado**, sem derrubar o elemento: o resto da aparência continua valendo. Uma variável desconhecida também é ignorada. * **Nada vira CSS.** Não é possível injetar seletores, classes ou folhas de estilo no elemento: ele aplica só essas seis variáveis, depois de validá-las de novo. * **A fonte vem da sinnu.** Não dá para carregar uma fonte própria dentro do elemento. Para conferir o que será aplicado, use `sanitizeAppearance`: ela devolve só as variáveis válidas. ```ts TypeScript theme={null} import { sanitizeAppearance } from "@sinnu-dev/elements"; sanitizeAppearance({ variables: { colorPrimary: "lime", borderRadius: "12px" } }); // { borderRadius: "12px" } ``` ## Mudar a aparência A aparência vai na URL do elemento. Para mudar, crie outra instância e monte o elemento de novo; o que o comprador preencheu se perde. Em React, mudar o conteúdo de `appearance` recria o elemento. Garanta contraste suficiente entre `colorText` e `colorBackground`. Veja também os [fundamentos visuais](/elements/fundamentos-visuais) e a [acessibilidade](/elements/acessibilidade). # Botão de pagamento Source: https://docs.sinnu.com.br/elements/botao-de-pagamento Uma âncora acessível para abrir o checkout a partir de um slug público. Use este componente depois de criar um link no servidor. Ele não cria cobranças: apenas navega para o checkout. ## Prévia PRÉVIA VISUAL Ir para o pagamento O exemplo visual não inicia uma cobrança. ## Código ```tsx payment-button.tsx theme={null} type PaymentButtonProps = { slug: string | null; label?: string; }; export function PaymentButton({ slug, label = "Ir para o pagamento", }: PaymentButtonProps) { if (!slug?.trim()) { return ; } const href = new URL(encodeURIComponent(slug), "https://pay.sinnu.com.br/").href; return {label}; } ``` ## Propriedades | Prop | Tipo | Descrição | | - | - | - | | `slug` | `string \| null` | Slug retornado pela sinnu. `null` exibe o estado indisponível. | | `label` | `string` | Texto da ação. Padrão: “Ir para o pagamento”. | ```tsx Uso theme={null} ``` O componente restringe a URL à origem do checkout e codifica o slug. Para navegação, ele usa uma âncora nativa, que preserva os comportamentos de teclado e de abertura em outra aba. ## Estilo sugerido ```css CSS theme={null} .sinnu-pay-button { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: 12px 22px; border: 0; border-radius: 999px; background: #C6F211; color: #0A0B09; font: inherit; font-weight: 600; text-decoration: none; } .sinnu-pay-button:focus-visible { outline: 3px solid currentColor; outline-offset: 4px; } .sinnu-pay-button:disabled { opacity: 0.5; cursor: not-allowed; } ``` Mantenha uma ação principal por etapa. Se abrir uma nova aba por escolha do seu produto, informe esse comportamento no texto acessível. # Elemento checkout Source: https://docs.sinnu.com.br/elements/checkout O formulário completo da sinnu dentro do seu site: resumo, comprador, Pix ou cartão e o botão de pagar. O elemento `checkout` coloca o checkout inteiro na sua página, num componente seguro da sinnu. O comprador vê o resumo do produto, preenche os dados dele, escolhe Pix ou cartão e paga, sem sair do seu site. Você escreve só a montagem e as reações aos eventos. ![Elemento checkout montado numa página de loja: resumo do pedido, dados do comprador, Pix ou cartão e o botão de pagar.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=f83dab92d073c6351347e3cbe5d74eae) Antes, confira os [requisitos](/elements/visao-geral): recurso liberado, domínio cadastrado e um link de venda avulsa. ## Código ```ts elements-checkout.ts theme={null} import { createElements } from "@sinnu-dev/elements"; type Order = { slug: string; orderId: string }; type CheckoutScreen = { showThanks(transactionId: string): void; showError(message: string): void; }; export function mountCheckout(target: string | HTMLElement, order: Order, screen: CheckoutScreen) { const elements = createElements({ link: order.slug, reference: order.orderId }); const checkout = elements.create("checkout"); checkout.on("completed", ({ transactionId }) => screen.showThanks(transactionId)); checkout.on("error", ({ message }) => screen.showError(message)); checkout.mount(target); return () => elements.destroy(); } ``` ```html Contêiner theme={null}
``` O elemento ocupa 100% da largura do contêiner. A altura começa em 120 px e acompanha o conteúdo pelo evento `resize`, sem código seu. Limite a largura pelo contêiner, por exemplo com `max-width: 560px`. ## Opções de `createElements` | Opção | Tipo | Descrição | | - | - | - | | `link` | `string` | Obrigatória. Slug do link de pagamento: até 64 caracteres entre letras, números, `-` e `_`. | | `reference` | `string` | Pedido no seu sistema. Até 255 caracteres, sem os espaços das pontas; vazia é ignorada. Volta como `reference` na transação, no webhook e no evento `completed`. | | `appearance` | `object` | Cores, cantos e fonte. Veja [aparência](/elements/aparencia). | | `baseUrl` | `string` | Padrão `https://pay.sinnu.com.br`. Homologação: `https://pay-sandbox.sinnu.com.br`. Precisa de `https://`. | | `locale` | `"pt-BR"` | Único valor aceito na v1. | | `loadTimeoutMs` | `number` | Prazo para o elemento carregar (evento `ready`), em milissegundos, de `1000` a `120000`. Padrão: `15000` (15 s). Esgotado, o elemento emite `error` com `load_timeout`. | Uma opção inválida lança `SinnuElementsError` com `invalid_config` na hora, com uma mensagem que diz o que corrigir. `createElements` não toca no DOM: pode rodar no servidor. Os elementos criados por uma instância compartilham link, referência e aparência. Para outro pedido, crie outra instância. ## Métodos | Método | O que faz | | - | - | | `elements.create("checkout")` | Cria o elemento. Ainda não aparece na página. | | `checkout.mount(alvo)` | Monta o elemento dentro do alvo: um seletor CSS, como `"#pagamento"`, ou um `HTMLElement`. | | `checkout.on(evento, handler)` | Escuta um evento. Devolve uma função que cancela a escuta. | | `checkout.unmount()` | Tira o elemento da página. Ele pode ser montado de novo. | | `checkout.destroy()` | Tira o elemento e os handlers. O elemento não pode mais ser usado. | | `elements.destroy()` | Destrói todos os elementos da instância e para de escutar mensagens. | Montar duas vezes sem `unmount()` lança `invalid_config`. Numa aplicação de página única, chame `elements.destroy()` quando a tela do pagamento sair. ## Eventos que importam aqui | Evento | Use para | | - | - | | `ready` | Esconder o seu indicador de carregamento. `methods` lista os meios disponíveis no link; vazio quando o link não está disponível agora (pausado, por exemplo). | | `completed` | Mostrar o "obrigado" ou levar o comprador para a próxima tela. Traz `transactionId`, `method`, `amountCents` (centavos) e `reference`. | | `failed` | Registrar a falha. O próprio formulário mostra o erro ao comprador e continua usável. | | `pix_created` | Saber que o QR Code está na tela, com `expiresAt` (ISO 8601). | | `expired` | Saber que o Pix venceu sem pagamento. O formulário volta para uma nova tentativa. | | `error` | Mostrar uma alternativa: o elemento não montou ou não carregou no prazo (`load_timeout`). | Os payloads e todos os códigos estão em [eventos e erros](/elements/eventos). ## O que o comprador vê > [tab] Pix > > ![Pix gerado dentro do elemento checkout: QR Code, contagem até o vencimento e o botão de copiar o código.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-pix.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=408ba1ec83c94818a2d9732e55cc41bf) > [tab] Cartão > > ![Cartão de crédito escolhido no elemento checkout: número, validade, CVV e parcelas.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-cartao.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=a4395fd0a19a3988d5a5495aa43f48bb) > [tab] Aprovado > > ![Pagamento aprovado dentro do elemento checkout, com o valor, o meio e o número do pedido.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-aprovado.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=905fa1dd6ef34dc80f6145b7982e9a33) * **Pix**: o QR Code e o copia e cola aparecem dentro do elemento, com a contagem até o vencimento. Quando o pagamento é confirmado, o elemento mostra a aprovação e você recebe `completed`. * **Cartão**: parcelas e juros seguem o link. Se o emissor recusar a primeira tentativa e a autenticação do banco (3DS) estiver disponível, o desafio abre dentro do elemento. Veja [como o 3DS entra](/elements/seguranca#autenticação-do-banco-3ds). Aprovado, o elemento mostra a confirmação e você recebe `completed`. * **Recusa**: o comprador vê o motivo no formulário e pode tentar outro cartão. * **Comprador vinculado**: quando o link possui cliente vinculado (`customer` ou `linkedCustomer`), nome, e-mail, telefone (se informado) e CPF/CNPJ mascarado já abrem preenchidos, com opção de alterar. * **Link pausado**: o elemento mostra que o pagamento está indisponível. O elemento não navega. O `redirectUrl` do link vale para o checkout hospedado; no Sinnu Elements, quem decide a próxima tela é a sua página, no evento `completed`. > [!WARNING] > > `completed` roda no navegador do comprador. Use para a interface e libere o pedido pelo webhook `transaction.approved` ou consultando a transação no seu servidor. Veja [segurança](/elements/seguranca). > [card] [Só os meios de pagamento](/elements/pagamento) > > Use o elemento `payment` com o seu formulário. > [card] [Em React](/elements/react) > > O mesmo elemento como componente. # Eventos e erros Source: https://docs.sinnu.com.br/elements/eventos Referência dos eventos do Sinnu Elements, dos códigos de failed e error e da classe SinnuElementsError. Todo elemento avisa a sua página por eventos. Escute com `element.on(evento, handler)`, que devolve uma função para cancelar a escuta. Em React, cada evento vira uma prop (`ready` → `onReady`, `pix_created` → `onPixCreated`). ```ts TypeScript theme={null} const off = checkout.on("completed", ({ transactionId, amountCents }) => { // amountCents em centavos: 19900 é R$ 199,00. }); off(); // para de escutar ``` Um erro lançado dentro de um handler é reportado como erro não tratado, no console, e não impede os outros handlers. O loader só aceita mensagens que vêm do elemento, da origem `pay.sinnu.com.br` e do canal daquele elemento; o resto é descartado em silêncio. ## Eventos | Evento | Payload | Quando | | - | - | - | | `ready` | `{ element, methods }` | O formulário está pronto. Uma vez por montagem. | | `resize` | `{ height }` | A altura do conteúdo mudou. O loader já ajusta a altura do elemento. | | `change` | `{ method, complete }` | O comprador trocou de método, ou o cartão ficou completo ou incompleto. | | `processing` | `{ requestId? }` | A cobrança começou. | | `pix_created` | `{ transactionId, amountCents, expiresAt, qrCode, requestId? }` | O QR Code foi gerado e está na tela, dentro do elemento. | | `completed` | `{ transactionId, status, method, amountCents, reference?, requestId? }` | Pagamento aprovado: cartão na hora, Pix quando o pagamento é confirmado. | | `failed` | `{ code, message, retryable, requestId? }` | A cobrança falhou. O formulário continua usável. | | `expired` | `{ transactionId }` | O Pix venceu sem pagamento. | | `error` | `{ code, message }` | O elemento não montou. É fatal para ele. | ### Campos | Campo | Valor | | - | - | | `element` | `"checkout"` ou `"payment"`. | | `methods` | Meios disponíveis no link: `"pix"` e `"card"`. Vazio quando o link não está disponível agora, como um link pausado. | | `height` | Altura do conteúdo, em px: inteiro de 0 a 10000. | | `method` | `"pix"` ou `"card"`. | | `complete` | No Pix, sempre `true`. No cartão, `true` com número, validade e CVV válidos. | | `transactionId` | ID da transação, o mesmo de `GET /api/transactions/{id}`. | | `amountCents` | Valor em **centavos**. `19900` é R\$ 199,00. | | `expiresAt` | Vencimento do QR Code, em ISO 8601. | | `qrCode` | O Pix copia e cola. | | `status` | Sempre `"approved"` no `completed`. | | `reference` | O `reference` com que o elemento foi montado, quando houver. | | `requestId` | Presente quando o evento responde a um `confirm()` do elemento `payment`. | O `completed` serve para a interface. Libere o pedido pelo webhook `transaction.approved` ou consultando a transação no servidor: veja [segurança](/elements/seguranca). ## Códigos de `failed` | Código | Significado | | - | - | | `card_declined` | O cartão foi recusado ou a autenticação do banco não foi concluída. | | `invalid_customer` | Os dados do comprador enviados no `confirm()` não passaram na validação. | | `invalid_card` | Os dados do cartão estão incompletos ou inválidos. | | `rate_limited` | Muitas tentativas em pouco tempo. Aguarde antes de tentar de novo. | | `link_unavailable` | O link não está disponível para pagamento agora, por exemplo pausado. | | `network_error` | Falha de conexão do comprador ou do elemento. | | `unknown` | Outra falha. Com `retryable: false`, o desfecho é incerto ou o pagamento já foi concluído: consulte a transação antes de cobrar de novo. É o que chega quando a cobrança é bloqueada porque o pagamento já foi aprovado ou ainda está em confirmação. | Decida pelo `retryable` que chega com cada falha. `message` vem em pt-BR, pronta para mostrar ao comprador, sem detalhe interno. `rate_limited` e `network_error` também podem chegar logo ao montar, sem `requestId`, quando o link não pôde ser carregado. Nesse caso, monte de novo depois de alguns segundos. ## Códigos de `error` | Código | Significado | O que fazer | | - | - | - | | `origin_not_allowed` | A origem da página não está entre os domínios permitidos da empresa. | Cadastre a origem exata em **Configurações → Checkout embutido → Domínios permitidos**. | | `link_not_found` | O slug não corresponde a um link. | Confira o slug. | | `unsupported_link` | O link é só de assinatura. A v1 vende só avulso; um link que também aceita compra avulsa abre nela. | Use um link de venda avulsa. | | `invalid_request` | Os parâmetros da URL do elemento são inválidos. | Monte o elemento pelo loader, sem alterar a URL do elemento. | | `load_timeout` | O elemento não mandou `ready` dentro de `loadTimeoutMs` (padrão 15 s). Emitido pelo loader. | Em geral, o domínio da página não está cadastrado e o navegador bloqueou o elemento. Confira **Domínios permitidos** e o console. | Depois de um `error`, o elemento não serve mais para cobrar: `confirm()` rejeita com o mesmo erro. Ofereça uma alternativa, como o link do checkout hospedado. ## `SinnuElementsError` Todo erro do pacote é uma `SinnuElementsError`, com: | Propriedade | Descrição | | - | - | | `code` | Um código de `failed`, de `error` ou do loader. | | `message` | Em `failed` e `error`, texto em pt-BR para o comprador. Nos códigos do loader, texto para quem integra. | | `retryable` | `true` quando o comprador pode tentar de novo. | ```ts TypeScript theme={null} import { SinnuElementsError } from "@sinnu-dev/elements"; try { await payment.confirm({ customer }); } catch (error) { if (error instanceof SinnuElementsError && error.retryable) { mostrarAviso(error.message); } } ``` ### Códigos do loader | Código | Quando | | - | - | | `invalid_config` | Opção ou argumento inválido em `createElements`, `create`, `mount`, `on` ou `confirm`. Lançado na hora: é erro de integração. | | `confirm_in_progress` | Já há um `confirm()` em andamento neste elemento. | | `timeout` | O `confirm()` não recebeu resposta no prazo. A cobrança pode ter acontecido: consulte a transação. | | `unmounted` | O elemento foi desmontado com um `confirm()` pendente. Consulte a transação. | | `destroyed` | O elemento foi destruído com um `confirm()` pendente, ou foi usado depois de destruído. | | `not_mounted` | O `` ainda não montou o elemento. | | `unsupported_environment` | Sem navegador (por exemplo, `mount()` no servidor), página fora de `http(s)` ou sem `crypto.getRandomValues`. | # Exemplo completo: propostas pagas pelo WhatsApp Source: https://docs.sinnu.com.br/elements/exemplo-propostas Um app Next.js de propostas que cria um link por proposta, cobra no elemento payment e libera o pedido só pelo webhook. O **Propostiva** é o app de exemplo do Sinnu Elements: o sistema de propostas de uma agência fictícia. A agência monta a proposta, envia o link pelo WhatsApp, e o cliente paga com Pix ou cartão na própria página da proposta, pelo [elemento `payment`](/elements/pagamento). Serve de modelo para qualquer negócio que vende produto, serviço ou software e quer receber dentro do próprio site. O endereço do ambiente de demonstração (sandbox) é `https://propostiva.sinnu.cloud`: um domínio fora da sinnu, como o site de um cliente. Nenhum pagamento feito lá é real. ## Como funciona **1. A agência cria a proposta** O servidor do app cria um link de pagamento para a proposta, com o total, o máximo de parcelas e quem paga os juros. Junto nasce um pedido no banco do app; o `id` dele é a `reference`. **2. A agência envia pelo WhatsApp** A mensagem leva o endereço da página da proposta. O endereço tem um token aleatório e nenhum dado pessoal. **3. O cliente paga na página da proposta** A página coleta nome, e-mail, celular e CPF ou CNPJ e chama `confirm({ customer })`. O QR Code do Pix, os campos do cartão e o desafio do banco ficam dentro do elemento. **4. O webhook libera o pedido** O evento assinado `transaction.approved` marca o pedido como pago. A página, que consultava o servidor do app desde o `completed`, mostra a confirmação. O link é arquivado para ninguém pagar de novo por ele. ## Onde está cada parte O que é integração com a sinnu fica separado do produto fictício. Copie a integração e troque o resto pelo seu sistema. | Parte | No exemplo | O que faz | | - | - | - | | Cliente da API | `src/sinnu/client.ts` | O SDK com a chave secreta. Só roda no servidor. | | Link por proposta | `src/sinnu/payment-link.ts` | O corpo de `links.create`, em centavos. | | Pedido | `src/sinnu/orders.ts` | Os estados do pedido: aguardando, pago, estornado, contestado. | | Webhook | `src/sinnu/webhook.ts` e `src/app/api/webhooks/sinnu/route.ts` | Assinatura, conferências e idempotência. | | Status para a página | `src/app/api/propostas/[token]/status/route.ts` | Diz à página se o pedido já está pago. | | Tela de pagamento | `src/components/public/pay-panel.tsx`, `src/sinnu/payment-flow.ts` e `src/sinnu/use-payment-flow.ts` | O elemento `payment`, o `confirm()` e o que a tela mostra em cada evento. | | Content Security Policy | `next.config.ts` | Libera o elemento do checkout em `frame-src`. | ## Um link por proposta O valor de cada proposta é diferente, e o elemento cobra pelo link. Por isso o app cria um link para cada proposta: ```ts TypeScript theme={null} const link = await sinnu.links.create({ title: proposal.title, amountCents: proposalTotalCents(proposal.items), // centavos methods: ["pix", "credit_card"], maxInstallments: proposal.maxInstallments, interestMode: proposal.interestPaidBy === "client" ? "pass_to_customer" : "absorb", externalReference: proposal.id, }); ``` A chave precisa dos escopos `links:write`, para criar e arquivar o link, e `transactions:read`, para conferir a venda no webhook. Veja [escopos](/fundamentos/autenticacao). ## Libere só pelo webhook O `completed` e o resultado do `confirm()` rodam no navegador do cliente. No exemplo, eles só mudam a tela para "confirmando". Quem marca o pedido como pago é o webhook, depois de quatro conferências: ```ts TypeScript theme={null} // 1. A assinatura, sobre o corpo cru da requisição. const event = sinnu.webhooks.constructEvent({ payload: rawBody, signature, secret }); // 2. A referência é um pedido seu, e a venda é do link desse pedido. const order = await orders.get(event.data.reference); if (!order || event.data.link?.id !== order.linkId) return ok(); // 3. O valor, na mesma unidade: a transação na API vem em centavos. const tx = await sinnu.transactions.get(event.data.id); if (tx.status === "pending") throw new Error("ainda pending"); // responda 5xx: a sinnu reenvia if (tx.status !== "approved" || tx.reference !== order.id) return ok(); if (tx.productAmount !== order.amountCents) return ok(); // 4. Idempotente: o pedido só sai de "aguardando" uma vez. await orders.markPaidIfPending(order.id, tx.id); ``` * **`data.amount` vem em reais** e inclui os juros quando o cliente paga o parcelamento. Por isso o exemplo compara `productAmount`, o preço antes dos juros, em centavos. Veja [valores e status](/fundamentos/valores-e-status). * **A mesma entrega pode chegar mais de uma vez**, e fora de ordem. No banco, a marcação é um `UPDATE ... WHERE id = ? AND status = 'pending'`, conferindo as linhas afetadas. * **Transação ainda `pending` na API**: responda 5xx. Com 200, a sinnu daria o evento por entregue. * **Arquive o link depois de pago** (`sinnu.links.archive`). O exemplo faz isso depois de responder ao webhook, para a resposta sair rápido. ## A tela de pagamento * **Confirmando até o servidor dizer que está pago.** Depois do `completed`, a página consulta o servidor do app até ele responder que o pedido está pago. * **Volta do app do banco.** Quem paga Pix pelo celular sai para o app do banco e volta. Quando a aba fica visível de novo, a página consulta na hora. * **Recarregar não cobra de novo.** Entre o `completed` e o webhook, o pedido ainda está "aguardando". O exemplo guarda o `transactionId` na aba e, se o cliente recarregar, a tela volta para "confirmando" em vez de mostrar o formulário outra vez. * **Falhas.** A tela decide pelo `retryable` de cada `failed`. Um `unknown` com `retryable: false` pede para conferir antes de cobrar de novo. Veja [eventos e erros](/elements/eventos). ## O que configurar 1. **Sinnu Elements liberado para a empresa.** [Fale com o suporte de integração](/comunidade/ajuda). 2. **A origem exata do site em Domínios permitidos**, em **Configurações → Checkout embutido**. `https://www.loja.exemplo.com.br` é outra origem que `https://loja.exemplo.com.br`. Veja [domínios permitidos](/elements/seguranca#domínios-permitidos). 3. **Um webhook** assinando `transaction.*`, apontando para a rota do app. Veja [webhooks](/guias/webhooks). 4. **A Content Security Policy do site** com o checkout em `frame-src`. O exemplo usa a variante simples, com `'unsafe-inline'` em `script-src`. Em produção, prefira a variante com nonce. 5. **`reference` e endereços sem dado pessoal.** Use o `id` do pedido e um token aleatório, nunca e-mail, CPF ou telefone. > [card] [Elemento payment](/elements/pagamento) > > O `confirm()` com o comprador do seu formulário. > [card] [Segurança](/elements/seguranca) > > Domínios permitidos, 3DS e liberação do pedido. # Fundamentos visuais Source: https://docs.sinnu.com.br/elements/fundamentos-visuais Cor, tipografia e hierarquia para interfaces claras no ecossistema sinnu. O design system usado nas aplicações da sinnu combina superfícies escuras, destaque lima e texto de alto contraste. Neste portal, o tema claro tem um verde mais escuro para manter a leitura dos links. ## Cor com função | Token da interface | Valor | Papel | | - | - | - | | `brand.lime` | `#C6F211` | Ação principal e destaque. | | `surface.canvas` | `#0A0B09` | Fundo principal escuro. | | `surface.surface` | `#141511` | Superfície de conteúdo. | | `text.primary` | `#F4F4EF` | Texto principal sobre fundo escuro. | | `brand.amber` | `#E8B54A` | Situações de espera. | | `brand.coral` | `#E86A4A` | Atenção e falhas. | Texto sobre lima deve ser escuro. Use texto e ícone para identificar um estado; a cor reforça a mensagem. ## Tipografia **Instrument Sans** sustenta a leitura da interface. **Space Grotesk** aparece em títulos e números de destaque. Use uma fonte monoespaçada para identificadores e código. Não transforme o logotipo em texto com uma fonte parecida: use os arquivos oficiais da marca. ## Hierarquia Reserve o botão lima para a ação principal. Agrupe informações do mesmo pagamento, mostre o valor com sua unidade e escreva a ação por inteiro: “Ir para o pagamento” comunica melhor do que “Continuar” fora de contexto. ## Pacotes internos `@repo/design` contém tokens TypeScript e CSS; `@repo/ui` reúne componentes de interface do workspace. Se você desenvolve dentro do monorepo, use essas fontes. Eles não são publicados: numa aplicação externa, use as receitas desta documentação. O pacote público de interface da sinnu é o `@sinnu-dev/elements`, do Sinnu Elements, que embute o checkout no seu site. As cores, os cantos e a fonte dele se ajustam pela [aparência do Sinnu Elements](/elements/aparencia), não pelos tokens acima. # Início rápido Source: https://docs.sinnu.com.br/elements/inicio-rapido Do link de pagamento ao primeiro pagamento com Pix ou cartão dentro do seu site. Ao terminar, a sua página mostra o checkout da sinnu como um elemento e reage quando o pagamento é aprovado. Leva poucos minutos se o recurso já estiver liberado para a sua empresa. Você precisa de um site servido por `https://`, de acesso ao [painel sinnu](https://app.sinnu.com.br) como Titular ou Administrador da empresa e de um link de pagamento de venda avulsa. Os exemplos usam produção: concluir um pagamento gera uma cobrança real. **1. Peça a liberação** O Sinnu Elements é ativado pela sinnu para cada empresa. Se ainda não estiver, [fale com o suporte de integração](/comunidade/ajuda). **2. Cadastre o domínio do seu site** No painel, abra **Configurações → Checkout embutido → Domínios permitidos** e cadastre a origem exata da página que vai mostrar o elemento, por exemplo `https://loja.exemplo.com.br`. `https://www.loja.exemplo.com.br` é outra origem: cadastre as duas se o site responde nas duas. A mudança pode levar até um minuto para valer. As regras completas estão em [segurança](/elements/seguranca). **3. Pegue o slug do link** O slug é o código público no fim da URL do checkout: em `https://pay.sinnu.com.br/abc12345`, o slug é `abc12345`. Crie o link no painel ou [pela API](/inicio/primeiro-link). **4. Monte o elemento** Escolha entre o arquivo pronto, via ` ``` * `link` é o slug do link de pagamento; `reference` é o pedido no seu sistema, que volta na transação e no webhook. * `completed` serve só para a interface: o pedido é liberado pelo webhook. * `error` chega quando o elemento não montou ou não carregou em 15 s (`load_timeout`). A `message` já vem pronta para o comprador. `@0.1` recebe as correções da versão 0.1. Para fixar uma versão exata, use `@0.1.1`. Se preferir, sirva o arquivo `dist/sinnu-elements.global.js` do seu próprio domínio. **Com npm**, em projetos com bundler: ```bash Terminal theme={null} npm install @sinnu-dev/elements ``` ```ts elements-checkout.ts theme={null} import { createElements } from "@sinnu-dev/elements"; type Order = { slug: string; orderId: string }; type CheckoutScreen = { showThanks(transactionId: string): void; showError(message: string): void; }; export function mountCheckout(target: string | HTMLElement, order: Order, screen: CheckoutScreen) { const elements = createElements({ link: order.slug, reference: order.orderId }); const checkout = elements.create("checkout"); checkout.on("completed", ({ transactionId }) => screen.showThanks(transactionId)); checkout.on("error", ({ message }) => screen.showError(message)); checkout.mount(target); return () => elements.destroy(); } ``` ```ts Uso theme={null} const destroy = mountCheckout("#pagamento", { slug: "abc12345", orderId: "pedido-123" }, { showThanks: (transactionId) => showThanks(transactionId), showError: (message) => showError(message), }); ``` O pacote pode ser importado no servidor (SSR) sem quebrar: só `mount()` precisa do navegador. Em React, use os [componentes prontos](/elements/react). **5. Libere o elemento na sua Content Security Policy** Se o seu site envia o cabeçalho `Content-Security-Policy`, libere a página da sinnu em `frame-src` e, se usar o arquivo da CDN, a origem dele em `script-src`: ```text CSP theme={null} frame-src https://pay.sinnu.com.br; script-src 'self' https://cdn.jsdelivr.net; ``` **6. Libere o pedido pelo webhook** Configure o [webhook](/guias/webhooks) e libere o pedido no evento assinado `transaction.approved`. O `data.reference` dele traz o `reference` com que o elemento foi montado. O evento `completed` serve só para a interface. ## Se o elemento não aparecer | O que acontece | Causa provável | O que fazer | | - | - | - | | O elemento fica em branco ou mostra um erro do navegador e, depois de 15 s, chega `error` com `load_timeout`. O console cita `frame-ancestors`. | O domínio da página não está cadastrado, nenhum domínio foi cadastrado ou o recurso não foi liberado para a empresa. O navegador bloqueia o elemento antes de ele carregar. | Confira a origem exata em **Domínios permitidos** e aguarde até um minuto. | | O console cita `frame-src` ou `script-src`. | A Content Security Policy do seu site bloqueou o elemento ou o arquivo da CDN. | Libere as origens do passo anterior. | | Evento `error` com `link_not_found`. | O slug não existe. | Confira o slug do link. | | Evento `error` com `unsupported_link`. | O link é só de assinatura. | Use um link de venda avulsa. | | Evento `error` com `origin_not_allowed`. | A origem informada ao elemento não está entre os domínios permitidos, por exemplo numa URL do elemento montada à mão. | Monte o elemento pelo loader, numa página do domínio cadastrado. | | Evento `failed` com `rate_limited` ou `network_error` logo ao montar. | O link não pôde ser carregado naquele momento. | Monte de novo depois de alguns segundos, com `unmount()` e `mount()`. | | `invalid_config` lançado na hora. | Opção inválida, como slug vazio ou `baseUrl` sem `https://`. | Leia a mensagem do erro: ela diz qual opção corrigir. | Em qualquer `error`, ofereça uma alternativa ao comprador, como um link para o checkout hospedado do mesmo link e pedido (`https://pay.sinnu.com.br/abc12345?ref=pedido-123`). O prazo de carregamento muda com a opção `loadTimeoutMs`. A tabela completa de códigos está em [eventos e erros](/elements/eventos). > [card] [Elemento checkout](/elements/checkout) > > Opções, eventos e o que o comprador vê. > [card] [Elemento payment](/elements/pagamento) > > Seus campos, seu botão e o `confirm()`. # Elemento payment Source: https://docs.sinnu.com.br/elements/pagamento Só Pix e cartão dentro do elemento: sua página coleta o comprador, mostra o botão e chama confirm(). O elemento `payment` mostra só os meios de pagamento: a escolha entre Pix e cartão e os campos do cartão. O resto da tela é seu: o formulário do comprador, o resumo do pedido e o botão de pagar. Quando o comprador confirma, a sua página chama `payment.confirm({ customer })` e o elemento cobra no método escolhido. ![Página de loja com o formulário do comprador e, abaixo, o elemento payment com a escolha entre Pix e cartão.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=df718a83498ad4805cf8d1b8d11816e8) Antes, confira os [requisitos](/elements/visao-geral). As opções de `createElements` e os métodos `mount`, `on`, `unmount` e `destroy` são os mesmos do [elemento checkout](/elements/checkout). ## Código O exemplo monta o elemento e traduz o resultado do `confirm()` em quatro situações para a sua interface: Pix gerado, pagamento aprovado, nova tentativa ou conferência no servidor. ```ts elements-payment.ts theme={null} import { createElements, SinnuElementsError, type CustomerInput, type PaymentElement, type SinnuElementsErrorCode, } from "@sinnu-dev/elements"; type Order = { slug: string; orderId: string }; type PaymentScreen = { setComplete(complete: boolean): void; showPaid(transactionId: string): void; showPixExpired(): void; }; export function mountPayment(target: string | HTMLElement, order: Order, screen: PaymentScreen) { const elements = createElements({ link: order.slug, reference: order.orderId }); const payment = elements.create("payment"); payment.on("change", ({ complete }) => screen.setComplete(complete)); payment.on("completed", ({ transactionId }) => screen.showPaid(transactionId)); payment.on("expired", () => screen.showPixExpired()); payment.mount(target); return { payment, destroy: () => elements.destroy() }; } export type PaymentOutcome = | { status: "pix"; transactionId: string; qrCode: string; expiresAt: string } | { status: "approved"; transactionId: string; amountCents: number } | { status: "retry" | "check" | "stop"; code: SinnuElementsErrorCode; message: string }; const MAY_HAVE_BEEN_CHARGED = new Set(["timeout", "unmounted", "destroyed", "unknown"]); export async function pay( payment: Pick, customer: CustomerInput, ): Promise { try { const result = await payment.confirm({ customer }); if (result.type === "pix_created") { const { transactionId, qrCode, expiresAt } = result; return { status: "pix", transactionId, qrCode, expiresAt }; } return { status: "approved", transactionId: result.transactionId, amountCents: result.amountCents }; } catch (error) { if (!(error instanceof SinnuElementsError)) throw error; const { code, message } = error; if (error.retryable) return { status: "retry", code, message }; if (MAY_HAVE_BEEN_CHARGED.has(code)) return { status: "check", code, message }; return { status: "stop", code, message }; } } ``` ```html Formulário theme={null}
``` ```ts Uso theme={null} const form = document.querySelector("#pedido")!; const button = document.querySelector("#pagar")!; const notice = document.querySelector("#aviso")!; const { payment } = mountPayment("#meios-de-pagamento", { slug: "abc12345", orderId: "pedido-123" }, { setComplete: (complete) => { button.disabled = !complete; }, showPaid: () => { notice.textContent = "Pagamento aprovado."; }, showPixExpired: () => { notice.textContent = "O Pix venceu. Gere um novo para continuar."; }, }); function readCustomer(data: FormData) { return { name: String(data.get("name")), email: String(data.get("email")), document: String(data.get("document")), phone: String(data.get("phone")), }; } form.addEventListener("submit", async (event) => { event.preventDefault(); button.disabled = true; const outcome = await pay(payment, readCustomer(new FormData(form))); if (outcome.status === "pix") notice.textContent = "Pague com o QR Code acima."; if ("message" in outcome) notice.textContent = outcome.message; if (outcome.status === "retry") button.disabled = false; }); ``` Habilite o botão pelo evento `change`: no Pix ele chega sempre com `complete: true`; no cartão, `complete` fica `true` quando número, validade e CVV estão preenchidos de forma válida. ## `confirm({ customer, timeoutMs })` | Campo | Tipo | Descrição | | - | - | - | | `customer.name` | `string` | Nome do comprador. | | `customer.email` | `string` | E-mail do comprador. | | `customer.document` | `string` | CPF ou CNPJ. | | `customer.phone` | `string` | Telefone do comprador. | | `timeoutMs` | `number` | Opcional. Prazo para a resposta do elemento, em milissegundos. Padrão: `120000` (120 s). | O elemento valida o comprador com as mesmas regras do checkout hospedado. Dado inválido volta como `invalid_customer`; cartão incompleto, como `invalid_card`. Um campo que não seja texto rejeita na hora. Regras do `confirm()`: * **Antes do `ready`**, ele espera o elemento ficar pronto e é enviado em seguida. * **Um por vez.** Outro `confirm()` com um em andamento rejeita na hora com `confirm_in_progress`. * **Resolve** com `{ type: "pix_created", ... }` ou `{ type: "completed", ... }`. * **Rejeita** com `SinnuElementsError` (`code`, `message`, `retryable`) quando a cobrança falha. * **No `timeout`**, a cobrança pode ter acontecido mesmo assim. Consulte a transação no seu servidor antes de tentar de novo. O mesmo vale para `unmounted` e `destroyed`, quando o elemento sai da página com um `confirm()` pendente. ## Pix `confirm()` resolve assim que o QR Code é gerado, com `type: "pix_created"`, `transactionId`, `amountCents` (centavos), `expiresAt` (ISO 8601) e `qrCode` (o copia e cola). O QR Code, o botão de copiar e a contagem até o vencimento já aparecem dentro do elemento: você não precisa desenhá-los. ![Elemento payment depois do confirm(): Pix gerado com QR Code e contagem até o vencimento.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-pix.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=3db93764b5c7bfca065f37e7d16ae8ba) Depois disso, o desfecho chega por evento: * `completed`, quando o pagamento é confirmado; * `expired`, quando o Pix vence sem pagamento. O elemento volta para a escolha do método e um novo `confirm()` gera outro Pix. Enquanto o QR Code está na tela, um novo `confirm()` responde `failed` com `unknown` e `retryable: true`. Esconda o seu botão de pagar até `completed` ou `expired`. ## Cartão `confirm()` resolve com `type: "completed"` quando o cartão é aprovado. Se o emissor recusar a primeira tentativa e a autenticação do banco (3DS) estiver disponível, o desafio abre dentro do elemento e a promessa espera por ele. Veja [como o 3DS entra](/elements/seguranca#autenticação-do-banco-3ds). Parcelas e juros seguem o link. ![Elemento payment com o cartão escolhido: número, validade, CVV e parcelas.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-cartao.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=9bde295f71e1053133c2ecdd17588af6) Cartão preenchido ![Desafio de autenticação do banco aberto dentro do elemento payment, sem sair da página da loja.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-3ds.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=7c278073d4a91ecfa1b5e038268e86e3) Desafio do banco (3DS) dentro do elemento ![Elemento payment com o pagamento aprovado e a confirmação na página da loja.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-aprovado.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=c1bf33365b85507a2c2c18ccc20dacf2) Aprovado | Situação | O que chega | O que fazer | | - | - | - | | Cartão recusado | `card_declined`, `retryable: true` | Mostre `message` e deixe o comprador tentar de novo ou trocar de cartão. | | Dados do cartão incompletos | `invalid_card`, `retryable: true` | Peça para conferir os campos do cartão. | | Sem confirmação a tempo | `unknown`, `retryable: false` | Consulte a transação no servidor antes de cobrar de novo. | | Pagamento já concluído neste elemento | `unknown`, `retryable: false` | Não cobre de novo: siga para a tela de sucesso. | ## Trate o `failed` Decida pelo `retryable` recebido, e não só pelo código: * `retryable: true`: mostre `message` e deixe o comprador tentar de novo. A mensagem já vem em pt-BR, pronta para o comprador. * `retryable: false` com `unknown`, `timeout`, `unmounted` ou `destroyed`: o desfecho é incerto. Consulte a transação antes de oferecer outra cobrança. * `retryable: false` com outro código, como `link_unavailable`: não ofereça nova tentativa. A lista completa está em [eventos e erros](/elements/eventos). ## O que o elemento `payment` não mostra Resumo do produto, campos do comprador, endereço e botão de pagar ficam de fora. Se o link pede o endereço do comprador, use o [elemento checkout](/elements/checkout): o `confirm()` envia só nome, e-mail, documento e telefone. > [!WARNING] > > `completed` e a promessa do `confirm()` rodam no navegador do comprador. Libere o pedido pelo webhook `transaction.approved` ou consultando a transação no seu servidor. Veja [segurança](/elements/seguranca). # Sinnu Elements em React Source: https://docs.sinnu.com.br/elements/react Os componentes SinnuCheckout e SinnuPayment, com confirm() pela ref. Em React, use os componentes de `@sinnu-dev/elements/react`. `` é o [elemento checkout](/elements/checkout) e `` é o [elemento payment](/elements/pagamento), com `confirm()` exposto pela `ref`. Eles funcionam com React 18 ou superior. ```bash Terminal theme={null} npm install @sinnu-dev/elements ``` ## Código O `PaymentStep` usa a função `pay` do [exemplo do elemento payment](/elements/pagamento), que aceita tanto o elemento quanto a `ref` do ``. ```tsx elements-react.tsx theme={null} "use client"; import { useRef, useState } from "react"; import { SinnuCheckout, SinnuPayment, type CustomerInput, type SinnuPaymentHandle, } from "@sinnu-dev/elements/react"; import { pay, type PaymentOutcome } from "./elements-payment"; type Order = { slug: string; orderId: string }; export function EmbeddedCheckout({ order, onPaid }: { order: Order; onPaid(transactionId: string): void }) { return ( onPaid(transactionId)} style={{ maxWidth: 560 }} /> ); } export function PaymentStep({ order, customer }: { order: Order; customer: CustomerInput }) { const payment = useRef(null); const [complete, setComplete] = useState(false); const [busy, setBusy] = useState(false); const [paid, setPaid] = useState(false); const [outcome, setOutcome] = useState(null); async function handlePay() { if (!payment.current) return; setBusy(true); try { setOutcome(await pay(payment.current, customer)); } finally { setBusy(false); } } const waitingForPix = outcome?.status === "pix"; const canPay = !paid && !waitingForPix; return (
setComplete(event.complete)} onCompleted={() => setPaid(true)} onExpired={() => setOutcome(null)} /> {outcome && "message" in outcome &&

{outcome.message}

} {canPay && ( )}
); } ``` ```tsx Uso theme={null} ``` `slug` e `orderId` vêm do seu servidor. No Next.js (App Router), carregue o pedido num Server Component e passe só esses dois valores para o componente de cliente. A chave de API não entra na árvore do cliente. ## Props As mesmas nos dois componentes. | Prop | Tipo | Descrição | | - | - | - | | `link` | `string` | Obrigatória. Slug do link de pagamento. | | `reference` | `string` | Pedido no seu sistema, até 255 caracteres. | | `appearance` | `Appearance` | Veja [aparência](/elements/aparencia). | | `baseUrl` | `string` | Padrão `https://pay.sinnu.com.br`. | | `locale` | `"pt-BR"` | Único valor aceito na v1. | | `loadTimeoutMs` | `number` | Prazo para carregar, em milissegundos. Padrão: `15000`. Esgotado, chama `onError` com `load_timeout`. | | `className`, `style` | | Aplicados ao `
` que recebe o elemento. | | `onReady`, `onResize`, `onChange`, `onProcessing`, `onPixCreated`, `onCompleted`, `onFailed`, `onExpired`, `onError` | função | Um handler por [evento](/elements/eventos), com o mesmo payload. | ## Quando o elemento é recriado O elemento só é recriado quando muda `link`, `reference`, `baseUrl`, `locale`, `loadTimeoutMs` ou o conteúdo de `appearance`. Um objeto `appearance` novo com o mesmo conteúdo não remonta nada, e trocar os handlers a cada render também não. Recriar o elemento descarta o que o comprador preencheu nele. Evite mudar essas props durante o pagamento. ## A `ref` do `` A `ref` expõe só `confirm({ customer, timeoutMs })`, com as mesmas regras do [elemento payment](/elements/pagamento). Antes de o componente montar o elemento, `confirm()` rejeita com `not_mounted`. ## Renderização no servidor Os componentes já trazem `"use client"`. No servidor, renderizam só o `
`; o elemento é criado no navegador, depois da montagem. O seu componente precisa de `"use client"` quando usa hooks, como o `PaymentStep` acima. # Segurança do Sinnu Elements Source: https://docs.sinnu.com.br/elements/seguranca Domínios permitidos, o que fica fora do seu site e como liberar o pedido sem confiar no navegador. O Sinnu Elements foi desenhado para que a sua página nunca veja o cartão nem guarde segredo. Em troca, três coisas ficam com você: cadastrar os domínios certos, liberar o pedido só pelo servidor e manter a chave de API fora do navegador. ## O que fica fora da sua página * **Dados do cartão.** Número, validade e CVV só existem dentro do elemento, servido por `pay.sinnu.com.br`. O navegador isola o elemento da sua página: ela não consegue ler esse conteúdo. Por isso a sua página pode se enquadrar no questionário SAQ A do PCI DSS; a avaliação de conformidade da sua empresa continua sendo sua. * **Segredos.** O elemento usa só o slug do link, que é público. A chave `sk_live_...` e o segredo do webhook ficam no servidor. ## Domínios permitidos O elemento só abre nas páginas cujos domínios a empresa cadastrou no painel, em **Configurações → Checkout embutido → Domínios permitidos**. Qualquer membro da empresa vê a lista; cadastrar e remover é de quem gerencia integrações (Titular ou Administrador). Cada item é uma **origem**: esquema, domínio e porta, exatamente como o navegador mostra em `window.location.origin`. | Você cadastra | Vale para | Não vale para | | - | - | - | | `https://loja.exemplo.com.br` | `https://loja.exemplo.com.br/checkout` e qualquer outro caminho do mesmo domínio. | `https://www.loja.exemplo.com.br`, `https://pagamento.loja.exemplo.com.br` ou `http://loja.exemplo.com.br`. | | `https://loja.exemplo.com.br:8443` | Páginas servidas nessa porta. | A mesma página na porta 443. | Regras do cadastro: * **`https://` obrigatório.** A porta 443 é omitida. * **Cada subdomínio é outra origem.** `www` incluído. Curinga (`*`) não é aceito: cadastre cada endereço. * **Só a origem.** Caminho, `?`, `#`, usuário e senha são recusados. Uma barra no fim é removida. * **Domínio, não IP.** Endereço IP e host sem ponto são recusados. * **Até 20 origens por empresa.** A mesma origem não pode ser cadastrada duas vezes. * **Domínios internacionalizados** são gravados em punycode, como o navegador envia. Uma mudança na lista pode levar até um minuto para valer. Como o navegador confere: a página do elemento responde com `Content-Security-Policy: frame-ancestors` listando as origens da empresa. Fora delas, o navegador bloqueia o elemento antes de ele carregar, e o loader avisa com `error` `load_timeout`. Sem nenhuma origem cadastrada, ou com o recurso desligado para a empresa, nenhuma página consegue embutir o elemento. O checkout hospedado (`https://pay.sinnu.com.br/{slug}`) continua sem poder ser embutido em outra página. ## Mensagens entre a página e o elemento As duas pontas conferem cada mensagem: * o loader só aceita mensagens da origem `pay.sinnu.com.br`, vindas daquele elemento e com o canal aleatório criado para ele; * o elemento só aceita mensagens da página que o embutiu, da origem cadastrada e do mesmo canal, e só envia para essa origem; * mensagem fora do contrato é descartada sem resposta. O elemento recebe apenas três permissões, válidas só para a origem da sinnu: escrever na área de transferência, para o botão de copiar o Pix, e ler acelerômetro e giroscópio, que o antifraude usa como sinal do aparelho. Se o seu site enviar um cabeçalho `Permissions-Policy` que bloqueie esses sensores, o bloqueio do seu site prevalece: o pagamento funciona igual, o antifraude só fica sem esse sinal. ## Libere o pedido pelo servidor O evento `completed` e o resultado do `confirm()` rodam no navegador do comprador, que pode alterar a página. Use-os para a interface, nunca para liberar o pedido. Libere de um destes jeitos: 1. **Webhook assinado `transaction.approved`.** Valide a assinatura como em [webhooks](/guias/webhooks). O `data.reference` traz a referência com que o elemento foi montado. 2. **Consulta no seu servidor.** Com o `transactionId` do evento, chame `GET /api/transactions/{id}` com a sua chave e confira o status. Veja [transações no SDK](/sdk/transacoes). Ao liberar, confira se a referência é de um pedido seu e se o valor bate com o pedido. Atenção às unidades: nos eventos do Sinnu Elements, `amountCents` está em **centavos**; no webhook, `data.amount` está em **reais**. Veja [valores e status](/fundamentos/valores-e-status). O webhook pode chegar mais de uma vez: atualize o pedido de forma idempotente, como em [conciliação](/guias/conciliacao). ## Autenticação do banco (3DS) A primeira tentativa no cartão vai sem desafio. Se o emissor recusar e a autenticação do banco estiver disponível para a sua empresa, o elemento abre o desafio do banco e tenta mais uma vez, com a autenticação. Isso vale para qualquer `threeDsMode` do link. * **O desafio abre dentro do elemento.** O comprador não sai da sua página, e o retorno do banco volta para o próprio elemento. A sua página não precisa fazer nada além de esperar o `completed` ou o `failed`. * **Uma tentativa a mais, no máximo.** Uma segunda recusa chega como `failed` com `card_declined`. * **Só recusa do emissor puxa o desafio.** Se a cobrança for bloqueada porque o pagamento já foi aprovado ou ainda está em confirmação, ou se houver erro de rede ou do servidor, não há desafio: chega `failed` com a mensagem original. Veja os [códigos de `failed`](/elements/eventos#códigos-de-failed). * **Desafio não concluído** chega como `card_declined`. Tempo esgotado ou desafio indisponível chega como `unknown`. ![Desafio de autenticação do banco aberto dentro do elemento payment, na própria página da loja.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-3ds.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=7c278073d4a91ecfa1b5e038268e86e3) ## A referência do pedido O link é o produto e pode ser vendido muitas vezes. Monte cada elemento com `reference` igual ao pedido no seu sistema: ```ts TypeScript theme={null} createElements({ link: "abc12345", reference: "pedido-123" }); ``` A referência tem até 255 caracteres, sem os espaços das pontas. Ela fica gravada na transação e volta como `reference` em `GET /api/transactions`, no `data.reference` do webhook e no evento `completed`. Não coloque dado pessoal do comprador nela: use o identificador do pedido. ## Content Security Policy do seu site Se o seu site envia `Content-Security-Policy`, libere a origem do elemento em `frame-src` e, se usar o arquivo da CDN, a origem dele em `script-src`: ```text CSP theme={null} frame-src https://pay.sinnu.com.br; script-src 'self' https://cdn.jsdelivr.net; ``` Para não depender da CDN, sirva o arquivo `dist/sinnu-elements.global.js` do seu próprio domínio. ## Homologação Se a sinnu liberou o ambiente de homologação para a sua empresa, aponte o elemento para ele com `baseUrl`: ```ts TypeScript theme={null} createElements({ link: "abc12345", baseUrl: "https://pay-sandbox.sinnu.com.br" }); ``` O link e os domínios permitidos precisam existir nesse ambiente, no painel dele; os de produção não valem lá. Na homologação, o painel também aceita `http://localhost:` e `http://127.0.0.1:` para você desenvolver na sua máquina. Em produção, só `https://`. Fora isso, `baseUrl` precisa usar `https://` (`http://` só com `localhost` ou `127.0.0.1`) e ser só a origem, sem caminho. # Status de pagamento Source: https://docs.sinnu.com.br/elements/status-de-pagamento Mostre o estado recebido do servidor sem depender apenas de cor. ## Prévia
Explore os estados
CONSULTORIA INICIAL / EXEMPLO R\$ 99,00 Os estados acima são uma demonstração local. Nenhuma requisição de pagamento é executada. ## Código ```tsx payment-status.tsx theme={null} const labels: Record = { approved: "Pagamento aprovado", pending: "Aguardando pagamento", refused: "Pagamento não aprovado", refunded: "Pagamento estornado", chargeback: "Pagamento contestado", }; type PaymentStatusProps = { status: string; amountCents: number; }; export function PaymentStatus({ status, amountCents }: PaymentStatusProps) { if (!Number.isSafeInteger(amountCents) || amountCents < 0) { throw new Error("Use um valor não negativo em centavos."); } const label = labels[status] ?? "Status a confirmar"; const amount = new Intl.NumberFormat("pt-BR", { style: "currency", currency: "BRL", }).format(amountCents / 100); return (
{label} {amount}
); } ``` ## Propriedades | Prop | Tipo | Descrição | | - | - | - | | `status` | `string` | Status da API de transações. Valores desconhecidos exibem “Status a confirmar”. | | `amountCents` | `number` | Inteiro não negativo em centavos. | ```tsx Uso theme={null} ``` ## De onde vêm os dados Seu servidor consulta a transação e retorna o estado necessário à interface. Não conecte este componente diretamente ao corpo do webhook: nele, `amount` está em reais e a aprovação usa `paid`. O componente anuncia mudanças de texto com `role="status"` e `aria-live="polite"`. Mantenha-o montado durante as atualizações para que tecnologias assistivas recebam a mudança. # Sinnu Elements Source: https://docs.sinnu.com.br/elements/visao-geral Tudo o que você precisa para receber com Pix e cartão no seu site: elementos seguros da sinnu para o pagamento e componentes para a interface em volta deles. Com o Sinnu Elements, o comprador paga com Pix ou cartão sem sair do seu site. O formulário roda num componente seguro servido por `pay.sinnu.com.br`, e a sua página conversa com ele por eventos. Preço, parcelas, juros e meios de pagamento continuam vindo do link de pagamento, como no checkout hospedado. O checkout hospedado (`https://pay.sinnu.com.br/{slug}`) continua sendo o caminho mais simples: um link ou redirecionamento, sem nada para instalar. Use o Sinnu Elements quando o pagamento precisar acontecer dentro da sua página. ## Escolha a peça O Sinnu Elements reúne as peças para cobrar no seu site. Os **elementos** são componentes seguros servidos pela sinnu: recebem o pagamento dentro da sua página. Os **componentes do seu site** ficam no seu código, em volta deles: abrir o checkout e mostrar o resultado. | Peça | Onde roda | O que faz | Quando usar | | - | - | - | - | | [Elemento `checkout`](/elements/checkout) | Servido pela sinnu | Resumo, dados do comprador, Pix ou cartão e o botão de pagar. | Você quer o checkout completo embutido, com o mínimo de código. | | [Elemento `payment`](/elements/pagamento) | Servido pela sinnu | Só os meios de pagamento: Pix e os campos do cartão. | Você já coleta nome, e-mail, documento e telefone no seu formulário e quer o seu próprio botão de pagar. | | [Botão de pagamento](/elements/botao-de-pagamento) | Seu código | Abre o checkout hospedado a partir do slug público do link. | Você quer cobrar com um clique, sem embutir nada. | | [Status de pagamento](/elements/status-de-pagamento) | Seu código | Mostra a situação e o valor que o seu servidor confirmou. | Depois do pagamento, em qualquer uma das opções acima. | ![Elemento checkout numa página: resumo do pedido, dados do comprador, escolha entre Pix e cartão e o botão de pagar.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/checkout-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=f83dab92d073c6351347e3cbe5d74eae) Elemento checkout: o formulário completo ![Elemento payment numa página: o formulário do comprador é da loja, e o elemento mostra só a escolha entre Pix e cartão.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/pagamento-inicio.png?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=df718a83498ad4805cf8d1b8d11816e8) Elemento payment: só os meios de pagamento Os elementos vêm no pacote `@sinnu-dev/elements`, com componentes React em `@sinnu-dev/elements/react`. O botão e o status são receitas React para copiar e adaptar: não há pacote para instalar, e nenhum deles recebe chave de API, segredo de webhook ou dado de cartão. A [aparência](/elements/aparencia) ajusta as cores dos elementos; os [fundamentos visuais](/elements/fundamentos-visuais) e a [acessibilidade](/elements/acessibilidade) valem para tudo. Nos elementos, o QR Code do Pix, o desafio de autenticação do cartão (3DS) e a confirmação do pagamento aparecem dentro do elemento. Veja [como o 3DS entra](/elements/seguranca#autenticação-do-banco-3ds). O elemento ocupa a largura do contêiner e ajusta a altura sozinho. ## O que a sinnu garante > [card] O cartão não passa pela sua página > > Número, validade e CVV só existem dentro do elemento, servido por `pay.sinnu.com.br`. Seu site não tem acesso a eles, o que permite que sua página se enquadre no questionário SAQ A do PCI DSS. > [card] Nenhum segredo no navegador > > O elemento usa só o slug do link, que é público: o mesmo código da URL do checkout. A chave `sk_live_...` fica no seu servidor. > [card] Só nos seus domínios > > O elemento só abre nos domínios cadastrados para a sua empresa. As mensagens entre a página e o elemento são conferidas nas duas pontas. > [card] As mesmas regras do checkout > > A cobrança é a do checkout hospedado: mesmos valores, mesmas parcelas e as mesmas verificações antifraude. Os detalhes estão em [segurança](/elements/seguranca). ## O que você precisa 1. **Sinnu Elements liberado para a sua empresa.** O recurso é ativado pela sinnu. [Fale com o suporte de integração](/comunidade/ajuda) para liberar. 2. **O domínio do seu site cadastrado no painel**, em **Configurações → Checkout embutido → Domínios permitidos**: a origem exata, como `https://loja.exemplo.com.br`. 3. **Um link de pagamento de venda avulsa.** Crie no painel ou [pela API](/inicio/primeiro-link) e guarde o `slug`. 4. **Um webhook configurado.** O pedido é liberado pelo evento assinado `transaction.approved`, não pelo navegador. Veja [webhooks](/guias/webhooks). ## Como um pagamento acontece ![Fluxo de um pagamento: seu servidor entrega à página o slug e o pedido; a página monta o elemento da sinnu; o comprador paga com Pix ou cartão; o evento completed só atualiza a tela; a sinnu envia o webhook transaction.approved ao seu servidor, que libera o pedido.](https://mintcdn.com/sinnu/G5P73YDmE1l48Zth/images/elements/fluxo-pagamento.svg?fit=max\&auto=format\&n=G5P73YDmE1l48Zth\&q=85\&s=f6bd940f83ecb6547f03e3234cbe2e83) **1. Seu servidor escolhe o link e o pedido** Ele entrega à página o `slug` do link e a referência do pedido no seu sistema. Nada de chave de API vai junto. **2. Sua página monta o elemento** O loader `@sinnu-dev/elements` monta o elemento com o slug, a referência e a origem da sua página. **3. O comprador paga dentro do elemento** No Pix, o QR Code aparece no elemento até o pagamento ou o vencimento. No cartão, a aprovação aparece na hora. **4. O seu servidor libera o pedido** O evento `completed` atualiza a sua interface. A liberação vem do webhook `transaction.approved`, que traz a mesma referência do pedido. ## Limitações da v1 * **Só venda avulsa.** Um link só de assinatura não monta: o elemento responde `error` com `unsupported_link`. Um link que também aceita compra avulsa abre só nela. * **Só pt-BR.** A opção `locale` aceita apenas `"pt-BR"`. * **Sem Apple Pay e Google Pay** dentro do elemento. * **O valor vem do link.** Uma sessão com valor definido pelo seu servidor na hora da compra virá em uma versão futura. * **Pixels de rastreamento** configurados no link não rodam dentro do elemento. * **Pix Automático** em breve. ## O pacote O loader é o pacote `@sinnu-dev/elements`: zero dependências, ESM e CommonJS, tipos TypeScript e componentes React em `@sinnu-dev/elements/react`. Ele também tem um arquivo pronto para usar com `