Primeiros passos

Do cadastro ao primeiro Pix em sandbox, com webhook outbound recebido localmente.

Este guia te leva do zero até receber um webhook real de pagamento aprovado em sandbox. Tempo estimado: 15-20 minutos.

Você pode parar no passo 6 (criar Pix) e validar a integração básica em 5 minutos. Se quiser também receber webhooks (passo 7), o tempo total vai pra ~20 minutos porque envolve subir um túnel HTTPS.

O que você vai precisar

Acesso ao seu provedor de e-mail (para receber o magic link).
Conta de teste em pelo menos um gateway: Abacate Pay, Asaas ou Pagar.me.
Um terminal com curl (ou Postman/Insomnia).
Para o passo 7 (webhooks): ngrok ou Cloudflare Tunnel instalado. Não é "opcional": webhooks da Allya só aceitam URL HTTPS pública, então sem túnel você não recebe nada na sua máquina.

O que é magic link? Login sem senha: você informa o e-mail, recebe um link único e clica para entrar. Sem cadastro de senha, sem 2FA configurado pelo usuário. A Allya não tem outro mecanismo.

1. Entrar com magic link

A Allya não tem cadastro com senha. Acesse /auth/login, informe seu e-mail e clique em Enviar link. O acesso chega por e-mail em poucos segundos.

No primeiro login, a Allya cria automaticamente uma organização vinculada ao seu e-mail.

2. Criar um projeto

No painel, clique em + Novo projeto no dashboard ou em Projetos.

Nome: livre (ex.: "Meu SaaS").
Slug: minúsculas, números e hífen (ex.: meu-saas).

Cada projeto recebe automaticamente dois ambientes: sandbox e produção. Credenciais, API keys, webhooks e pagamentos ficam isolados por ambiente.

Após criar, você cai no Overview do projeto, já no ambiente sandbox.

3. Conectar um gateway sandbox

Garanta que o switcher no topo está em Sandbox (vai sempre estar, no primeiro acesso).

No menu lateral, clique em Gateways → Adicionar gateway. Escolha um provedor:

Abacate Pay

Em app.abacatepay.com, vá em Configurações → API.
Copie a API Key (formato abc_dev_... em sandbox).
Defina um Webhook Secret de sua escolha. Será exigido na URL inbound: pode ser qualquer string longa e aleatória. A assinatura X-Webhook-Signature enviada pela Abacate Pay é validada automaticamente pela Allya.
Cole os dois valores no painel da Allya e clique em Conectar gateway.

Asaas

Em sandbox.asaas.com, vá em Integrações → Chaves de API.
Crie uma nova chave e copie o valor (começa com $aact_).
Em Integrações → Webhooks, defina ou copie o Webhook Token (será enviado no header asaas-access-token quando o Asaas chamar a Allya). Use um token forte com 32 a 255 caracteres e sem espaços.
Cole Access Token e Webhook Secret no painel da Allya e conecte.

Pagar.me

Em dashboard.pagar.me, vá em Desenvolvedores → Chaves.
Copie a Secret Key de sandbox (formato sk_test_...).
Em Desenvolvedores → Webhooks, configure ou copie o Webhook Secret usado para assinar os payloads.
Cole Secret Key e Webhook Secret no painel da Allya e conecte.

Para detalhes do que cada gateway suporta e exige, consulte Gateways.

Após conectar, o gateway aparece como ativo na listagem.

4. Definir roteamento de Pix

No menu lateral, clique em Roteamento. A página tem duas seções independentes:

Pagamentos avulsos: define qual gateway atende Pix e cartão em POST /v1/payments.
Assinaturas recorrentes: define qual gateway atende cartão em POST /v1/subscriptions. Só aparece se algum gateway ativo suportar recorrência.

Em Pagamentos avulsos → Pix, selecione o gateway que você acabou de conectar. Clique em Salvar roteamento.

Sem roteamento, a Allya não sabe para qual gateway enviar a cobrança e retorna 409 no_routing_rule. Para criar assinaturas depois, repita o passo na seção de assinaturas recorrentes: o roteamento é independente.

