API operativa

Referencia de la API

La API de PagoVeloz sigue las convenciones REST. Acepta cuerpos de petición JSON, devuelve respuestas JSON y usa códigos de estado HTTP estándar. Base URL: https://api.pago-veloz.com/v1

Primeros pasos

Para comenzar a integrar la API de PagoVeloz necesitas una clave de API. Puedes generar tus claves desde el panel de control en Configuración → API Keys.

ℹ

Utiliza las claves de entorno sandbox durante el desarrollo. Las claves de producción solo deben usarse en servidores seguros, nunca en código cliente.

Instalación del SDK

Node.js Python PHP

# npm
npm install @pagoveloz/node

# yarn
yarn add @pagoveloz/node

Primera petición

const PagoVeloz = require('@pagoveloz/node');

const pv = new PagoVeloz('pk_live_TU_CLAVE_AQUI');

const pago = await pv.pagos.crear({
  monto:    15000,
  moneda:   'CLP',
  metodo:   'tarjeta',
  cliente:  'cli_abc123',
  metadata: { pedido_id: 'ord_9821' }
});

console.log(pago.id); // pay_xK8mN2qP...

Autenticación

La API usa claves de API tipo Bearer. Incluye tu clave en el header Authorization de cada petición.

Bearer Token

Prefija tu clave con Bearer. Las claves de producción empiezan con pk_live_ y las de sandbox con pk_test_.

Authorization: Bearer pk_live_xK8mN2qP4rT7vW1yZ3aB6cD

⚠

Las claves de producción tienen acceso completo. Nunca las expongas en código frontend, repositorios públicos ni variables de entorno no cifradas.

Errores y códigos de estado

PagoVeloz utiliza los códigos de estado HTTP estándar. Los errores devuelven un objeto JSON con el detalle.

Código	Significado	Descripción
200	OK	Petición exitosa.
201	Created	Recurso creado correctamente.
400	Bad Request	Parámetros inválidos o faltantes.
401	Unauthorized	Clave de API inválida o expirada.
402	Payment Required	El pago fue rechazado por el emisor.
422	Unprocessable	Error de validación de negocio.
429	Too Many Requests	Límite de peticiones superado.
500	Server Error	Error interno. Reintenta con backoff.

Estructura de error

{
  "error": {
    "codigo":   "tarjeta_rechazada",
    "mensaje":  "La tarjeta fue declinada por el banco emisor.",
    "campo":    null,
    "doc_url":  "https://docs.pago-veloz.com/errores/tarjeta_rechazada",
    "request_id": "req_7mKpN2xQ"
  }
}

Rate limiting

Los límites se aplican por clave de API. La respuesta incluye headers informativos en cada petición.

Header	Descripción
X-RateLimit-Limit	Peticiones permitidas por ventana (1 minuto).
X-RateLimit-Remaining	Peticiones disponibles en la ventana actual.
X-RateLimit-Reset	Unix timestamp de reset de la ventana.

El límite por defecto es 300 peticiones/minuto para producción y 60/minuto para sandbox. Contacta a soporte para aumentar los límites.

Entornos

Entorno	Base URL	Prefijo clave
Producción	https://api.pago-veloz.com/v1	pk_live_
Sandbox	https://sandbox.pago-veloz.com/v1	pk_test_

✓

En sandbox puedes simular distintos escenarios usando números de tarjeta de prueba. Consulta la guía de testing para la lista completa.

Pagos

POST /v1/pagos Crear un nuevo pago

Crea un nuevo objeto de pago. Puede quedar en estado pendiente, procesando o aprobado dependiendo del flujo de autenticación.

Parámetros del cuerpo

Parámetro	Tipo	Requerido	Descripción
monto	integer	requerido	Monto en centavos o unidad mínima de la moneda. Para CLP usar pesos enteros.
moneda	string	requerido	Código ISO 4217. Ej: `CLP`, `USD`, `MXN`.
metodo	string	requerido	`tarjeta`, `transferencia`, `wallet`.
cliente	string	opcional	ID de cliente existente (`cli_...`). Requerido para pagos recurrentes.
descripcion	string	opcional	Descripción visible en el estado de cuenta del cliente. Máx. 255 caracteres.
captura_automatica	boolean	opcional	Si `false`, el pago queda preautorizado hasta captura manual. Default: `true`.
metadata	object	opcional	Pares clave-valor libres. Máx. 20 claves, 500 bytes por valor.

Ejemplo de petición

