Pagamentos

Registro e gestão de pagamentos de faturas.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/billing/api/v1/payments	Registrar pagamento	BILLING_PAYMENTS_RECORD
GET	/billing/api/v1/payments	Listar pagamentos	BILLING_PAYMENTS_READ
GET	/billing/api/v1/payments/:id	Obter pagamento	BILLING_PAYMENTS_READ
POST	/billing/api/v1/payments/:id/refund	Processar reembolso	BILLING_PAYMENTS_REFUND

Atributos

Campo	Tipo	Descrição
billingAccountId	string (UUID)	ID da conta de faturamento
invoiceId	string (UUID)	ID da fatura (opcional)
amount	number	Valor do pagamento
status	enum	Status do pagamento
paymentMethod	string	Método de pagamento
externalRef	string	Referência externa (gateway)
refundedAmount	number	Valor já reembolsado
metadata	object	Dados adicionais
createdAt	datetime	Data de criação
updatedAt	datetime	Data da última atualização

Status do Pagamento

Status	Descrição
COMPLETED	Pagamento confirmado
REFUNDED	Totalmente reembolsado
PARTIALLY_REFUNDED	Parcialmente reembolsado

---

Registrar Pagamento

POST /billing/api/v1/payments

Registra um novo pagamento. Se associado a uma fatura, atualiza o status da fatura automaticamente.

Atributos

Campo	Tipo	Obrigatório	Descrição
billingAccountId	string	Sim	ID da conta de faturamento
invoiceId	string	Não	ID da fatura a pagar
amount	number	Sim	Valor do pagamento
paymentMethod	string	Não	Método usado (ex: "PIX", "BOLETO")
externalRef	string	Não	ID no gateway de pagamento
metadata	object	Não	Dados adicionais

cURL

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/payments' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "payments",
      "attributes": {
        "billingAccountId": "550e8400-e29b-41d4-a716-446655440050",
        "invoiceId": "550e8400-e29b-41d4-a716-446655440060",
        "amount": 199.90,
        "paymentMethod": "PIX",
        "externalRef": "gateway-txn-123456",
        "metadata": {
          "gatewayResponse": "approved"
        }
      }
    }
  }'

JavaScript

