Developers

REST API /v1 — Charges (Fase A)

Última actualización: 27 de octubre de 2026 · Operador: KAIA-Bolivia SRL

Kaia-Pay es MCP-first. Esta REST fina es el espejo 1:1 de charges (misma lógica que MCP) para backends web/app. Los reportes siguen solo en MCP. Beta cerrada por invitación.

1. Qué es

La superficie REST /v1 replica los casos de uso de cobros del MCP merchant: crear QR, listar, consultar, anular, refrescar estado, ver límites. Mismas reglas de autenticación e idempotencia. Pensada para integraciones backend (tu web o app), no para reemplazar el flujo agentic.

Incluye: charges + estado de pago + límites.
No incluye (aún): reportes y otras tools MCP — esas quedan en MCP.

2. Base URL

https://gw.kaia-pay.pay-bo.com/v1

Producción. Todos los paths de abajo son relativos a esta base.

3. Autenticación

Usá la API key de tu comercio en la cabecera Authorization:

Authorization: Bearer pbk_live_…

Es una API key de comercio (pbk_live_…). Esta superficie no usa OAuth del Claude Directory: eso es para conectar el agente MCP, no para REST.

4. Idempotencia

Las mutaciones (POST) requieren la cabecera Idempotency-Key (8–64 caracteres). Si repetís la misma clave dentro de 24 horas, devolvemos la respuesta cacheada. En POST /charges también podés mandar idempotencyKey en el cuerpo; si falta, se usa la cabecera.

5. Envelope de respuesta

Todas las respuestas siguen este formato:

{
  "ok": true,
  "data": { … },
  "error": { "code": "…", "message": "…", "details": { … } }
}

Si ok es false, mirá error.code y error.message. Códigos HTTP típicos: 400 parámetros, 401 API key, 404 no encontrado, 409 límite o conflicto de idempotencia, 429 rate limit.

6. Límites beta

Hasta 100 Bs por cobro.
Hasta 500 Bs en 7 días móviles (o los límites configurados para tu comercio).

Consultá el consumo actual con GET /limits.

7. Endpoints

Método	Path	Descripción
POST	`/charges`	Crear cobro QR
GET	`/charges`	Listar cobros (filtros + cursor)
GET	`/charges/{chargeId}`	Obtener cobro
GET	`/charges/{chargeId}/qr`	QR del cobro (JSON o PNG)
POST	`/charges/{chargeId}/cancel`	Anular cobro
POST	`/charges/{chargeId}/refresh`	Reconsultar estado al proveedor
GET	`/payments/status`	Estado de pago (`chargeId` o `reference`)
GET	`/limits`	Límites y consumo

Especificación completa: openapi-v1-charges.yaml (OpenAPI 3.1).

8. Ejemplos curl

Reemplazá pbk_live_YOUR_KEY y los IDs por los tuyos. Nunca subas keys a repos públicos.

Crear cobro QR

curl -sS -X POST 'https://gw.kaia-pay.pay-bo.com/v1/charges' \
  -H 'Authorization: Bearer pbk_live_YOUR_KEY' \
  -H 'Idempotency-Key: demo-charge-001-abc12' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 85.00,
    "description": "Almuerzo mesa 4",
    "canal": "WEB"
  }'

Obtener cobro por id

curl -sS 'https://gw.kaia-pay.pay-bo.com/v1/charges/ch_XXXXXXXX' \
  -H 'Authorization: Bearer pbk_live_YOUR_KEY'

Estado de pago

curl -sS 'https://gw.kaia-pay.pay-bo.com/v1/payments/status?chargeId=ch_XXXXXXXX' \
  -H 'Authorization: Bearer pbk_live_YOUR_KEY'

Límites y consumo

curl -sS 'https://gw.kaia-pay.pay-bo.com/v1/limits' \
  -H 'Authorization: Bearer pbk_live_YOUR_KEY'

9. OpenAPI

Descargá el contrato: openapi-v1-charges.yaml. Podés importarlo en Postman, Insomnia o generar un cliente con openapi-generator.

10. Contacto

¿Dudas de integración? Escribinos a carlos.olivera.t@gmail.com o mirá Acerca de. Operado por KAIA-Bolivia SRL · kaialatam.com.