5. Gerar API key sandbox

No menu lateral, API Keys → + Nova API Key.

Nome: ex. "backend dev local".
Clique em Gerar chave.

A chave completa aparece uma única vez (formato sk_test_...). Copie e guarde em .env local:

ALLYA_API_KEY=sk_test_...

Depois desta tela, o painel mostra apenas a versão mascarada. Se perder, revogue e gere outra.

6. Criar um Pix de teste

Com a API key em mãos, dispare uma cobrança:

curl -X POST https://payments-api.allyasolutions.com/v1/payments \
  -H "Authorization: Bearer $ALLYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1990,
    "currency": "BRL",
    "method": "pix",
    "externalId": "pedido_quickstart_1",
    "customer": {
      "name": "Cliente Teste",
      "email": "cliente@example.com",
      "document": "00000000000"
    }
  }'

Pontos importantes do payload acima:

amount é sempre em centavos. 1990 representa R$ 19,90: nunca R$ 1.990.
currency aceita apenas BRL na versão atual.
externalId é o seu identificador (id de pedido, sessão de checkout, etc.). Reenviar a mesma requisição com o mesmo externalId retorna o pagamento já criado, sem cobrar de novo. Veja Idempotência.
customer.document aceita CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem máscara: a Allya normaliza. O exemplo usa um CPF de teste (00000000000).

A resposta inclui id, status, pix.qrCodeText (copia e cola) e pix.qrCode (imagem ou URL, quando o gateway envia). No painel, Pagamentos mostra a cobrança recém-criada com status inicial pending ou processing: veja Status de pagamento para o ciclo completo.

Se você está usando Asaas, o QR Pix é obtido em uma segunda chamada na API do gateway. Se essa chamada falhar (timeout/5xx), a resposta sai sem pix.qrCodeText/pix.qrCode: o pagamento já existe e é cobrável; chame POST /v1/payments/:id/sync para tentar de novo.

Veja o ciclo completo do retorno em Criar pagamento.

7. Receber webhook outbound

Quando o gateway notifica a Allya que o Pix foi pago, a Allya envia um webhook padronizado para o endpoint que você cadastrar.

Cadastrar endpoint

No painel, Webhooks → Novo endpoint. Informe uma URL HTTPS pública. Em desenvolvimento local, exponha sua aplicação atrás de um túnel: veja o guia completo de Testar webhooks localmente.

A URL precisa ser HTTPS pública: URLs locais, privadas ou em domínios internos são bloqueadas antes de salvar.

Ao criar, a Allya mostra o secret uma única vez. Salve em .env:

ALLYA_WEBHOOK_SECRET=wh_sec_...

Simular o pagamento

Em sandbox, cada gateway tem um caminho próprio para marcar o Pix como pago:

Abacate Pay: aba Simular no painel sandbox.
Asaas: aba Cobranças → ação Marcar como recebido.
Pagar.me: usa Pix de teste com txid específico documentado pela Pagar.me.

Em poucos segundos, a Allya recebe o webhook do gateway, atualiza o pagamento e dispara o evento normalizado para o seu endpoint. No painel, Webhooks → Histórico de entregas mostra o resultado (HTTP code, tentativa, timestamp).

O payload e a assinatura HMAC-SHA256 são descritos em Webhooks.

Próximos passos

Conferir status por API: Consultar pagamento.
Adicionar cartão de crédito: Criar pagamento.
Cobrar recorrência com cartão: Criar assinatura (lembre de configurar também o roteamento de assinatura em Roteamento → Assinaturas recorrentes, separado do roteamento de pagamentos avulsos).
Ler os erros estruturados: Erros.
Entender o ciclo de status: Status de pagamento e Status de assinatura.
Subir para produção: siga o checklist de produção.

Veja também

Testar webhooks localmente: guia completo de ngrok e Cloudflare Tunnel.
Autenticação: GET /v1/auth/test como ping de debug.
Troubleshooting: cenários comuns durante a integração.

On this page