Payments API - Core Projects - Constructora AyC

Overview

The Payments API manages payment records (pagos) for sales operations. Payments can be linked to:

Sales/Separations: General payments for a sale
Cuotas: Specific installment payments from amortization plan

Payments track the payment method, concept, amount, and reference information.

Model Structure

Pago Model

Table: pagos
Primary Key: id_pago (auto-increment)

Attributes

id_pago

integer

Primary key, auto-increment

fecha

datetime

required

Payment date and time

id_venta

integer

required

Foreign key to ventas table. The sale this payment belongs to.

referencia_pago

string

Payment reference number (transaction ID, check number, etc.). Max 60 characters.

id_concepto_pago

integer

Foreign key to conceptos_pago table. Payment concept/purpose.

id_medio_pago

integer

Foreign key to medios_pago table. Payment method used.

descripcion

text

Additional payment notes or description

valor

decimal(15,2)

required

Payment amount

id_cuota

integer

Optional. Foreign key to planes_amortizacion_cuota table. Links payment to specific installment.

created_at

timestamp

Record creation timestamp

updated_at

timestamp

Last update timestamp

Relationships

venta

BelongsTo

The sale this payment is for. Includes client and property details.

conceptoPago

BelongsTo

Payment concept details (e.g., “Cuota Inicial”, “Abono”, “Separación”)

medioPago

BelongsTo

Payment method details (e.g., “Efectivo”, “Transferencia”, “Cheque”)

cuota

BelongsTo

Optional. Specific installment from payment plan this payment covers.

List All Payments

curl -X GET "https://api.coreprojects.com/pagos" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Query Parameters

id_venta

integer

Filter payments by sale ID

documento_cliente

string

Filter payments by client document

id_concepto_pago

integer

Filter by payment concept

id_medio_pago

integer

Filter by payment method

fecha_desde

date

Filter payments from this date (format: YYYY-MM-DD)

fecha_hasta

date

Filter payments until this date (format: YYYY-MM-DD)

Response

[
  {
    "id_pago": 1,
    "fecha": "2024-01-15T14:30:00.000000Z",
    "id_venta": 1,
    "referencia_pago": "TRF-2024-001234",
    "id_concepto_pago": 1,
    "id_medio_pago": 2,
    "descripcion": "Pago primera cuota",
    "valor": 3750000.00,
    "id_cuota": 1,
    "created_at": "2024-01-15T14:30:00.000000Z",
    "updated_at": "2024-01-15T14:30:00.000000Z",
    "venta": {
      "id_venta": 1,
      "tipo_operacion": "venta",
      "valor_total": 270000000,
      "cliente": {
        "documento": "1234567890",
        "nombre": "Juan Pérez García"
      }
    },
    "concepto_pago": {
      "id_concepto_pago": 1,
      "concepto": "Cuota Inicial",
      "descripcion": "Pago de cuota inicial"
    },
    "medio_pago": {
      "id_medio_pago": 2,
      "medio_pago": "Transferencia Bancaria",
      "descripcion": "Transferencia electrónica"
    },
    "cuota": {
      "id_cuota": 1,
      "numero_cuota": 1,
      "fecha_vencimiento": "2024-02-15",
      "valor_cuota": 3750000.00,
      "estado": "Pagada"
    }
  }
]

Get Payment by ID

curl -X GET "https://api.coreprojects.com/pagos/{id}" \
  -H "Authorization: Bearer {token}"

Path Parameters

integer

required

Payment ID (id_pago)

Create Payment

curl -X POST "https://api.coreprojects.com/pagos" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha": "2024-01-15 14:30:00",
    "id_venta": 1,
    "referencia_pago": "TRF-2024-001234",
    "id_concepto_pago": 1,
    "id_medio_pago": 2,
    "descripcion": "Pago primera cuota",
    "valor": 3750000,
    "id_cuota": 1
  }'

Request Body

fecha

datetime

Payment date and time. Defaults to current timestamp if not provided.

id_venta

integer

required

