Payment History & Resident Payments

Overview

This API provides two distinct payment tracking systems:

Payment History - Contract-level payment tracking for administrative record-keeping
Resident Payments (Pagos) - Resident-submitted payments with confirmation workflow

Payment History endpoints require ADMIN_COMPANY or SYSTEM_ADMIN role. Resident Payment endpoints have role-based access.

Payment History

Payment History provides comprehensive tracking of payment transactions associated with contracts. This API maintains a detailed audit trail of all payments, including payment methods, references, and status changes.

Payment History Object

string (guid)

Unique identifier for the payment history record

contratoId

string (guid)

ID of the contract associated with this payment

monto

number (decimal)

Payment amount

fechaPago

string (datetime)

Date when the payment was made (ISO 8601 format)

metodoPago

string

Payment method used. Common values:

transferencia - Bank transfer
tarjeta - Credit/debit card
efectivo - Cash
cheque - Check

referenciaPago

string

Payment reference number, transaction ID, or receipt number

estadoPago

string

Current payment state. Possible values:

pendiente - Payment pending
pagado - Payment completed
cancelado - Payment canceled
reembolsado - Payment refunded

notas

string

Additional notes or comments about the payment

createdAt

string (datetime)

Timestamp when the record was created

updatedAt

string (datetime)

Timestamp of the last update

updatedByUserId

string (guid)

ID of the user who last updated the record

Get All Payment Histories

GET /api/PaymentHistories

Retrieves all payment history records in the system. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Query Parameters

includeInactive

boolean

default:"false"

Whether to include inactive payment records

Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "contratoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "monto": 1500.00,
    "fechaPago": "2024-03-15T14:30:00Z",
    "metodoPago": "transferencia",
    "referenciaPago": "TRX-2024031500123",
    "estadoPago": "pagado",
    "notas": "Pago mensualidad marzo 2024",
    "createdAt": "2024-03-15T14:35:00Z",
    "updatedAt": "2024-03-15T15:00:00Z",
    "updatedByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
  }
]

Get Payment Histories by Contract

GET /api/PaymentHistories/contrato/{contratoId}

Retrieves all payment history records for a specific contract. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Path Parameters

contratoId

string (guid)

required

The unique identifier of the contract

Query Parameters

includeInactive

boolean

default:"false"

Whether to include inactive payment records

Response

Returns an array of payment history objects for the specified contract, ordered by payment date.

Get Payment History by ID

GET /api/PaymentHistories/{id}

Retrieves a specific payment history record by its ID. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Path Parameters

string (guid)

required

The unique identifier of the payment history record

Query Parameters

includeInactive

boolean

default:"false"

Whether to return the record if it’s inactive

Response

Returns a single payment history object or 404 if not found.

Create Payment History

POST /api/PaymentHistories

Creates a new payment history record. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Request Body

contratoId

string (guid)

required

ID of the contract this payment is associated with

monto

number (decimal)

required

Payment amount (must be positive)

fechaPago

string (datetime)

required

Date when the payment was made (ISO 8601 format)

metodoPago

string

required

Payment method (e.g., transferencia, tarjeta, efectivo, cheque)

referenciaPago

string

Payment reference or transaction ID

estadoPago

string

required

Initial payment state (pendiente, pagado, cancelado, reembolsado)

notas

string

Additional notes about the payment

Example Request

{
  "contratoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "monto": 1500.00,
  "fechaPago": "2024-03-15T14:30:00Z",
  "metodoPago": "transferencia",
  "referenciaPago": "TRX-2024031500123",
  "estadoPago": "pagado",
  "notas": "Pago mensualidad marzo 2024"
}

Response

Status: 201 Created Returns the created payment history object with a Location header pointing to the new resource.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contratoId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "monto": 1500.00,
  "fechaPago": "2024-03-15T14:30:00Z",
  "metodoPago": "transferencia",
  "referenciaPago": "TRX-2024031500123",
  "estadoPago": "pagado",
  "notas": "Pago mensualidad marzo 2024",
  "createdAt": "2024-03-15T14:35:00Z",
  "updatedAt": null,
  "updatedByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
}

