Payments and Customer Orders API Endpoints

All protected endpoints require a valid JWT token obtained from POST /api/users/login. Include it in the Authorization header:

Authorization: Bearer <your_jwt_token>

Payments

Payments capture money received from customers. Whether a payment starts as approved or unapproved depends on how it is created — see the individual endpoints for details. Approving a payment increments the AutoLavado’s balanceUsd and/or balanceBs depending on the payment method.

Get All Payments

🔒 Requires: Any authenticated user (token required) Returns all payment records ordered by most recent first, with each payment’s customer details nested inside.

curl http://localhost:3000/api/payments \
  -H "Authorization: Bearer <token>"

Response 200 — Array of Payment objects:

string

UUID of the payment record.

customerId

string

UUID of the customer who made the payment.

customer

object

Nested customer (User) object.

method

string

Payment method used.

mountUSD

number

Amount paid in USD.

mountBS

number

Amount paid in bolívares.

reference

string | null

Transaction reference number, if provided.

approved

boolean

Whether the payment has been verified and applied to the business balance.

date

string

ISO 8601 datetime of the payment.

[
  {
    "id": "uuid",
    "customerId": "uuid",
    "customer": { "name": "Ana", "lastName": "López" },
    "method": "Pago Movil",
    "mountUSD": 0,
    "mountBS": 4666.60,
    "reference": "REF123456",
    "approved": true,
    "date": "2026-06-26T11:00:00.000Z"
  }
]

Create a Payment

🔒 Requires: Any authenticated user (token required) Registers a new incoming payment from a customer. Payments created through this endpoint are immediately marked approved: true and the AutoLavado’s balance is updated in the same transaction. This endpoint is intended for in-person POS transactions where funds are confirmed at the time of creation.

customerId

string

required

UUID of the customer making the payment. Must correspond to an existing user.

method

string

required

Payment method. Accepted values: Pago Movil, Efectivo, Binance, debit, transferencia, Zelle, Punto de Venta, cash.

mountUSD

number

required

Amount in USD. For BS-only methods (e.g. Pago Movil), pass 0.

mountBS

number

required

Amount in bolívares. Must be 0 when method is binance — Binance payments are USD-only.

reference

string

Transaction or confirmation reference number. Required for non-cash methods (e.g. Pago Movil, transferencia). Optional for cash payments.

If method is binance, mountBS must be 0. Sending a non-zero mountBS will return a 400 error: "Los pagos por Binance solo permiten USD (el monto en Bs debe ser 0)".For non-cash methods, reference is required. Omitting it returns 400: "El número de referencia es obligatorio para pagos con {method}".

curl -X POST http://localhost:3000/api/payments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-uuid>",
    "method": "Pago Movil",
    "mountUSD": 0,
    "mountBS": 4666.60,
    "reference": "REF123456"
  }'

Response 201 — The newly created Payment object (always approved: true for this endpoint):

string

UUID of the payment record.

customerId

string

UUID of the paying customer.

method

string

Payment method used.

mountUSD

number

Amount paid in USD.

mountBS

number

Amount paid in bolívares.

reference

string | null

Transaction reference number, if provided.

approved

boolean

Always true for payments created via this endpoint — funds are confirmed at POS creation time.

date

string

ISO 8601 datetime of the payment.

{
  "id": "uuid",
  "customerId": "uuid",
  "method": "Pago Movil",
  "mountUSD": 0,
  "mountBS": 4666.60,
  "reference": "REF123456",
  "approved": true,
  "date": "2026-06-26T11:00:00.000Z"
}

Approve a Payment

🔒 Requires: ADMIN role Verifies and approves a pending payment (one with approved: false). Sets approved: true and adds the payment amounts to the AutoLavado’s financial balances. The balance update is method-aware:

Method	Balance updated
`Pago Movil`, `Efectivo BS`, `Punto de Venta`	`balanceBs` incremented by `mountBS`
`Zelle`, `Efectivo USD`, `Binance`, `Cash`	`balanceUsd` incremented by `mountUSD`
All other methods	Both `balanceBs` and `balanceUsd` incremented

string

required

UUID of the payment to approve.

Returns 400 with "El pago ya se encuentra aprobado" if the payment has already been approved. Each payment can only be approved once.