Sale ID this payment belongs to

referencia_pago

string

Payment reference number (transaction ID, check number, etc.). Max 60 characters.

id_concepto_pago

integer

Payment concept ID. Common concepts:

Cuota Inicial (Down Payment)
Abono (Partial Payment)
Separación (Separation Fee)
Saldo Final (Final Balance)

id_medio_pago

integer

Payment method ID. Common methods:

Efectivo (Cash)
Transferencia Bancaria (Bank Transfer)
Cheque (Check)
Tarjeta de Crédito (Credit Card)
Consignación (Bank Deposit)

descripcion

string

Additional payment notes or description

valor

decimal

required

Payment amount (must be > 0)

id_cuota

integer

Optional. Links this payment to a specific installment from the amortization plan.

Validation Rules

fecha: Optional datetime. Defaults to now() if not provided
id_venta: Required, must exist in ventas table
referencia_pago: Optional string, max 60 characters
id_concepto_pago: Optional, must exist in conceptos_pago table
id_medio_pago: Optional, must exist in medios_pago table
descripcion: Optional text field
valor: Required, numeric, must be ≥ 0
id_cuota: Optional, must exist in planes_amortizacion_cuota table

Response

{
  "id_pago": 1,
  "fecha": "2024-01-15T14:30:00.000000Z",
  "id_venta": 1,
  "referencia_pago": "TRF-2024-001234",
  "id_concepto_pago": 1,
  "id_medio_pago": 2,
  "descripcion": "Pago primera cuota",
  "valor": 3750000.00,
  "id_cuota": 1,
  "created_at": "2024-01-15T14:30:00.000000Z",
  "updated_at": "2024-01-15T14:30:00.000000Z"
}

Error Responses

422

validation_error

Validation errors:

Sale not found (invalid id_venta)
Invalid concepto_pago or medio_pago ID
Invalid cuota ID
Invalid amount (negative or zero)

Update Payment

curl -X PUT "https://api.coreprojects.com/pagos/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_pago": "TRF-2024-001234-UPDATED",
    "descripcion": "Pago primera cuota - corregido",
    "valor": 3800000
  }'

Path Parameters

integer

required

Payment ID to update

Updating payment amounts does NOT automatically update cuota status. You must manually update the related cuota if the payment amount changes.

Delete Payment

curl -X DELETE "https://api.coreprojects.com/pagos/{id}" \
  -H "Authorization: Bearer {token}"

Path Parameters

integer

required

Payment ID to delete

Deleting a payment does NOT update the related cuota status. If the payment was linked to a cuota, you must manually update the cuota status to “Pendiente”.

Response

{
  "message": "Pago eliminado correctamente"
}

Payment Concepts

ConceptoPago Model

Table: conceptos_pago
Primary Key: id_concepto_pago

Common Payment Concepts

Cuota Inicial

concept

Down payment installments

Separación

concept

Separation/reservation fee

Abono

concept

Partial payment or advance

Saldo Final

concept

Final balance payment

Intereses

concept

Interest payment

Mora

concept

Late payment fee

List Payment Concepts

$conceptos = ConceptoPago::orderBy('concepto')->get();

Payment Methods

MedioPago Model

Table: medios_pago
Primary Key: id_medio_pago

Common Payment Methods

Efectivo

method

Cash payment

Transferencia Bancaria

method

Bank transfer

Cheque

method

Check payment

Tarjeta de Crédito

method

Credit card

Tarjeta de Débito

method

Debit card

Consignación

method

Bank deposit

List Payment Methods

$medios = MedioPago::orderBy('medio_pago')->get();

Business Logic

Payment to Sale

Payments are always linked to a sale (id_venta). The sale contains:

Client information
Property details
Total amount
Payment terms

Payment to Cuota

Optionally, payments can be linked to specific installments (id_cuota) from the amortization plan:

// When creating payment for a cuota
$pago = Pago::create([
    'id_venta' => $venta->id_venta,
    'id_cuota' => $cuota->id_cuota,
    'valor' => $cuota->valor_cuota,
    'id_concepto_pago' => $conceptoCuotaInicial->id_concepto_pago,
    'fecha' => now(),
]);