Update Payment History

PUT /api/PaymentHistories/{id}

Updates an existing payment history record. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Path Parameters

string (guid)

required

The unique identifier of the payment history record to update

Request Body

monto

number (decimal)

required

Payment amount

fechaPago

string (datetime)

required

Date when the payment was made (ISO 8601 format)

metodoPago

string

required

Payment method

referenciaPago

string

Payment reference or transaction ID

estadoPago

string

required

Payment state (pendiente, pagado, cancelado, reembolsado)

notas

string

Additional notes about the payment

Example Request

{
  "monto": 1500.00,
  "fechaPago": "2024-03-15T14:30:00Z",
  "metodoPago": "transferencia",
  "referenciaPago": "TRX-2024031500123",
  "estadoPago": "reembolsado",
  "notas": "Pago reembolsado por error en facturación"
}

Response

Status: 200 OK Returns the updated payment history object, or 404 if the record doesn’t exist.

Delete Payment History

DELETE /api/PaymentHistories/{id}

Deletes a payment history record from the system. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Deleting payment history records permanently removes financial audit trails. Consider updating the estadoPago to cancelado instead.

Path Parameters

string (guid)

required

The unique identifier of the payment history record to delete

Response

Status: 204 No Content Returns no content on success, or 404 if the record doesn’t exist.

Resident Payments (Pagos)

Resident Payments provide a workflow for residents to submit payment proof and for administrators to confirm and apply those payments. This system is separate from Payment History and focuses on the resident payment submission process.

Resident Payment Object

string (guid)

Unique identifier for the payment

residenteId

string (guid)

ID of the resident who made the payment

residentName

string

Full name of the resident

residentNumber

string

Resident’s identification number

fechaPago

string (datetime)

Date when the payment was made

monto

number (decimal)

Payment amount

status

string

Payment status:

PorConfirmar - Pending admin confirmation
Aplicado - Confirmed and applied to charges
Cancelado - Canceled payment

concepto

string

Description or concept of the payment

urlComprobante

string

URL to the payment receipt or proof document

nota

string

Additional notes about the payment

createdAt

string (datetime)

Timestamp when the payment was submitted

updatedAt

string (datetime)

Timestamp of the last update

createdByUserId

string (guid)

ID of the user who created the payment

updatedByUserId

string (guid)

ID of the user who last updated the payment

System Comparison

Feature	Payment History	Resident Payments
Purpose	Contract payment tracking	Resident payment submissions
Created By	Admins only	Admins and residents
Associated With	Contracts	Residents
Workflow	Direct recording	Confirmation workflow
Status Values	pendiente, pagado, cancelado, reembolsado	PorConfirmar, Aplicado, Cancelado
Proof Upload	Reference field only	Dedicated urlComprobante field
Endpoint	`/api/PaymentHistories`	`/api/PagosResidente`

Get All Resident Payments

GET /api/PagosResidente

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN Retrieves all resident payment submissions.

Example Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "residenteId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "residentName": "Juan Pérez",
    "residentNumber": "RES-001",
    "fechaPago": "2024-03-15T00:00:00Z",
    "monto": 150.00,
    "status": "PorConfirmar",
    "concepto": "Cuota de mantenimiento marzo",
    "urlComprobante": "https://storage.example.com/receipts/receipt-123.pdf",
    "nota": "Pago realizado vía transferencia bancaria",
    "createdAt": "2024-03-15T10:30:00Z",
    "updatedAt": null,
    "createdByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "updatedByUserId": null
  }
]

Get My Payments (Resident)

GET /api/PagosResidente/my

Authorization: All authenticated users Allows residents to view their own payment submissions.

Response

Returns an array of payment objects for the authenticated resident, or an error if the user is not registered as a resident.

Get Payments by Resident

GET /api/PagosResidente/resident/{residentId}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Path Parameters

