Documentación de la API

CR SINPE confirma si un pago SINPE Móvil llegó a su cuenta, por cuánto y si ya fue usado. Todas las rutas devuelven JSON y se llaman desde su servidor (nunca desde el navegador: la clave es secreta).

Base URL

https://crsinpe.stellacr.com/api/v1

Autenticación

Envíe la clave en cada solicitud, en Authorization: Bearer sk_live_... o en X-API-Key. Las claves se generan en el panel (Claves API) y se muestran una sola vez; en el servidor solo se guarda su hash SHA-256. Si pierde una clave, revóquela y genere otra.

Endpoints

Método	Ruta	Descripción
POST	/verificar	Verifica un pago y lo marca como utilizado (atómico).
GET	/verificar/{ultimos4}	Consulta sin marcar como utilizado. Acepta ?monto=.
GET	/transacciones	Lista los SINPE recibidos, más recientes primero. Filtros: estado=disponible|utilizado, desde=ISO, limit, offset.
GET	/transacciones/{referencia}	Una transacción por su referencia completa.
POST	/sincronizar	Fuerza una revisión inmediata de los buzones (normalmente cada 30 s).
POST	/ingest/sms	Registra un SINPE a partir del texto de un SMS bancario reenviado ({"texto": "...", "banco": "BAC"}). Para bancos que no notifican por correo.
POST	/sandbox/transacciones	Solo cuentas sandbox: simula un SINPE recibido ({"monto": 12500, "motivo": "ORD-1"}).

POST /verificar

Parámetros

Campo	Tipo	Req.	Descripción
ultimos4	string	Sí	Últimos 4 dígitos de la referencia del comprobante.
monto	number|string	Recomendado	Monto esperado en colones (4000 o "4,000.00"). Evita colisiones.
telefono	string	No	Teléfono de origen, para desempatar.
referencia	string	No	Referencia completa del comprobante.
referencia_externa	string	No	Su número de orden; queda guardado junto al SINPE.
consumir	boolean	No	false para solo consultar. Por defecto true.

Ejemplo

curl -X POST https://crsinpe.stellacr.com/api/v1/verificar \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -d '{"ultimos4":"8231","monto":12500,"referencia_externa":"ORD-1042"}'

Respuesta 200

{
  "verificado": true,
  "consumido": true,
  "transaccion": {
    "referencia": "2026101812345678901238231", "ultimos4": "8231",
    "monto": 12500, "moneda": "CRC", "telefono": "88887777",
    "nombre": "MARIA LOPEZ", "entidad": "Banco de Costa Rica", "motivo": "ORD-1042",
    "banco": "BCR", "fecha": "2026-10-18T15:02:00.000Z", "estado": "utilizado",
    "utilizado_en": "2026-10-18T15:03:10.000Z", "referencia_externa": "ORD-1042"
  }
}

Errores

HTTP	error	Significado
404	no_encontrado	No ha llegado ningún SINPE con esos dígitos (se buscan los últimos 30 días).
409	ya_utilizado	El comprobante ya se usó; incluye utilizado_en y referencia_externa.
409	ambiguo	Varios SINPE comparten esos 4 dígitos. Envíe monto, telefono o referencia.
422	monto_no_coincide	Existe, pero por otro monto; incluye monto_recibido.
400	parametros_invalidos	Parámetros inválidos.
401	no_autorizado	Falta la clave o es inválida.
403	cliente_inactivo	Cuenta inactiva.
429	demasiadas_solicitudes	Espere y reintente con espera exponencial.

Webhooks

Registre una URL en el panel y recibirá un POST por cada SINPE recibido (evento sinpe.recibido). Cabeceras: X-CRSinpe-Event, X-CRSinpe-Timestamp y X-CRSinpe-Signature (sha256=HMAC_SHA256(secreto, timestamp + "." + cuerpo)). Responda 2xx; si no, reintentamos con espera exponencial hasta 8 veces. El webhook solo avisa: para liberar el pedido llame a /verificar con consumir=true, así el comprobante queda marcado como usado de forma atómica.

{ "evento": "sinpe.recibido", "id_entrega": 15, "enviado_en": "2026-10-18T15:02:05.000Z",
  "transaccion": { "referencia": "...", "ultimos4": "8231", "monto": 12500, "moneda": "CRC", "motivo": "ORD-1042", "estado": "disponible", ... } }

Cómo leemos los pagos

• Conecte el buzón al que su banco envía las notificaciones (solo lectura, con contraseña de aplicación; se guarda cifrada con AES-256-GCM).
• Revisamos el buzón cada 30 s. Cada correo debe venir de un dominio bancario conocido y pasar DKIM/ARC/SPF; si no, se descarta y queda en el registro de rechazados.
• Formato con plantilla real: Banco de Costa Rica. Otros bancos usan una plantilla genérica por etiquetas; si su banco solo avisa por SMS, use /ingest/sms con una app reenviadora.
• Guardamos monto, teléfono, nombre, entidad, motivo y referencia. No pedimos credenciales bancarias y no podemos mover dinero.

Buenas prácticas

• Envíe siempre el monto: 4 dígitos solos colisionan con facilidad.
• Pida al cliente que escriba su número de orden en el "motivo" del SINPE y úselo como referencia_externa.
• Ante ambiguo, pida el teléfono o la referencia completa.
• Ante 429, espere y reintente.