// Update cuota status
$cuota->update(['estado' => 'Pagada']);

Payment Tracking

To calculate paid amount for a sale:

$totalPagado = Pago::where('id_venta', $idVenta)->sum('valor');
$saldoPendiente = $venta->valor_total - $totalPagado;

Cuota Status Management

When a payment is linked to a cuota, update the cuota status:

$cuota = PlanAmortizacionCuota::find($idCuota);

$totalPagado = Pago::where('id_cuota', $idCuota)->sum('valor');

if ($totalPagado >= $cuota->valor_cuota) {
    $cuota->update(['estado' => 'Pagada']);
} elseif ($totalPagado > 0) {
    $cuota->update(['estado' => 'Parcial']);
} else {
    $cuota->update(['estado' => 'Pendiente']);
}

Audit Trail

Payments provide an audit trail:

referencia_pago: External transaction reference
fecha: When payment was received
medio_pago: How payment was made
concepto_pago: What payment was for
descripcion: Additional notes

Payments are typically NOT deleted. If a payment is voided or reversed, create a negative payment or use a “Reversión” concept.

Reporting Queries

Payments by Date Range

$pagos = Pago::whereBetween('fecha', [$fechaInicio, $fechaFin])
    ->with(['venta.cliente', 'conceptoPago', 'medioPago'])
    ->orderBy('fecha')
    ->get();

Payments by Client

$pagos = Pago::whereHas('venta', function ($q) use ($documentoCliente) {
    $q->where('documento_cliente', $documentoCliente);
})
->with(['venta', 'conceptoPago', 'medioPago'])
->orderBy('fecha', 'desc')
->get();

Payments by Project

$pagos = Pago::whereHas('venta', function ($q) use ($idProyecto) {
    $q->where('id_proyecto', $idProyecto);
})
->with(['venta.cliente', 'conceptoPago', 'medioPago'])
->sum('valor');

Payments by Payment Method

$pagosPorMedio = Pago::select('id_medio_pago', DB::raw('SUM(valor) as total'))
    ->whereBetween('fecha', [$fechaInicio, $fechaFin])
    ->groupBy('id_medio_pago')
    ->with('medioPago')
    ->get();

Sales API - Sales that receive payments
Amortization API - Payment schedules and cuotas
Clients API - Client making payments

Overview

Geographic Data

Projects & Properties

Sales & Clients

Organization

​Overview

​Model Structure

​Pago Model

​Attributes

​Relationships

​List All Payments

​Query Parameters

​Response

​Get Payment by ID

​Path Parameters

​Create Payment

​Request Body

​Validation Rules

​Response

​Error Responses

​Update Payment

​Path Parameters

​Delete Payment

​Path Parameters

​Response

​Payment Concepts

​ConceptoPago Model

​Common Payment Concepts

​List Payment Concepts

​Payment Methods

​MedioPago Model

​Common Payment Methods

​List Payment Methods

​Business Logic

​Payment to Sale

​Payment to Cuota

​Payment Tracking

​Cuota Status Management

​Audit Trail

​Reporting Queries

​Payments by Date Range

​Payments by Client

​Payments by Project

​Payments by Payment Method

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Model Structure

Pago Model

Attributes

Relationships

List All Payments

Query Parameters

Response

Get Payment by ID

Path Parameters

Create Payment

Request Body

Validation Rules

Response

Error Responses

Update Payment

Path Parameters

Delete Payment

Path Parameters

Response

Payment Concepts

ConceptoPago Model

Common Payment Concepts

List Payment Concepts

Payment Methods

MedioPago Model

Common Payment Methods

List Payment Methods

Business Logic

Payment to Sale

Payment to Cuota

Payment Tracking

Cuota Status Management

Audit Trail

Reporting Queries

Payments by Date Range

Payments by Client

Payments by Project

Payments by Payment Method

Related Endpoints