residentId

string (guid)

required

The unique identifier of the resident

Response

Returns an array of payment objects for the specified resident.

Get Payments by Community

GET /api/PagosResidente/community/{communityId}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Path Parameters

communityId

string (guid)

required

The unique identifier of the community

Response

Returns an array of payment objects for all residents in the specified community.

Get Payment by ID

GET /api/PagosResidente/{id}

Authorization:

Admins can view any payment
Residents can only view their own payments

Path Parameters

string (guid)

required

The unique identifier of the payment

Response

Returns a single payment object, 404 if not found, or 403 if a resident tries to access another resident’s payment.

Create Resident Payment

POST /api/PagosResidente

Authorization: All authenticated users

Role-based behavior:

Admins: Can create payment with any status and for any resident
Residents: Can only create payments for themselves with status “PorConfirmar”

Request Body

residenteId

string (guid)

required

ID of the resident making the payment

fechaPago

string (datetime)

required

Date when the payment was made

monto

number (decimal)

required

Payment amount (must be positive)

status

string

default:"PorConfirmar"

Payment status (residents can only use “PorConfirmar”)

concepto

string

Description of what the payment is for

urlComprobante

string

URL to the uploaded payment receipt or proof

nota

string

Additional notes about the payment

createdByUserId

string (guid)

ID of the user creating the payment

Example Request (Resident)

{
  "residenteId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "fechaPago": "2024-03-15T00:00:00Z",
  "monto": 150.00,
  "status": "PorConfirmar",
  "concepto": "Cuota de mantenimiento marzo",
  "urlComprobante": "https://storage.example.com/receipts/receipt-123.pdf",
  "nota": "Pago realizado vía transferencia bancaria"
}

Example Request (Admin)

{
  "residenteId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "fechaPago": "2024-03-15T00:00:00Z",
  "monto": 150.00,
  "status": "Aplicado",
  "concepto": "Cuota de mantenimiento marzo",
  "urlComprobante": "https://storage.example.com/receipts/receipt-123.pdf",
  "nota": "Pago verificado y aplicado directamente",
  "createdByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
}

Response

Status: 201 Created Returns the created payment object with a Location header.

Update Resident Payment

PUT /api/PagosResidente/{id}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN Used by administrators to update payment status after verification or to modify payment details.

Path Parameters

string (guid)

required

The unique identifier of the payment to update

Request Body

residenteId

string (guid)

required

ID of the resident

fechaPago

string (datetime)

required

Date when the payment was made

monto

number (decimal)

required

Payment amount

status

string

required

Payment status (PorConfirmar, Aplicado, Cancelado)

concepto

string

Description of the payment

urlComprobante

string

URL to the payment receipt

nota

string

Additional notes

updatedByUserId

string (guid)

ID of the user updating the payment

Example Request

{
  "residenteId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "fechaPago": "2024-03-15T00:00:00Z",
  "monto": 150.00,
  "status": "Aplicado",
  "concepto": "Cuota de mantenimiento marzo",
  "urlComprobante": "https://storage.example.com/receipts/receipt-123.pdf",
  "nota": "Pago verificado y aplicado a cargo correspondiente",
  "updatedByUserId": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
}

Response

Status: 200 OK Returns the updated payment object, or 404 if not found.

Delete Resident Payment

DELETE /api/PagosResidente/{id}

Authorization: ADMIN_COMPANY, SYSTEM_ADMIN

Path Parameters

string (guid)

required

The unique identifier of the payment to delete

Response

Status: 204 No Content Returns no content on success, or 404 if not found.

Payment Workflow

Resident Payment Submission Workflow

Resident submits payment:
```
POST /api/PagosResidente
```
- Status: “PorConfirmar”
- Includes payment amount, date, and proof (urlComprobante)
Admin views pending payments:
```
GET /api/PagosResidente?status=PorConfirmar
```
- Reviews payment details and proof
Admin confirms payment:
```
PUT /api/PagosResidente/{id}
```
- Updates status to “Aplicado”
- Adds verification notes
Admin updates corresponding charge:
```
PUT /api/CargosResidente/{chargeId}
```
- Updates charge status to “Pagado” or “PagoParcial”

