Skip to main content
POST
/
api
/
v1
/
accounts
/
payment
Account Payments
curl --request POST \
  --url https://api.example.com/api/v1/accounts/payment \
  --header 'Content-Type: application/json' \
  --data '
{
  "date": "<string>",
  "time": "<string>",
  "ventanaId": "<string>",
  "vendedorId": "<string>",
  "bancaId": "<string>",
  "amount": 123,
  "type": {},
  "method": {},
  "notes": "<string>",
  "isFinal": true,
  "idempotencyKey": "<string>"
}
'
{
  "payment": {
    "id": "<string>",
    "date": "<string>",
    "time": "<string>",
    "amount": 123,
    "type": "<string>",
    "method": "<string>",
    "isReversed": true,
    "paidById": "<string>",
    "createdAt": "<string>"
  },
  "statement": {},
  "meta.cached": true
}

​
Overview

Registers a payment (pago) or collection (cobro) to settle account balances. Supports idempotency and returns updated statement.

​
Authentication

Requires JWT authentication:
  • VENDEDOR: Not authorized
  • VENTANA: Can register payments for own window or sellers
  • ADMIN: Can register payments for any entity

​
Request Body

​
date
string
required
Payment date in YYYY-MM-DD format (cannot be future)
​
time
string
Payment time in HH:MM 24-hour format (default: 00:00). Cannot be future if date is today.
​
ventanaId
string
Window ID (required for window-level payments). Mutually exclusive with vendedorId and bancaId.
​
vendedorId
string
Seller ID (required for seller-level payments). Mutually exclusive with ventanaId and bancaId.
​
bancaId
string
Banca ID (admin only, required for banca-level payments). Mutually exclusive with ventanaId and vendedorId.
​
amount
number
required
Payment amount (must be > 0)
​
type
enum
required
Payment type: payment (pago) or collection (cobro)
​
method
enum
required
Payment method: cash, check, transfer, system
​
notes
string
Optional notes (max 500 characters)
​
isFinal
boolean
default:"false"
Mark day as settled (saldado)
​
idempotencyKey
string
Unique key for idempotency (min 8 characters). If key exists, returns cached payment.

​
Response

​
payment
object
Created payment record
​
statement
object
Updated account statement for the day
​
meta.cached
boolean
Present if payment returned from idempotency cache (status 200 instead of 201)

​
Status Codes

  • 201: Payment created successfully
  • 200: Cached payment returned (idempotency)
  • 400: Invalid date/time or missing dimension
  • 403: RBAC violation

​
Example Request

{
  "date": "2024-03-15",
  "time": "14:30",
  "ventanaId": "ventana-001",
  "amount": 100000,
  "type": "payment",
  "method": "cash",
  "notes": "Pago parcial de ventas del día",
  "isFinal": false,
  "idempotencyKey": "payment-2024-03-15-001"
}

​
Example Response

{
  "success": true,
  "data": {
    "payment": {
      "id": "pay-abc-123",
      "date": "2024-03-15",
      "time": "14:30",
      "amount": 100000,
      "type": "payment",
      "method": "cash",
      "notes": "Pago parcial de ventas del día",
      "isReversed": false,
      "isFinal": false,
      "paidById": "user-123",
      "createdAt": "2024-03-15T20:30:00.000Z"
    },
    "statement": {
      "id": "stmt-001",
      "date": "2024-03-15",
      "totalSales": 500000,
      "totalPayouts": 250000,
      "totalPaid": 100000,
      "remainingBalance": 132500,
      "isSaldado": false
    }
  }
}

​
Validation Rules

  1. Date: Cannot be future date
  2. Time: Cannot be future if date is today (Costa Rica time)
  3. Dimension: Must provide exactly one of bancaId, ventanaId, or vendedorId
  4. Amount: Must be positive number
  5. RBAC: VENTANA users can only register payments for their window/sellers

​
Activity Logging

Logs action ACCOUNT_PAYMENT_CREATE with payment details.

Build docs developers (and LLMs) love

Get started for freeTalk to us