curl -X POST https://api.pago-veloz.com/v1/pagos \
  -H "Authorization: Bearer pk_live_xK8mN2..." \
  -H "Content-Type: application/json" \
  -d '{
    "monto":             25990,
    "moneda":            "CLP",
    "metodo":            "tarjeta",
    "cliente":           "cli_abc123",
    "descripcion":       "Suscripción mensual Plan Pro",
    "captura_automatica": true,
    "metadata": {
      "pedido_id": "ord_9821",
      "canal":     "web"
    }
  }'

Respuesta

201 Created

{
  "id":                 "pay_xK8mN2qP4rT7vW",
  "objeto":             "pago",
  "monto":              25990,
  "moneda":             "CLP",
  "estado":             "aprobado",
  "metodo":             "tarjeta",
  "cliente":            "cli_abc123",
  "descripcion":        "Suscripción mensual Plan Pro",
  "capturado":          true,
  "codigo_autorizacion":"AUT-441829",
  "creado_en":          1702915200,
  "metadata": {
    "pedido_id": "ord_9821",
    "canal":     "web"
  }
}

GET /v1/pagos/:id Obtener un pago por ID

Devuelve el objeto pago completo asociado al ID proporcionado.

Parámetros de ruta

Parámetro	Tipo	Descripción
id	string	ID del pago. Formato: `pay_...`

curl https://api.pago-veloz.com/v1/pagos/pay_xK8mN2qP4rT7vW \
  -H "Authorization: Bearer pk_live_xK8mN2..."

GET /v1/pagos Listar pagos con filtros

Devuelve una lista paginada de pagos en orden cronológico inverso.

Query params

Parámetro	Tipo	Default	Descripción
limit	integer	20	Resultados por página. Máx. 100.
cursor	string	—	Cursor de paginación (del campo `next_cursor` de la respuesta anterior).
estado	string	—	Filtrar por estado: `aprobado`, `rechazado`, `pendiente`.
cliente	string	—	Filtrar por ID de cliente.
desde	integer	—	Unix timestamp inicio del rango.
hasta	integer	—	Unix timestamp fin del rango.

POST /v1/pagos/:id/capturar Capturar pago preautorizado

Captura un pago que fue creado con captura_automatica: false. El monto capturado puede ser igual o menor al autorizado.

Parámetro	Tipo	Descripción
monto	integer	Monto a capturar. Si se omite, captura el monto total autorizado.

DEL /v1/pagos/:id Cancelar pago pendiente

Reembolsos

POST /v1/pagos/:id/reembolsos Crear reembolso total o parcial

Emite un reembolso sobre un pago aprobado. Puedes emitir múltiples reembolsos parciales siempre que la suma no supere el monto original.

Parámetro	Tipo	Requerido	Descripción
monto	integer	opcional	Si se omite, reembolsa el total. Si se especifica, reembolso parcial.
motivo	string	opcional	`duplicado`, `fraudulento`, `solicitado_por_cliente`.

curl -X POST https://api.pago-veloz.com/v1/pagos/pay_xK8mN2qP/reembolsos \
  -H "Authorization: Bearer pk_live_xK8mN2..." \
  -H "Content-Type: application/json" \
  -d '{
    "monto":  5000,
    "motivo": "solicitado_por_cliente"
  }'

GET /v1/pagos/:id/reembolsos/:reembolso_id Obtener reembolso

Clientes

POST /v1/clientes Crear cliente

Crea un objeto cliente para asociar pagos, métodos de pago guardados y suscripciones.

Parámetro	Tipo	Requerido	Descripción
email	string	requerido	Email único del cliente.
nombre	string	opcional	Nombre completo.
telefono	string	opcional	Formato E.164. Ej: `+56912345678`.
metadata	object	opcional	Datos adicionales libres.

PUT /v1/clientes/:id Actualizar cliente

GET /v1/clientes/:id Obtener cliente

Webhooks

Los webhooks notifican a tu servidor cuando ocurre un evento en PagoVeloz. Regístralos desde el panel en Configuración → Webhooks.

Eventos disponibles

Evento	Descripción
pago.aprobado	El pago fue autorizado y capturado exitosamente.
pago.rechazado	El emisor rechazó la transacción.
pago.reembolsado	Se procesó un reembolso total o parcial.
pago.disputa.abierta	El titular abrió una disputa (chargeback).
pago.disputa.resuelta	La disputa fue resuelta por el banco.
cliente.creado	Nuevo cliente registrado en la plataforma.

Verificar la firma

Cada webhook incluye el header X-PagoVeloz-Signature con un HMAC-SHA256 del cuerpo firmado con tu secreto de webhook.

const crypto = require('crypto');

function verificarFirma(payload, header, secreto) {
  const firma = crypto
    .createHmac('sha256', secreto)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(firma),
    Buffer.from(header)
  );
}

⚠

Usa siempre timingSafeEqual para comparar las firmas. La comparación directa de strings es vulnerable a ataques de timing.