const response = await fetch('https://billing.stg.catalisa.app/billing/api/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'payments',
      attributes: {
        billingAccountId: '550e8400-e29b-41d4-a716-446655440050',
        invoiceId: '550e8400-e29b-41d4-a716-446655440060',
        amount: 199.90,
        paymentMethod: 'PIX',
        externalRef: 'gateway-txn-123456',
        metadata: {
          gatewayResponse: 'approved',
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Pagamento registrado: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

Response (201 Created)

{
  "data": {
    "type": "payments",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "links": {
      "self": "/billing/api/v1/payments/550e8400-e29b-41d4-a716-446655440070"
    },
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440050",
      "invoiceId": "550e8400-e29b-41d4-a716-446655440060",
      "amount": 199.90,
      "status": "COMPLETED",
      "paymentMethod": "PIX",
      "externalRef": "gateway-txn-123456",
      "refundedAmount": 0,
      "metadata": {
        "gatewayResponse": "approved"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

---

Listar Pagamentos

GET /billing/api/v1/payments

Lista pagamentos com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
page[number]	integer	Número da página
page[size]	integer	Itens por página
filter[billingAccountId]	UUID	Filtrar por conta
filter[invoiceId]	UUID	Filtrar por fatura
filter[status]	enum	Filtrar por status

cURL

curl 'https://billing.stg.catalisa.app/billing/api/v1/payments?filter[billingAccountId]=550e8400-e29b-41d4-a716-446655440050&filter[status]=COMPLETED' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const params = new URLSearchParams({
  'filter[billingAccountId]': '550e8400-e29b-41d4-a716-446655440050',
  'filter[status]': 'COMPLETED',
});

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/payments?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de pagamentos: ${meta.totalItems}`);

// Calcular total pago
const totalPaid = data.reduce((sum, p) => sum + p.attributes.amount, 0);
console.log(`Total pago: R$ ${totalPaid.toFixed(2)}`);

---

Obter Pagamento

GET /billing/api/v1/payments/:id

Obtém os detalhes de um pagamento específico.

cURL

curl 'https://billing.stg.catalisa.app/billing/api/v1/payments/550e8400-e29b-41d4-a716-446655440070' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const paymentId = '550e8400-e29b-41d4-a716-446655440070';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/payments/${paymentId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Valor: R$ ${data.attributes.amount.toFixed(2)}`);
console.log(`Método: ${data.attributes.paymentMethod}`);
console.log(`Status: ${data.attributes.status}`);

---

Processar Reembolso

POST /billing/api/v1/payments/:id/refund

Processa um reembolso total ou parcial do pagamento.

Atributos

Campo	Tipo	Obrigatório	Descrição
amount	number	Não	Valor a reembolsar (default: total)

cURL

# Reembolso total
curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/payments/550e8400-e29b-41d4-a716-446655440070/refund' \
  -H 'Authorization: Bearer SEU_TOKEN'

# Reembolso parcial
curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/payments/550e8400-e29b-41d4-a716-446655440070/refund' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "amount": 50.00
      }
    }
  }'

JavaScript

const paymentId = '550e8400-e29b-41d4-a716-446655440070';

// Reembolso total
const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/payments/${paymentId}/refund`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// Reembolso parcial
const partialRefund = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/payments/${paymentId}/refund`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      attributes: {
        amount: 50.00,
      },
    },
  }),
});

const { data } = await partialRefund.json();
console.log(`Status: ${data.attributes.status}`);
console.log(`Reembolsado: R$ ${data.attributes.refundedAmount.toFixed(2)}`);

Response (200 OK)

{
  "data": {
    "type": "payments",
    "id": "550e8400-e29b-41d4-a716-446655440070",
    "attributes": {
      "billingAccountId": "550e8400-e29b-41d4-a716-446655440050",
      "invoiceId": "550e8400-e29b-41d4-a716-446655440060",
      "amount": 199.90,
      "status": "PARTIALLY_REFUNDED",
      "paymentMethod": "PIX",
      "refundedAmount": 50.00,
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

---

Fluxo de Pagamento

1. Fatura criada → Status: DRAFT
2. Fatura finalizada → Status: FINALIZED
3. Pagamento registrado → Fatura: PAID, Pagamento: COMPLETED
4. Reembolso (se aplicável) → Pagamento: REFUNDED ou PARTIALLY_REFUNDED

---

Integração com Gateway

// Exemplo de integração com gateway de pagamento
async function processPayment(invoice, paymentData) {
  // 1. Processar no gateway
  const gatewayResponse = await paymentGateway.charge({
    amount: invoice.totalAmount,
    method: paymentData.method,
    customer: paymentData.customer,
  });

  if (gatewayResponse.status === 'approved') {
    // 2. Registrar pagamento na Catalisa
    await fetch('https://billing.stg.catalisa.app/billing/api/v1/payments', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        data: {
          type: 'payments',
          attributes: {
            billingAccountId: invoice.billingAccountId,
            invoiceId: invoice.id,
            amount: gatewayResponse.amount,
            paymentMethod: paymentData.method,
            externalRef: gatewayResponse.transactionId,
            metadata: {
              gatewayResponse: gatewayResponse,
            },
          },
        },
      }),
    });
  }
}

---

Erros Comuns

Código	Erro	Descrição
400	VALIDATION	Dados inválidos ou valor negativo
404	NOT_FOUND	Pagamento, conta ou fatura não encontrada
409	CONFLICT	Pagamento já reembolsado totalmente
409	CONFLICT	Valor de reembolso excede o disponível