Central Unificada de Pagamentos

API intermediadora oficial conectada ao banco Asaas. Permite que qualquer projeto ou aplicação da empresa realize cobranças via PIX Dinâmico com QR Code, Cartão de Crédito e Assinaturas em segundos, sem necessidade de reconfigurar chaves ou webhooks.

🚀 Base URL Oficial

https://pagamentos.clickai.app.br/api/v1

Como Funciona a Integração?

1. Seu Projeto chama um dos endpoints desta API enviando a sua X-API-Key.
2. A Central gera o pagamento diretamente no Asaas e já retorna imediatamente o QR Code / Código Pix ou a confirmação do Cartão.
3. Quando o cliente final paga, o Asaas avisa a Central, que automaticamente repassa um Webhook de Confirmação para o seu projeto liberar o acesso ou quitar a fatura.

Autenticação

Todas as requisições para a API devem incluir a chave de autenticação do seu projeto (gerada no Painel Administrativo). Você pode passá-la de duas formas:

Cabeçalhos HTTP Válidos

X-API-Key: pay_sec_seu_projeto_abc123...
# OU
Authorization: Bearer pay_sec_seu_projeto_abc123...

1. Criar Cobrança PIX

Gera uma cobrança com chave Pix Copia e Cola e imagem Base64 do QR Code instantaneamente.

POST /payments/pix

Parâmetro	Tipo	Obrigatório	Descrição
value	number	Sim	Valor da cobrança em Reais (Ex: `150.00`)
customer	object	Sim	Objeto contendo `cpfCnpj` (obrigatório), `name`, `email` e `phone`
dueDate	string (YYYY-MM-DD)	Não	Data de vencimento. Padrão: dia atual
externalReference	string	Não	ID ou referência interna do seu sistema (Ex: ID da fatura #1085)
description	string	Não	Descrição que aparecerá no comprovante Pix do pagador

curl -X POST https://pagamentos.clickai.app.br/api/v1/payments/pix \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pay_sec_sua_chave_aqui" \
  -d '{
    "value": 150.00,
    "externalReference": "fatura_789",
    "description": "Mensalidade Outubro/2026",
    "customer": {
      "name": "João Silva",
      "cpfCnpj": "12345678909",
      "email": "joao@email.com",
      "phone": "61999998888"
    }
  }'

const axios = require('axios');

async function gerarPix() {
  const response = await axios.post('https://pagamentos.clickai.app.br/api/v1/payments/pix', {
    value: 150.00,
    externalReference: 'fatura_789',
    description: 'Mensalidade Outubro/2026',
    customer: {
      name: 'João Silva',
      cpfCnpj: '12345678909',
      email: 'joao@email.com',
      phone: '61999998888'
    }
  }, {
    headers: {
      'X-API-Key': 'pay_sec_sua_chave_aqui',
      'Content-Type': 'application/json'
    }
  });

  console.log('ID do Pagamento:', response.data.paymentId);
  console.log('Código Copia e Cola:', response.data.pix.payload);
  console.log('QR Code Base64:', response.data.pix.encodedImage);
}
gerarPix();

import requests

