Skip to main content

​
Overview

The Payments & Charges API provides comprehensive functionality for managing financial transactions within residential communities. This includes creating and tracking charges for residents, processing payments, and maintaining detailed payment histories.

​
Authentication

All endpoints require authentication using Bearer tokens. Different role levels provide access to different operations:
  • ADMIN_COMPANY, SYSTEM_ADMIN: Full access to all payment and charge operations
  • Resident users: Limited access to view their own payments and submit payment records
Include the JWT token in the Authorization header: 
Authorization: Bearer {your_jwt_token}

​
Key Features

​
Community Charges & Payments

Manage charges and payments at the community and contract level.
  • Statements: View comprehensive statements showing charges (cargos) and payments (pagos) for contracts or communities
  • Community Charges: Track charges associated with contracts and communities, including late fees
  • Community Payments: Record payments and automatically apply them to outstanding charges
  • Charge Status Tracking: Monitor charge status (No vencido, vencido, pagado, pago parcial)
  • Payment Application: Link payments to multiple charges with applied amounts

​
Resident Charges (Cargos)

Manage charges assigned to individual residents, including maintenance fees, utilities, and other community-related costs.
  • Create and track charges for individual residents
  • Monitor charge status (Activo, Pagado, PagoParcial, Cancelado)
  • View charges by resident or community
  • Update charge details and status

​
Resident Payments (Pagos)

Process and track payments made by residents towards their charges.
  • Submit payment records with proof of payment
  • Support for payment confirmation workflow
  • Flexible payment status tracking (PorConfirmar, Aplicado, Cancelado)
  • Role-based payment creation (admin vs resident)

​
Payment History

Maintain a comprehensive audit trail of all payment transactions linked to contracts.
  • Track payment methods (transferencia, tarjeta, efectivo, cheque)
  • Record payment references and receipts
  • Monitor payment states (pendiente, pagado, cancelado, reembolsado)
  • Associate payments with specific contracts

​
Common Workflows

​
Managing Community Charges and Payments

  1. View statement for contract or community:
    • Use /api/charges/contrato/{contratoId} or /api/charges/comunidad/{comunidadId}
    • Returns all charges (cargos) and payments (pagos)
    • Shows charge status, amounts, late fees, and payment applications
  2. Track charge status:
    • Charges automatically track status based on payment date and amount
    • Status values: “No vencido”, “vencido”, “pagado”, “pago parcial”
    • Late fees (MontoRecargos) can be applied to overdue charges
  3. Apply payments to charges:
    • Payments can be applied to multiple charges
    • System tracks the amount applied to each charge via PagoCargoComunidad
    • Charge status updates automatically based on payment application

​
Creating a Charge for a Resident

  1. Identify the resident ID
  2. Create a charge with amount, description, and due date
  3. Charge is created with “Activo” (Active) status by default
  4. Resident can view their charges and submit payments

​
Processing a Resident Payment

  1. Resident submits payment:
    • Creates payment record with “PorConfirmar” (Pending Confirmation) status
    • Includes payment amount, date, and proof of payment URL
  2. Admin reviews payment:
    • Views pending payments
    • Updates status to “Aplicado” (Applied) once verified
  3. Admin updates charge:
    • Updates corresponding charge status based on payment amount
    • Marks as “Pagado” (Paid) or “PagoParcial” (Partially Paid)

​
Recording Payment History

Administrators can create detailed payment history records that track:
  • Contract-specific payments
  • Payment methods and references
  • Transaction dates and amounts
  • Administrative notes and updates

​
API Endpoints Structure

​
Community Charges & Payments

  • /api/charges/* - Community charge statements and queries

​
Resident Operations

  • /api/CargosResidente/* - Resident charge management
  • /api/PagosResidente/* - Resident payment submissions

​
Contract Payments

  • /api/PaymentHistories/* - Contract payment history tracking

​
Response Formats

All endpoints return JSON responses with consistent structures:
  • Success: Returns the requested resource(s) with HTTP 200 OK
  • Created: Returns the created resource with HTTP 201 Created
  • Not Found: Returns HTTP 404 when resource doesn’t exist
  • Bad Request: Returns HTTP 400 with error details for invalid operations
  • Forbidden: Returns HTTP 403 for unauthorized access attempts

​
Date Formats

All dates are handled consistently across the API:
  • Request dates: DateTime objects or ISO 8601 strings
  • Response dates: ISO 8601 datetime strings
  • Fields: CreatedAt, UpdatedAt, Fecha, FechaPago, FechaDePago

​
Error Handling

The API returns standard HTTP status codes:
  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 204 No Content - Resource deleted successfully
  • 400 Bad Request - Invalid input data
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
Error responses include descriptive messages: 
{
  "error": "INVALID_OPERATION",
  "message": "Contract does not exist"
}

​
Next Steps

  • Review Community Charges for statement and charge tracking endpoints
  • Learn about Payment History for contract payment tracking and resident payment submissions

Build docs developers (and LLMs) love

Get started for freeTalk to us