Integración para comercios

Datos de conexión

Base URL: https://pay.solucionescuba.com

API Key: keystorecubared07061269408

Esta API key es pública. Aun así, se recomienda que el llamado a la API se haga desde tu backend para controlar la lógica de pedidos. Cubared es un proyecto con amor; no lucramos con la integración.

¿Dónde declaro mi “correo de cobro”?

En cada cobro debes enviar merchant_wallet_id con el correo (email) de tu cuenta Cubared donde quieres recibir el dinero. No existe un “panel de comercios” aparte: tu cuenta Cubared es la misma que usas para cobrar.

{
  "merchant_wallet_id": "tu-correo@dominio.com"
}

Si no tienes cuenta, crea una en Cubared y usa ese email aquí. (También se admite teléfono, pero recomendamos email.)

Flujo recomendado: Checkout redirigido (✅)

Este flujo evita que tu comercio toque datos de tarjetas. Solo generas un checkout y rediriges al cliente al enlace de pago. Cuando el pago termina, Cubared muestra un “Pago completado” y el cliente puede volver a tu web con un botón.

1) Crea tu pedido en tu sistema

Genera un identificador único, por ejemplo ORDER-20260212-0001. Ese valor lo envías como merchant_ref.

2) Tu backend crea el checkout en Cubared

Endpoint: POST /api/public/checkout_create.php
Header requerido: X-API-KEY

Campo	Requerido	Descripción
`amount`	Sí	Monto a cobrar (número). Ej: `120` o `120.50`.
`merchant_wallet_id`	Sí	Tu email (cuenta Cubared) donde recibes el pago.
`currency`	No	Moneda. Por defecto `CUP`.
`description`	No	Descripción visible del cobro (producto/servicio).
`merchant_ref`	No	ID de tu pedido/orden/factura.
`success_url`	No	URL a la que el cliente vuelve desde la pantalla de “Pago completado”.
`cancel_url`	No	URL para volver si el cliente cancela.
`webhook_url`	No	URL de tu backend para notificaciones automáticas.
`expires_in_minutes`	No	Minutos de expiración (por defecto 20).

Ejemplo (cURL):

curl -X POST "https://pay.solucionescuba.com/api/public/checkout_create.php" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: keystorecubared07061269408" \
  -d '{
    "amount": 120,
    "currency": "CUP",
    "merchant_wallet_id": "tu-correo@dominio.com",
    "description": "Compra en MiTienda",
    "merchant_ref": "ORDER-20260212-0001",
    "success_url": "https://tusitio.com/pago-exitoso?order=ORDER-20260212-0001",
    "cancel_url": "https://tusitio.com/carrito",
    "webhook_url": "https://tusitio.com/webhooks/cubared"
  }'

Respuesta (ejemplo):

{
  "status": "success",
  "data": {
    "token": "...",
    "checkout_url": "https://pay.solucionescuba.com/pasarela.php?token=...",
    "expires_at": "YYYY-MM-DD HH:MM:SS"
  }
}

3) Redirige al cliente a `checkout_url`

En tu frontend (o backend), envía al usuario al enlace devuelto por la API. Ahí el cliente completa el pago en Cubared.

4) Confirma el pago antes de entregar el producto

Para confirmar, usa el token del checkout: GET /api/public/checkout_status.php?token=.... Considera el pedido “pagado” solo si el estado es paid.

curl "https://pay.solucionescuba.com/api/public/checkout_status.php?token=TU_TOKEN" \
  -H "X-API-KEY: keystorecubared07061269408"

5) (Opcional) Webhook para confirmación automática

Si envías webhook_url, Cubared intentará notificarte con un POST JSON. Recomendación: cuando recibas el webhook, vuelve a consultar checkout_status por seguridad y para sincronizar tu pedido.

// Ejemplo de payload (puede variar)
{
  "token": "...",
  "status": "paid",
  "amount": 120,
  "currency": "CUP",
  "merchant_ref": "ORDER-20260212-0001"
}

Endpoints útiles

/api/public/checkout_status.php?token=... — estado del checkout
/api/public/tx_status.php?tx_id=... — estado de una transacción (si lo necesitas)