url = "https://pagamentos.clickai.app.br/api/v1/payments/pix"
headers = {
    "X-API-Key": "pay_sec_sua_chave_aqui",
    "Content-Type": "application/json"
}
payload = {
    "value": 150.00,
    "externalReference": "fatura_789",
    "description": "Mensalidade Outubro/2026",
    "customer": {
        "name": "João Silva",
        "cpfCnpj": "12345678909",
        "email": "joao@email.com",
        "phone": "61999998888"
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print("Pix Copia e Cola:", data['pix']['payload'])

<?php
$ch = curl_init('https://pagamentos.clickai.app.br/api/v1/payments/pix');
$payload = json_encode([
    'value' => 150.00,
    'externalReference' => 'fatura_789',
    'customer' => [
        'name' => 'João Silva',
        'cpfCnpj' => '12345678909',
        'email' => 'joao@email.com'
    ]
]);

curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: pay_sec_sua_chave_aqui'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Copia e Cola: " . $response['pix']['payload'];

Exemplo de Resposta (JSON):

{
  "success": true,
  "paymentId": "pay_819283918239",
  "status": "PENDING",
  "value": 150.00,
  "dueDate": "2026-10-22",
  "pix": {
    "encodedImage": "iVBORw0KGgoAAAANSUhEUgAA...",
    "payload": "00020101021226830014br.gov.bcb.pix2561...",
    "expirationDate": "2026-10-22 23:59:59"
  },
  "invoiceUrl": "https://www.asaas.com/i/819283918239"
}

2. Cobrança com Cartão de Crédito

Processa pagamentos à vista ou parcelados em até 12x. Você pode enviar os dados completos do cartão ou utilizar um creditCardToken previamente gerado.

POST /payments/credit-card

Exemplo com Dados do Cartão

curl -X POST https://pagamentos.clickai.app.br/api/v1/payments/credit-card \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pay_sec_sua_chave_aqui" \
  -d '{
    "value": 300.00,
    "installmentCount": 2,
    "externalReference": "pedido_105",
    "customer": {
      "name": "Maria Oliveira",
      "cpfCnpj": "98765432100",
      "email": "maria@email.com",
      "phone": "61988887777"
    },
    "creditCard": {
      "holderName": "MARIA OLIVEIRA",
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2028",
      "ccv": "123"
    },
    "creditCardHolderInfo": {
      "name": "Maria Oliveira",
      "email": "maria@email.com",
      "cpfCnpj": "98765432100",
      "postalCode": "70000000",
      "addressNumber": "100",
      "phone": "61988887777"
    }
  }'

Exemplo de Resposta:

{
  "success": true,
  "paymentId": "pay_98129381923",
  "status": "CONFIRMED",
  "value": 300.00,
  "creditCardBrand": "VISA",
  "creditCardLastDigits": "1111",
  "message": "Pagamento aprovado com sucesso!"
}

3. Consultar Status da Cobrança

Permite consultar o status atual de uma cobrança usando o Asaas ID (ex: pay_123), o ID local ou o seu externalReference. Caso a cobrança esteja pendente, o endpoint sincroniza em tempo real com o Asaas.

GET /payments/:id

Exemplo de Consulta

curl -X GET https://pagamentos.clickai.app.br/api/v1/payments/pay_819283918239 \
  -H "X-API-Key: pay_sec_sua_chave_aqui"

⚡ Webhooks de Retorno no seu Projeto

Você não precisa lidar diretamente com o Asaas. Quando um cliente efetua o pagamento, a Central de Pagamentos envia automaticamente uma requisição POST para a URL do Webhook configurada no seu projeto com o cabeçalho X-Webhook-Secret para validação.

Exemplo de Payload Enviado para o seu Projeto:

{
  "event": "PAYMENT_CONFIRMED",
  "timestamp": "2026-10-22T00:35:00.000Z",
  "project": {
    "id": 1,
    "slug": "casa-lip",
    "name": "Casa Lip - Gestão Residencial"
  },
  "payment": {
    "id": 105,
    "asaasId": "pay_819283918239",
    "externalReference": "fatura_789",
    "status": "CONFIRMED",
    "billingType": "PIX",
    "value": 150.00,
    "netValue": 147.51,
    "paymentDate": "2026-10-22T00:34:55.000Z",
    "customer": {
      "name": "João Silva",
      "cpfCnpj": "12345678909",
      "email": "joao@email.com"
    }
  }
}

Exemplo de Tratamento no seu Projeto (Express):

// Rota no seu projeto (ex: /api/payments/webhook)
app.post('/api/payments/webhook', async (req, res) => {
  const secret = req.headers['x-webhook-secret'];
  if (secret !== process.env.MY_WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  const { event, payment } = req.body;

  if (event === 'PAYMENT_CONFIRMED' || event === 'PAYMENT_RECEIVED') {
    const invoiceId = payment.externalReference;
    console.log(`Fatura ${invoiceId} Paga! Valor Líquido: R$ ${payment.netValue}`);
    // Quitar fatura, liberar plano, etc...
  }

  res.json({ received: true });
});