curl -X PATCH http://localhost:3000/api/payments/<payment-uuid>/approve \
  -H "Authorization: Bearer <token>"

Response 200 — Updated Payment object with approved: true, plus a confirmation message:

{
  "message": "Pago aprobado y balance actualizado exitosamente",
  "payment": {
    "id": "uuid",
    "customerId": "uuid",
    "method": "Pago Movil",
    "mountUSD": 0,
    "mountBS": 4666.60,
    "reference": "REF123456",
    "approved": true,
    "date": "2026-06-26T11:00:00.000Z"
  }
}

Customer Orders

Customer Orders allow clients to submit product purchases and service requests through the web interface. An order starts as PENDING and moves to APPROVED or REJECTED after admin review.

Order Status Reference:

PENDING — Order has been created, inventory decremented, but not yet reviewed by an admin.
APPROVED — Admin has approved the order and a Sales record has been generated.
REJECTED — Admin has rejected the order. Inventory is restored and any linked service orders are marked CANCELLED.

Calling POST /api/customer/orders/:id/pay links a payment to the order but does not change its status — the order remains PENDING until an admin calls the approve or reject endpoints.

Get My Orders (Customer)

🔒 Requires: CUSTOMER role Returns all orders belonging to the authenticated customer, based on the JWT token identity. Orders are returned in descending date order and include full details with linked items, services, and payment.

curl http://localhost:3000/api/customer/orders/my \
  -H "Authorization: Bearer <token>"

Response 200 — Array of OrderCustomers objects for the authenticated customer.

[
  {
    "id": "uuid",
    "customerId": "uuid",
    "paymentId": "uuid",
    "status": "PENDING",
    "date": "2026-06-26T10:00:00.000Z",
    "customer": { "name": "Ana", "lastName": "López" },
    "payment": { "method": "Pago Movil", "approved": false },
    "details": [
      {
        "id": "uuid",
        "orderId": "uuid",
        "itemId": "uuid",
        "serviceId": null,
        "cant": 2,
        "UPriceUsd": 2.5,
        "item": { "name": "Ambientador Pino" }
      }
    ]
  }
]

Get All Orders (Admin)

🔒 Requires: ADMIN role Returns all customer orders across all customers. Includes full details with items, services, service orders, and linked payments.

curl http://localhost:3000/api/customer/orders \
  -H "Authorization: Bearer <token>"

Response 200 — Array of all OrderCustomers objects.

Create a Customer Order

🔒 Requires: CUSTOMER role Creates a new order from the customer-facing web interface. The customerId is taken automatically from the authenticated JWT token — it is not accepted in the request body. Each order can include a mix of product purchases and service requests. The following effects happen atomically in a single transaction:

For product details (itemId): Inventory is checked for sufficient stock and decremented by cant immediately.
For service details (serviceId): A new ServiceOrders entry is created in En cola state and linked to this order.

carId

string

UUID of the customer’s vehicle. Required when any details entry includes a serviceId.

details

array

required

Array of order line items. Each entry must have either itemId or serviceId, along with cant:

Product line: { "itemId": "uuid", "cant": 2 }
Service line: { "serviceId": "uuid", "cant": 1 }

Prices are fetched from the database automatically — do not supply UPriceUsd in the request body.

Returns 400 if there is insufficient inventory for any product line: "Inventario insuficiente para el item {itemId}". Inventory is decremented at creation, before payment is linked.

curl -X POST http://localhost:3000/api/customer/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "carId": "<vehicle-uuid>",
    "details": [
      {
        "itemId": "<ambientador-uuid>",
        "cant": 1
      },
      {
        "serviceId": "<lavado-basico-uuid>",
        "cant": 1
      }
    ]
  }'

Response 201 — The newly created OrderCustomers object:

string

UUID of the customer order.

customerId

string

UUID of the customer who placed the order (from JWT token).

paymentId

string | null

UUID of the linked payment. null until POST /api/customer/orders/:id/pay is called.

status

string

Current order status. Always PENDING on creation.

date

string

ISO 8601 datetime when the order was placed.

{
  "id": "uuid",
  "customerId": "uuid",
  "paymentId": null,
  "status": "PENDING",
  "date": "2026-06-26T10:00:00.000Z"
}

Pay for a Customer Order

