Gateways

A Allya Payments orquestra três gateways na versão atual: Abacate Pay, Asaas e Pagar.me. Esta página tem três seções:

1. Visão geral: quem cobre o quê em uma tabela.
2. Configurar cada gateway: credenciais, onde achar, webhook secret.
3. Particularidades: diferenças importantes que afetam payload (parcelamento, plano obrigatório do Pagar.me, etc.).

A última seção traz URLs inbound e provedores ainda não disponíveis.

Visão geral

Cartão sempre usa checkout hospedado pelo gateway: avulso ou recorrente. A Allya nunca recebe número, CVV, titular ou validade. A resposta de POST /v1/payments e POST /v1/subscriptions traz checkoutUrl para o cliente concluir o pagamento na página do gateway.

Cartão é sempre crédito (avulso ou recorrente). Os três gateways não expõem cartão de débito nas APIs públicas v3/v5 que a Allya consome: billingType do Asaas oferece apenas BOLETO, CREDIT_CARD, PIX e UNDEFINED; accepted_payment_methods do Pagar.me lista apenas credit_card, boleto, pix; Abacate Pay é credit-only no produto. Débito existe nesses gateways via produtos dedicados (Checkout Asaas, etc.) que não estão integrados aqui.

Suporte a assinatura recorrente: detalhes

Detalhamento das regras de trial em Período de trial. Restrições de cancelamento em Cancelar assinatura.

Configurar cada gateway

Todas as credenciais são criptografadas no banco (AES-256-GCM) e nunca exibidas depois de salvas. Para trocá-las, basta editar o gateway e preencher os campos novamente.

Abacate Pay

Credenciais:

Webhook inbound:

A URL exibida em Webhooks do projeto vem sem query string para evitar cópia acidental de placeholder. Ao cadastrar no painel da Abacate Pay, acrescente ?secret=<seu Webhook Secret> ao final da URL. A Allya valida tanto o secret da URL quanto o header X-Webhook-Signature (HMAC-SHA256 do body usando o mesmo Webhook Secret).

Asaas

Credenciais:

Customer no Asaas: o gateway exige um Customer ID próprio antes de criar cobrança ou assinatura. A Allya cria um cliente no Asaas durante cada POST /v1/payments e POST /v1/subscriptions, usando customer.name, customer.document, customer.email e, quando enviado, customer.phone. A Allya não mantém hoje um mapeamento local de clientes Asaas.

Assinatura no Asaas: a Allya cria a assinatura e busca a primeira cobrança em /subscriptions/{id}/payments para retornar o checkoutUrl da fatura hospedada. Webhooks PAYMENT_* com payment.subscription criam ou atualizam o Payment local do ciclo.

Pagar.me

Credenciais:

Autenticação: o Pagar.me usa Basic Auth com a Secret Key: a Allya lida com isso internamente.

Plano obrigatório para assinaturas. O Pagar.me v5 não aceita assinatura "inline": exige que você crie um Plan previamente via POST /plans na API deles e passe o plan.id em gateway.pagarme.planId. Sem isso, POST /v1/subscriptions retorna 400 invalid_input. Veja Plano obrigatório no Pagar.me.

Assinatura no Pagar.me: a Allya cria primeiro um Payment Link (pl_…). A assinatura real (sub_…) só nasce depois que o cliente conclui o checkout; por isso a Allya só dispara subscription.created para Pagar.me quando recebe o webhook do gateway. Webhooks charge.* com subscription criam/atualizam o Payment do ciclo.

Particularidades

Pix

Os três gateways retornam Pix dinâmico com QR Code. A resposta normalizada de POST /v1/payments traz:

• pix.qrCodeText: código copia e cola (string longa começando com 00020101…).
• pix.qrCode: imagem do QR Code, em data URL ou base64, quando o gateway disponibiliza.

Quando o cliente paga, o gateway envia webhook para a Allya, que atualiza status para paid e dispara um webhook outbound padronizado.

Asaas: o QR Pix é obtido em uma segunda chamada após criar o pagamento. Se essa chamada falhar (timeout/5xx), a resposta sai sem pix.qrCode/pix.qrCodeText: o pagamento já existe e é cobrável; use POST /v1/payments/:id/sync para recuperar o QR depois.

Cartão de crédito: parcelamento

card.installments aceita valores de 1 a 24 no schema geral da Allya. O limite real depende do gateway que atender a chamada:

Para assinatura recorrente, card.installments é ignorado: assinatura não parcela.

Cartão: campos obrigatórios por gateway

A Allya valida esses requisitos antes de chamar o gateway. Se faltar, retorna 400 invalid_input com issues[].path apontando o campo.

URLs inbound (gateway → Allya)

Cada gateway recebe uma URL única por ambiente, exibida em Webhooks dentro do projeto:

https://payments-api.allyasolutions.com/api/webhooks/{inboundWebhookSlug}

Cadastre a URL exibida para cada gateway no painel do provedor correspondente. Para Abacate Pay, acrescente ?secret=<seu Webhook Secret> ao final da URL antes de salvar no painel do gateway. Para testar em máquina local, exponha o serviço com ngrok ou Cloudflare Tunnel e substitua o host pelo da URL pública do túnel.

Roteamento

Conectar um gateway não basta: você precisa também rotear cada método de pagamento. Em Roteamento, defina qual gateway atende:

• Pagamentos avulsos (POST /v1/payments): Pix e cartão.
• Assinaturas recorrentes (POST /v1/subscriptions): cartão.

Sem roteamento configurado, a rota retorna 409 no_routing_rule. Você pode usar o mesmo gateway para os dois métodos ou separar (ex.: Asaas para Pix, Pagar.me para cartão).

Não disponíveis agora

Estes provedores aparecem no roadmap mas ainda não estão implementados:

• Mercado Pago: Pix e cartão.
• Stripe: cartão.
• PagSeguro / PagBank: Pix e cartão.
• Stone: Pix e cartão.
• Cielo: cartão.
• OpenPix: Pix.

Tentar configurar um gateway fora da lista resulta em erro no painel: o adapter precisa existir no registry para a opção aparecer.

Veja também

• Criar pagamento: uso da API após configurar o gateway.
• Criar assinatura: fluxo recorrente.
• Plano obrigatório no Pagar.me: pré-requisito específico do gateway.
• Testar webhooks localmente: túnel HTTPS para sandbox.