API Reference: Pagamentos (Asaas)

Base URL: /api/pagamentos e /api/webhooks. Integrado com Asaas para cobrancas PIX, boleto e cartao de credito com checkout transparente.

POST /api/pagamentos/customer

Cria ou busca o customer no Asaas para o usuario logado. Chamado automaticamente na primeira cobranca.

Permissao: Autenticado

Response

"cus_xxxxxxxxxxxxx"

POST /api/pagamentos/cobranca

Gera uma cobranca no Asaas. Usado internamente pela loja e planos.

Permissao: Autenticado

Body

{
  "valorReal": 20.00,
  "valorCCUsado": 3000,
  "metodo": "PIX",
  "origem": "loja",
  "referenciaId": "uuid-do-pedido",
  "descricao": "Compra na loja MBL-ES"
}

Metodos aceitos

PIX, CARTAO_CREDITO, CARTAO_DEBITO, BOLETO

Response

{
  "pagamentoId": "uuid",
  "asaasPaymentId": "pay_xxxxx",
  "urlPagamento": "https://sandbox.asaas.com/...",
  "pixQrCode": "00020126...",
  "status": "PENDENTE"
}

GET /api/pagamentos/:id

Retorna status de um pagamento.

GET /api/pagamentos/meus

Historico de pagamentos reais do usuario. Paginado.

POST /api/webhooks/asaas

Recebe webhooks do Asaas. Validado com asaas-access-token header.

Eventos processados

Evento Asaas	Acao no sistema
PAYMENT_CONFIRMED / PAYMENT_RECEIVED	Marca pagamento como CONFIRMADO, debita CC parciais, avanca pedido/assinatura
PAYMENT_OVERDUE	Marca como ATRASADO
PAYMENT_REFUNDED	Marca como ESTORNADO
PAYMENT_DELETED	Marca como CANCELADO

O webhook deve ser configurado no dashboard Asaas apontando para https://api.mbl-es.org/api/webhooks/asaas.

Checkout Transparente (Cartao de Credito)

Para pagamentos com cartao de credito, os dados sao enviados inline no body da cobranca — sem redirect para pagina externa do Asaas.

Campos adicionais no body

Campo	Tipo	Descricao
`creditCard.holderName`	string	Nome do titular do cartao
`creditCard.number`	string	Numero do cartao
`creditCard.expiryMonth`	string	Mes de validade
`creditCard.expiryYear`	string	Ano de validade
`creditCard.ccv`	string	Codigo de seguranca

creditCardHolderInfo (from JSONB)

Os dados do titular sao populados automaticamente a partir do campo JSONB endereco do usuario:

Campo	Tipo	Origem
`name`	string	Nome completo do usuario
`email`	string	Email do usuario
`cpfCnpj`	string	CPF do usuario
`postalCode`	string	CEP do campo JSONB `endereco`
`addressNumber`	string	Numero do endereco do campo JSONB `endereco`
`phone`	string	Telefone do usuario (fallback: `00000000000` se menor que 10 digitos)

Mapeamento de Metodo

CARTAO_CREDITO (enum interno) e mapeado para CREDIT_CARD (billing type Asaas). A conversao e feita automaticamente no backend antes de enviar para a API Asaas.

Auto-recreate Customer

Se o customer Asaas do usuario for invalido (removido ou inconsistente), o sistema recria automaticamente antes de prosseguir com a cobranca.

Asaas Nacional

Pagamentos de nivel Nacional (produtos da loja nacional, planos nacionais) utilizam a conta Asaas da organizacao nacional:

As credenciais Asaas nacionais sao separadas das credenciais dos nucleos
O webhook processa pagamentos nacionais e locais de forma unificada, diferenciando pela origem
Pedidos nacionais sao gerenciados pelo super admin