🔒 Requires: Any authenticated user (token required) Creates a Payment record and links it to the customer order by setting its paymentId. The order status remains PENDING — admin approval is still required after payment is linked. The created payment starts with approved: false and must be approved separately via PATCH /api/payments/:id/approve.

string

required

UUID of the OrderCustomers record to pay for.

method

string

required

Payment method. Accepted values: debit, Pago Movil, binance, cash, transferencia.

mountUSD

number

required

Amount in USD.

mountBS

number

required

Amount in bolívares. Must be 0 if method is binance.

Returns 400 if the order already has a payment linked: "La orden ya tiene un pago registrado". Each order can only be paid once.

curl -X POST http://localhost:3000/api/customer/orders/<order-uuid>/pay \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "Pago Movil",
    "mountUSD": 0,
    "mountBS": 4666.60
  }'

Response 200 — Updated OrderCustomers object with paymentId populated:

{
  "message": "Pago registrado exitosamente",
  "order": {
    "id": "uuid",
    "customerId": "uuid",
    "paymentId": "uuid",
    "status": "PENDING",
    "date": "2026-06-26T10:00:00.000Z"
  }
}

The payment created by this endpoint starts as approved: false. An admin must verify the transaction and call PATCH /api/payments/:id/approve to apply the funds to the AutoLavado’s balance, then call PATCH /api/customer/orders/:id/approve to finalize the sale.

Approve a Customer Order

🔒 Requires: ADMIN role Approves a PENDING customer order that has an associated payment. Creates a Sales record (including line-item SalesDetails) and transitions the order status to APPROVED. The exchange rate and payment method are captured on the sale record.

string

required

UUID of the OrderCustomers record to approve.

tazaUsd

number

required

The USD/BS exchange rate at the time of approval. Used to calculate the bolivar equivalent on the Sales record.

methodPayment

string

required

The payment method applied to this sale.

Returns 400 if the order status is not PENDING or if the order has no linked paymentId. Only paid, pending orders can be approved.

curl -X PATCH http://localhost:3000/api/customer/orders/<order-uuid>/approve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tazaUsd": 36.5,
    "methodPayment": "Pago Movil"
  }'

Response 200 — The newly created Sales record with line items:

{
  "message": "Orden aprobada exitosamente",
  "sale": {
    "id": "uuid",
    "tazaUsd": 36.5,
    "totalUsd": 7.5,
    "paymentId": "uuid",
    "userId": "uuid",
    "date": "2026-06-26T12:00:00.000Z",
    "salesDetails": [
      {
        "id": "uuid",
        "cant": 1,
        "UPriceUsd": 2.5,
        "itemId": "uuid",
        "serviceOrderId": null
      }
    ]
  }
}

Reject a Customer Order

🔒 Requires: ADMIN role Rejects a PENDING customer order. All side effects are reversed atomically:

Product inventory is restored — the quantity decremented at order creation is added back.
Linked service orders are marked CANCELLED rather than deleted, preserving the audit trail.
The order is marked REJECTED.

string

required

UUID of the OrderCustomers record to reject.

Returns 400 if the order status is not PENDING. Only pending orders can be rejected.

curl -X DELETE http://localhost:3000/api/customer/orders/<order-uuid>/reject \
  -H "Authorization: Bearer <token>"

Response 200:

{
  "message": "Orden rechazada y eliminada exitosamente"
}

Overview

Endpoints

Payments and Customer Orders API Endpoints

Payments

Get All Payments

Create a Payment

Approve a Payment

Customer Orders

Get My Orders (Customer)

Get All Orders (Admin)

Create a Customer Order

Pay for a Customer Order

Approve a Customer Order

Reject a Customer Order

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Payments

​Get All Payments

​Create a Payment

​Approve a Payment

​Customer Orders

​Get My Orders (Customer)

​Get All Orders (Admin)

​Create a Customer Order

​Pay for a Customer Order

​Approve a Customer Order

​Reject a Customer Order

Build docs developers (and LLMs) love

Payments

Get All Payments

Create a Payment

Approve a Payment

Customer Orders

Get My Orders (Customer)

Get All Orders (Admin)

Create a Customer Order

Pay for a Customer Order

Approve a Customer Order

Reject a Customer Order