Indo para produção

Você terminou o quickstart, validou o fluxo em sandbox e quer ligar cobranças reais. Esta página é um checklist para a aplicação que consome a API da Allya. Ela não cobre deploy ou infraestrutura interna da Allya Payments.

Antes de trocar a chave

• Fluxo completo validado em sandbox: criar pagamento, concluir no gateway, receber webhook outbound e marcar o pedido como pago no seu sistema.
• Assinatura validada, se aplicável: criar, receber subscription.created, simular renovação e cancelar.
• Sua aplicação trata 401, 409, 429 e 502. Veja Erros.
• Retry com backoff implementado para 5xx e timeout em POST /v1/payments e POST /v1/subscriptions.
• Idempotência preservada: retentativas usam o mesmo externalId. Veja Idempotência.
• Seu handler de webhook valida X-Allya-Signature usando body cru e rejeita timestamp velho. Veja Webhooks.

Gateways live

Para cada gateway que vai operar em produção:

• Credenciais live geradas no painel do gateway.
• Gateway configurado no ambiente Production da Allya, sem reaproveitar credenciais de sandbox.
• Webhook Secret novo e forte cadastrado no gateway, quando o provedor exigir.
• URL inbound exibida pela Allya cadastrada no painel do gateway de produção. Para Abacate Pay, acrescente ?secret=<seu Webhook Secret>; para Asaas e Pagar.me, use a URL sem query string.
• Roteamento configurado em Production para pagamentos avulsos e assinaturas recorrentes.
• Para Pagar.me com assinatura: Plan criado no ambiente live do Pagar.me. Plans de sandbox não funcionam em produção. Veja Plano obrigatório no Pagar.me.

API key live

• Gere uma API key sk_live_... no projeto e ambiente Production.
• Armazene a chave no cofre de segredos da sua aplicação.
• Atualize sua aplicação para chamar https://payments-api.allyasolutions.com.
• Valide a chave com GET /v1/auth/test antes de liberar tráfego real.
• Confirme que environment.kind retorna production.
• Revogue ou remova do runtime qualquer chave sk_test_... usada nos testes.

Exemplo de validação:

curl https://payments-api.allyasolutions.com/v1/auth/test \
  -H "Authorization: Bearer sk_live_..."

Endpoint outbound

• Publique um endpoint HTTPS estável da sua aplicação, por exemplo https://api.suaempresa.com/webhooks/allya.
• Cadastre esse endpoint em Webhooks no ambiente Production da Allya.
• Armazene o secret gerado pela Allya no cofre de segredos da sua aplicação.
• Faça um teste controlado de assinatura inválida para garantir que seu endpoint retorna 401.
• Defina política de rotação: webhook secret a cada 90-180 dias ou quando houver suspeita de vazamento; API keys quando alguém deixa o time.

Não use URL de túnel em produção. ngrok e quick tunnels são úteis em sandbox, mas são descartáveis e podem mudar sem aviso.

Monitoramento

• Uptime check em GET https://payments-api.allyasolutions.com/v1/health.
• Alerta para taxa de erro alta em POST /v1/payments e POST /v1/subscriptions.
• Alerta para latência alta na criação de pagamento, considerando o tempo do gateway.
• Alerta para WEBHOOK_FAILED no painel da Allya ou rotina operacional diária para revisar Webhooks → Histórico de entregas.
• Revisão periódica de Logs para GATEWAY_ERROR e falhas de entrega.

Não faça

• Não use sk_test_... em produção.
• Não reutilize credenciais ou webhook secrets de sandbox.
• Não grave API key, webhook secret ou credenciais de gateway em logs.
• Não trate processing como sucesso: espere paid ou chame POST /v1/payments/:id/sync.
• Não use cancel-payment como refund. Cancelar só serve para cobranças ainda não pagas.

Pós-virada

Logo após liberar:

1. Faça uma cobrança real de valor mínimo em cada combinação método x gateway que você vai usar.
2. Confirme no painel do gateway que a cobrança foi criada no ambiente live.
3. Confirme no painel da Allya que o pagamento aparece em Production.
4. Confirme que seu endpoint recebeu o webhook outbound e respondeu 2xx.
5. Audite os logs após o primeiro dia para garantir que não há GATEWAY_ERROR ou WEBHOOK_FAILED recorrente.

Veja também

• Quickstart: fluxo equivalente em sandbox.
• Autenticação: uso de API keys.
• Logs: onde investigar quando algo der errado em produção.
• Troubleshooting: cenários comuns e como destravar.
• Webhooks: validação obrigatória do X-Allya-Signature.