Error Responses

400 Bad Request

Returned when the request data is invalid:

{
  "error": "INVALID_OPERATION",
  "message": "Contract does not exist"
}

401 Unauthorized

Returned when authentication is missing or invalid.

403 Forbidden

Returned when:

User doesn’t have the required role
Resident tries to access another resident’s payments
Resident tries to create payment for another resident

{
  "error": "BAD_REQUEST",
  "message": "Usuario no está registrado como residente."
}

404 Not Found

Returned when the requested payment record doesn’t exist.

Best Practices

Payment History

Reference Numbers: Always include payment reference numbers for traceability
Audit Trail: Avoid deleting payment records; use status updates instead
Payment Methods: Use consistent metodoPago values across the system
Notes: Add detailed notes for unusual transactions or refunds
Contract Validation: Verify contract exists before creating payment history
Date Accuracy: Use the actual payment date, not the processing date
Status Tracking: Update estadoPago as payments progress through their lifecycle

Resident Payments

Upload Proof: Always encourage residents to upload payment receipts (urlComprobante)
Clear Concepts: Use descriptive payment concepts for easy identification
Timely Review: Review and confirm resident payments promptly
Status Updates: Keep residents informed by updating payment status
Link to Charges: After confirming payment, update corresponding charges
Audit Notes: Add notes when confirming or canceling payments
Amount Validation: Verify payment amounts match expected charges before confirming

Authentication

Residents

Communities

Amenities

Documents

Payments & Charges

Tickets

Vehicles & Pets

Visits

Announcements & Surveys

Error Handling

​Overview

​Payment History

​Payment History Object

​Get All Payment Histories

​Query Parameters

​Example Response

​Get Payment Histories by Contract

​Path Parameters

​Query Parameters

​Response

​Get Payment History by ID

​Path Parameters

​Query Parameters

​Response

​Create Payment History

​Request Body

​Example Request

​Response

​Update Payment History

​Path Parameters

​Request Body

​Example Request

​Response

​Delete Payment History

​Path Parameters

​Response

​Resident Payments (Pagos)

​Resident Payment Object

​System Comparison

​Get All Resident Payments

​Example Response

​Get My Payments (Resident)

​Response

​Get Payments by Resident

​Path Parameters

​Response

​Get Payments by Community

​Path Parameters

​Response

​Get Payment by ID

​Path Parameters

​Response

​Create Resident Payment

​Request Body

​Example Request (Resident)

​Example Request (Admin)

​Response

​Update Resident Payment

​Path Parameters

​Request Body

​Example Request

​Response

​Delete Resident Payment

​Path Parameters

​Response

​Payment Workflow

​Resident Payment Submission Workflow

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Best Practices

​Payment History

​Resident Payments

Build docs developers (and LLMs) love

Overview

Payment History

Payment History Object

Get All Payment Histories

Query Parameters

Example Response

Get Payment Histories by Contract

Path Parameters

Query Parameters

Response

Get Payment History by ID

Path Parameters

Query Parameters

Response

Create Payment History

Request Body

Example Request

Response

Update Payment History

Path Parameters

Request Body

Example Request

Response

Delete Payment History

Path Parameters

Response

Resident Payments (Pagos)

Resident Payment Object

System Comparison

Get All Resident Payments

Example Response

Get My Payments (Resident)

Response

Get Payments by Resident

Path Parameters

Response

Get Payments by Community

Path Parameters

Response

Get Payment by ID

Path Parameters

Response

Create Resident Payment

Request Body

Example Request (Resident)

Example Request (Admin)

Response

Update Resident Payment

Path Parameters

Request Body

Example Request

Response

Delete Resident Payment

Path Parameters

Response

Payment Workflow

Resident Payment Submission Workflow

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Best Practices

Payment History

Resident Payments