Introdução
Entenda o papel da Allya Payments e os conceitos principais da plataforma.
Em 30 segundos
A Allya Payments expõe uma única API REST que orquestra Abacate Pay, Asaas e Pagar.me:
POST /v1/paymentscria uma cobrança (Pix ou cartão) no gateway que você roteou.POST /v1/subscriptionscria uma assinatura recorrente em cartão de crédito via checkout hospedado.- Webhooks dos gateways são recebidos, normalizados e reenviados para o seu endpoint num formato único (
payment.paid,subscription.renewed, ...).
O cliente continua dono dos contratos e credenciais com os gateways: a Allya centraliza só a parte técnica.
Pulando para a prática? Vá direto para Primeiros passos: leva do cadastro ao primeiro Pix com webhook em sandbox em ~15 minutos.
Escolha uma trilha
Se você já sabe o que quer validar, comece por uma destas trilhas:
| Objetivo | Comece por | Depois leia |
|---|---|---|
| Validar o primeiro Pix em sandbox | Primeiros passos | Criar pagamento, Webhooks |
| Adicionar cartão com checkout hospedado | Criar pagamento | Dados do cliente, Cancelar pagamento |
| Cobrar assinatura recorrente | Criar assinatura | Plano obrigatório no Pagar.me, Status de assinatura |
| Preparar produção | Indo para produção | Ambientes, Rate limiting |
O que a Allya é, com mais calma
A Allya Payments é uma camada de orquestração e centralização técnica de gateways de pagamento.
Ela não substitui gateways como Abacate Pay, Asaas ou Pagar.me. O cliente continua usando os provedores que já contratou, com suas próprias credenciais e regras comerciais. A Allya centraliza a integração técnica para reduzir trabalho repetido e padronizar respostas, webhooks e logs.
Convenções desta documentação
Nos exemplos de API você verá:
https://payments-api.allyasolutions.com/v1/...Em desenvolvimento local, substitua a base por http://localhost:3000. Veja Primeiros passos para subir o ambiente local.
Dois domínios, papéis diferentes
A Allya usa dois hosts. Não os troque nas suas chamadas:
| Domínio | Para quê |
|---|---|
payments-api.allyasolutions.com | A API REST (/v1/*). É o que vai no seu backend. |
payments.allyasolutions.com | O painel e esta documentação (uso humano, login por magic link). |
Se você apontar o backend para payments.allyasolutions.com, as chamadas /v1/* não respondem como API.
O que a Allya centraliza
- Configurações de gateways por ambiente.
- Credenciais de gateways criptografadas.
- API keys por projeto e ambiente.
- Criação de pagamentos avulsos (Pix e cartão) por uma API única.
- Criação de assinaturas recorrentes em cartão de crédito (checkout hospedado), com cobranças automáticas e eventos
subscription.*normalizados. - Roteamento independente para pagamento avulso e assinatura (mesmo método pode ir para gateways diferentes).
- Normalização de respostas de pagamento e assinatura.
- Recebimento de webhooks dos gateways.
- Envio de webhooks padronizados para o cliente.
- Logs técnicos com retenção por plano.
- Histórico de transações e ciclos de assinatura.
Fluxo de um pagamento
Da chamada à confirmação por webhook, ponta a ponta:
Modelo principal
Tudo abaixo de Ambiente é isolado por ambiente: uma API key de sandbox nunca enxerga dados de produção.
Organização
Uma organização representa a conta principal do cliente dentro da Allya Payments.
Na versão atual, cada usuário é associado automaticamente a uma organização no primeiro login. A organização concentra projetos, plano, membros, limites e retenção de logs.
Projeto
Um projeto representa uma aplicação, produto ou sistema que vai integrar pagamentos pela Allya.
Exemplos:
- Um e-commerce.
- Um SaaS.
- Um sistema interno de cobrança.
- Um app mobile.
Cada projeto possui seus próprios ambientes, API keys, gateways, webhooks e pagamentos.
Ambientes
Cada projeto possui dois ambientes:
sandbox: usado para testes.production: usado para operação real.
Os dados são separados por ambiente. Uma API key de sandbox cria pagamentos no sandbox. Uma API key de produção cria pagamentos em produção.
Glossário rápido
Termos que aparecem em várias páginas, na ordem em que costumam confundir:
- Organização: a conta principal do cliente da Allya. Hoje, cada usuário tem uma única organização (criada automaticamente no primeiro login).
- Projeto: uma aplicação ou produto dentro da organização. Concentra ambientes, gateways, API keys e pagamentos.
- Ambiente:
sandboxouproduction. Tudo é isolado por ambiente; uma API key vive em um único ambiente. - Gateway: provedor de pagamento (Abacate Pay, Asaas, Pagar.me). Cada gateway tem credenciais próprias por ambiente.
- Roteamento: regra que define qual gateway atende cada método. Separa avulso (
POST /v1/payments) de recorrente (POST /v1/subscriptions). - API key: credencial que você usa no header
Authorization: Bearer. Prefixosk_test_em sandbox,sk_live_em produção. O ambiente da chamada vem do prefixo da chave. externalId: identificador do seu sistema (id de pedido, sessão, assinatura). Funciona como chave de idempotência por ambiente: mesma chamada com mesmoexternalIdretorna o pagamento existente.- Webhook inbound: evento que chega na Allya vindo do gateway (ex.: "este Pix foi pago").
- Webhook outbound: evento que a Allya envia para o seu endpoint, num formato normalizado e assinado.
checkoutUrl: URL hospedada pelo gateway para o cliente final concluir o pagamento de cartão (ou inserir o cartão da assinatura).gatewayRef: id do recurso no gateway. Útil para correlacionar com o painel do provedor durante investigação.
O que ainda não está disponível
A versão atual não inclui:
- Fallback automático entre gateways (cada método tem um único gateway roteado por vez).
- Checkout personalizado pela Allya: cartão sempre usa o checkout hospedado do gateway escolhido.
- SDK oficial (Node, Python etc.): apenas HTTP direto.
- Convites de membros e permissões por papel. Cada usuário tem sua própria organização.
- PIX recorrente (em breve em Abacate Pay e Asaas) e débito recorrente.
- Catálogo de planos, troca de cartão sem cancelar, upgrade/downgrade, proration, pause/resume e cupom em assinaturas. Veja Criar assinatura.