Pagos

El recurso Pagos te permite registrar pagos sobre una venta existente y consultarlos. Es la forma de saldar una venta que quedó con balance pendiente o de registrar abonos posteriores.

Todas las rutas son relativas a la URL base de producción:

https://api-pos.zelta.dev/public/v1

INFO

La autenticación se hace con el header Authorization: Bearer <key> o X-API-Key: <key>, usando una llave con prefijo zpk_. Consulta para más detalles.

Registrar un pago

POST /payments

Registra un pago sobre una venta. Devuelve 201. Si el monto excede el balance pendiente de la venta, responde 409 (conflict).

Campos del cuerpo

Campo	Tipo	Requerido	Descripción
saleId	string (cuid2)	Sí	ID de la venta. Es el saleId que devuelve .
paymentMethod	string (cuid2)	Sí	ID del método de pago. Lo obtienes de .
amount	number	Sí	Monto del pago. Debe ser mayor que 0.
reference	string	No	Referencia libre del pago (máx. 500 caracteres).

TIP

El saleId proviene de la respuesta de creación de una factura. Guárdalo si planeas registrar pagos en momentos distintos al de la venta (por ejemplo, ventas a crédito).

curl -X POST "https://api-pos.zelta.dev/public/v1/payments" \
  -H "Authorization: Bearer zpk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "saleId": "sal_1a2b3c4d5e6f7g8h",
    "paymentMethod": "pm_2x9a8b7c6d5e4f3g",
    "amount": 59.20,
    "reference": "Transferencia ACH #88231"
  }'

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    saleId: 'sal_1a2b3c4d5e6f7g8h',
    paymentMethod: 'pm_2x9a8b7c6d5e4f3g',
    amount: 59.20,
    reference: 'Transferencia ACH #88231'
  })
});
const data = await res.json();

Ejemplo Py

import requests

res = requests.post(
    'https://api-pos.zelta.dev/public/v1/payments',
    headers={'Authorization': 'Bearer zpk_live_xxx', 'Content-Type': 'application/json'},
    json={
        'saleId': 'sal_1a2b3c4d5e6f7g8h',
        'paymentMethod': 'pm_2x9a8b7c6d5e4f3g',
        'amount': 59.20,
        'reference': 'Transferencia ACH #88231'
    }
)
data = res.json()

Respuesta

{
  "id": "pay_3c4d5e6f7g8h9i0j",
  "paymentMethodId": "pm_2x9a8b7c6d5e4f3g",
  "amount": "59.20",
  "reference": "Transferencia ACH #88231",
  "allocations": [
    { "orderId": "sal_1a2b3c4d5e6f7g8h", "amount": "59.20" }
  ],
  "date": "2026-06-30T14:25:00.000Z"
}

Campo	Tipo	Descripción
id	string	ID del pago.
paymentMethodId	string	Método de pago usado.
amount	string	Monto del pago.
reference	string | null	Referencia del pago.
allocations	array	Distribución del pago. Cada elemento tiene orderId y amount.
date	string	Fecha del pago.

Listar pagos

GET /payments

Devuelve la lista de pagos en un envoltorio { "data": [ ... ] }. Soporta paginación y sincronización incremental (start, limit, updatedSince, from/to, metadata). Consulta la .

curl "https://api-pos.zelta.dev/public/v1/payments?limit=30&metadata=true" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/payments?limit=30&metadata=true', {
  headers: { 'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}` }
});
const data = await res.json();

Ejemplo Py

import requests

res = requests.get(
    'https://api-pos.zelta.dev/public/v1/payments',
    headers={'Authorization': 'Bearer zpk_live_xxx'},
    params={'limit': 30, 'metadata': 'true'}
)
data = res.json()

{
  "data": [
    {
      "id": "pay_3c4d5e6f7g8h9i0j",
      "paymentMethodId": "pm_2x9a8b7c6d5e4f3g",
      "amount": "59.20",
      "reference": "Transferencia ACH #88231",
      "allocations": [
        { "orderId": "sal_1a2b3c4d5e6f7g8h", "amount": "59.20" }
      ],
      "date": "2026-06-30T14:25:00.000Z"
    }
  ],
  "metadata": { "total": 1 }
}

Obtener un pago

GET /payments/{id}

Devuelve un pago como objeto directo. Responde 404 si no existe.

curl "https://api-pos.zelta.dev/public/v1/payments/pay_3c4d5e6f7g8h9i0j" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/payments/pay_3c4d5e6f7g8h9i0j', {
  headers: { 'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}` }
});
const data = await res.json();

Ejemplo Py

import requests

res = requests.get(
    'https://api-pos.zelta.dev/public/v1/payments/pay_3c4d5e6f7g8h9i0j',
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
data = res.json()

Problemas comunes

Código	HTTP	Causa probable
validation_error	400	Falta saleId, paymentMethod o amount, o el monto es ≤ 0.
unauthorized	401	API key ausente o inválida.
forbidden	403	La key no tiene acceso al recurso solicitado.
not_found	404	El saleId, el paymentMethod o el pago consultado no existen.
conflict	409	El monto excede el balance pendiente de la venta.
rate_limited	429	Se superó el límite de peticiones.
internal_error	500	Error interno del servidor.

Siguientes pasos

• — crea la venta de la que obtienes el saleId.
• — descubre los id de los métodos de pago.
• — consulta los reembolsos asociados a tus ventas.