Documentación de Integración — Cubared (UltraPay)

Esta guía explica cómo integrar tu comercio para cobrar a clientes usando tarjetas virtuales Cubared. El flujo recomendado es checkout redirigido (tu cliente paga en nuestra pasarela), y opcionalmente puedes usar cobro directo server-to-server.

Datos básicos

Header X-API-KEY: keystorecubared07061269408

Formato JSON (Content-Type: application/json)

Importante: nunca pidas ni guardes el CVV del cliente en tu servidor. Para front-end usa el checkout redirigido.

1) Checkout redirigido (RECOMENDADO)

Tu backend crea una sesión de pago y redirige al cliente a la pasarela Cubared, donde el cliente introduce su tarjeta virtual. Si el pago se aprueba, se debita al usuario y se acredita saldo al comercio.

1.1 Crear sesión

POST /api/public/checkout_create.php

{
  "merchant_wallet_id": 10,
  "amount": 250.00,
  "description": "Pago de orden #A-152",
  "merchant_ref": "A-152",
  "success_url": "https://tu-sitio.com/pago-ok",
  "cancel_url": "https://tu-sitio.com/pago-cancelado",
  "webhook_url": "https://tu-sitio.com/webhooks/cubared"
}

Respuesta:

{
  "status": "success",
  "code": "OK",
  "message": "Sesión creada",
  "data": {
    "token": "4f3a...",
    "checkout_url": "https://pay.solucionescuba.com/pasarela.php?token=4f3a...",
    "expires_at": "2026-02-12 21:20:00"
  },
  "ts": 1700000000
}

1.2 Redirigir al cliente

En tu front-end, redirige al cliente a checkout_url. El cliente paga en Cubared.

1.3 Confirmación

Tienes 3 opciones (puedes usar 1 o combinar):

Webhook: si envías webhook_url, notificamos el resultado.
Success URL: al terminar, el cliente vuelve a tu sitio con parámetros status, tx_out, tx_in.
Polling: consulta el estado con checkout_status.php.

1.4 Consultar estado

GET /api/public/checkout_status.php?token=TOKEN

{
  "status": "success",
  "code": "OK",
  "message": "Estado",
  "data": {
    "token": "TOKEN",
    "status": "paid",
    "amount": 250,
    "description": "Orden #152",
    "merchant_id": 10,
    "merchant_ref": "A-152",
    "payer_id": 37,
    "mov_out_id": 201,
    "mov_in_id": 202,
    "paid_at": "2026-02-12 20:05:33"
  },
  "ts": 1700000000
}

2) Cobro directo (server-to-server)

Si tu integración es 100% backend (por ejemplo, panel interno), puedes cobrar directamente con:

POST /api/public/charge.php

{
  "merchant_wallet_id": 10,
  "card_number": "5931498383565279",
  "cvv": "321",
  "amount": 50.00,
  "description": "Pago desde API"
}

Respuesta:

{
  "status": "success",
  "code": "CHARGE_OK",
  "message": "Cobro realizado",
  "data": {
    "merchant_wallet_id": 10,
    "payer_user_id": 37,
    "amount": 50,
    "mov_out_id": 203,
    "mov_in_id": 204
  },
  "ts": 1700000000
}

3) Verificar una transacción

GET /api/public/tx_status.php?tx_id=ID

Devuelve detalles del movimiento (monto, fecha, user_id, etc.). Útil para reconciliación.

Versión: 2026-02-12 — Pasarela redirigida + tarjetas virtuales en MariaDB.

Volver Ejemplos de integración