O que você precisa
| Campo | O que faz |
|---|---|
| Access token | Permite chamarmos o Square para criar o link de checkout. Secreto. |
| Webhook signature key | Confirma que um webhook realmente veio do Square. Secreta. |
| Location ID | A localização Square que recebe o pagamento. Define a moeda. |
| URL de sucesso / URL de cancelamento | Onde o comprador chega depois de pagar ou desistir. |
Por que pedimos cada campo
Access token
Autoriza a criação do link de checkout, para que a cobrança corra pela sua conta.
Webhook signature key
Comprova que um webhook recebido é genuinamente do Square, para que ninguém possa forjar um evento de "pago". É um valor separado do access token.
Location ID
Diz ao Square qual localização recebe o dinheiro, e define a moeda do checkout. Não é secreto.
URL de sucesso e cancelamento
Configurações simples: onde o comprador chega depois de pagar ou desistir. Não são secretas.
Configurar
- Abra o painel de desenvolvedor do Square
Entre em developer.squareup.com. Cada aplicação tem as suas próprias credenciais, e um Sandbox gratuito é criado junto com ela para testes. Este guia percorre o Sandbox; o fluxo de produção é idêntico, basta alternar o botão Sandbox / Production e usar as suas credenciais de produção. Para criar um novo app, clique no bloco + na tela Applications.
Square Developer → Applications - Dê um nome à sua aplicação
Dê à aplicação um nome que você reconheça (por exemplo "Coin Moebius") e clique em Next.
Square → Name your application - Copie o seu access token
Abra o app e vá até Credentials. Confirme que o botão Sandbox / Production no topo corresponde ao ambiente que você está configurando. Clique no ícone de copiar ao lado do Access token e guarde-o.
Square → Credentials O access token é secreto, trate-o como uma senha. Sandbox e Production têm tokens separados, portanto não os misture.
- Copie o seu Location ID
No menu à esquerda, abra Locations. Copie o Location ID da localização que deve receber os pagamentos. Ele define a moeda do checkout, portanto escolha aquele cuja moeda você deseja cobrar.
Square → Locations - Abra Webhooks → Subscriptions
O Square chama um endpoint de webhook de "subscription". No menu à esquerda, expanda Webhooks, abra Subscriptions e clique em Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Adicione a subscription e selecione os eventos
Dê um nome (como "coin-moebius"). Em Notification URL, cole o endereço de webhook do seu projeto Square (abaixo). Em seguida, em Events, pesquise e marque os eventos que o Coin Moebius escuta e clique em Save.
- Pagamentos únicos: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Assinaturas (somente se você as vender): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Se você não cobra de forma recorrente, pule estes.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription O ID do seu projeto está abaixo do nome do projeto no painel do Coin Moebius; insira-o no endereço acima. Eventos extras são inofensivos, ignoramos tudo o que não usamos. O cartão do provedor conectado (último passo) mostra a mesma URL para referência.
- Abra a subscription que você acabou de criar
O Square salva a subscription e a lista em Webhooks com o status Enabled. Clique no seu nome para abrir o painel de detalhes onde fica a chave de assinatura.
Square → Webhooks → sua subscription (Enabled) - Copie a Signature key
No painel Properties da subscription, clique no ícone de copiar ao lado de Signature key. Este é o valor que o Coin Moebius usa para confirmar que cada webhook realmente veio do Square. Ele só existe após a subscription ser criada, por isso o webhook vem antes da etapa de conexão.
Square → sua subscription → Signature key - De volta no Coin Moebius: Adicionar provedor → Square
No seu projeto, abra a aba Provedores, clique em Adicionar provedor, escolha Conectar um serviço e selecione Square. Defina a sua URL de sucesso e a URL de cancelamento. Na aba Live, cole o seu Access token, Webhook signature key e Location ID e clique em Salvar. Está configurando com credenciais de sandbox primeiro? Cole-as na aba Test e adicione as credenciais de produção mais tarde em Editar.
Coin Moebius → Adicionar provedor → Square - Você está conectado
O Square agora aparece na sua aba Provedores com a data em que foi conectado. O cartão mostra a mesma URL de webhook que você colou no Square, além de Editar e Desconectar. Use o botão de alternância Modo de teste para executar um pedido de sandbox de ponta a ponta antes de ir ao ar.
Coin Moebius → Provedores → Square (conectado) Cartões de sandbox nunca cobram um cartão real. Use o cartão 4111 1111 1111 1111, CVV 111, qualquer validade futura, qualquer código postal válido (por exemplo 94103).
Depois de conectar
Faça um pagamento de teste antes de ir ao ar:
- Crie um produto e defina o Ambiente dele como Teste. Isso roda o produto nas suas credenciais de sandbox, para que você possa fazer um pedido completo sem mover dinheiro. (Se você pulou o conjunto de sandbox, um produto de Teste recai para a produção, então adicione-o primeiro.)
- Coloque o botão de compra em uma página (um arquivo HTML local serve) apontado para o seu projeto.
- Conclua o checkout com o cartão de teste do sandbox de cima.
- Abra a aba Transações. Uma nova linha aparece, marcada como Teste. Quando o status dela chegar a succeeded, as suas credenciais e o webhook estão ambos funcionando de ponta a ponta.
Mude o Ambiente do produto para Produção quando você estiver pronto para pagamentos reais.
Solução de problemas
Comece com Verificar. No painel, clique em Verificar (ou Verificar credenciais de teste) para checar o seu access token e localização.
A verificação falha.
Copie de novo o access token e o Location ID. Production e Sandbox têm tokens separados, então não os misture.
A verificação de assinatura falha, ou o pedido fica pendente.
O Square assina sobre a notification URL exata mais o corpo. A URL que você registra no Square deve coincidir com a sua URL de webhook caractere por caractere, sem barra final e sem query string extra. Depois copie de novo a signature key daquele mesmo endpoint.
Confirme de ponta a ponta.
Square Developer Console → Webhooks → sua subscription → Send Test Event, depois observe o pedido atualizar.
Bom saber
A moeda segue a localização. O checkout cobra na moeda da localização cujo id você fornece.
Rotacionando segredos. Rotacione o access token ou a signature key quando quiser, depois cole o novo valor. Os campos secretos ficam em branco na edição.
Dúvidas? Join our Discord