Pular para o conteúdo principal
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. 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. 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.
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. O webhook pode chegar mais de uma vez: atualize o pedido de forma idempotente, como em conciliação.

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.
  • 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.

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:
TypeScript
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:
CSP
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:
TypeScript
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:<porta> e http://127.0.0.1:<porta> 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.