Referencia de API

Base URLs

Entorno	URL
Producción	https://merchant.api.wepago.com
Staging	https://merchant.sta-api.core.wepago.com
Testing	https://merchant.testing-api.core.wepago.com

Autenticación

Authorization: Bearer {api_key}:{api_secret}

Obtén tus credenciales en comercios.wepago.com → Configuración → API.

---

POST /merchants/subscription-link

Crea un link de pago y un plan de suscripción.

Auth: requerida

Ver integración API para detalles y ejemplos completos.

Respuesta 200:

{
  "token": "V1StGXR8Z5",
  "url": "https://checkout.wepago.com/pay/V1StGXR8Z5",
  "expiresAt": "2026-04-13T12:00:00.000Z",
  "subscriptionPlanId": "01JR9H0BKMCAZ6PY1GR65B91J7"
}

---

GET /merchants/plans/{planId}/status

Consulta el estado de un plan y su última transacción. Usado para polling en tiempo real.

Auth: requerida
Parámetros: planId — subscriptionPlanId retornado al crear el link

Respuesta 200:

{
  "subscriptionPlanId": "01JR9H0BKMCAZ6PY1GR65B91J7",
  "externalReference": "orden-123",
  "plan": {
    "status": "ACTIVE",
    "amount": 49900,
    "currency": "COP",
    "description": "Suscripción mensual Premium",
    "nextChargeDate": 1744416000000
  },
  "lastTransaction": {
    "subscriptionTransactionId": "01JR9H0BKMCAZ6PY1GR65B91J6",
    "status": "APPROVED",
    "amount": 49900,
    "chargeDate": 1712534400000,
    "wompiTransactionId": "1200969-1775447756-67089"
  }
}

Respuesta 403: el plan no pertenece a tu cuenta
Respuesta 404: plan no encontrado

---

GET /merchants/subscription-plans/{id}

Obtiene un plan por ID.

Auth: requerida
Parámetros: id — subscriptionPlanId

---

GET /checkout/session/{token}

Resuelve un token de checkout (sin auth — el token corto es el secreto).

Parámetros: token — token de 10 chars generado por /merchants/subscription-link

Respuesta 200:

{
  "customer": {
    "phone": "+573001234567",
    "firstName": "Juan"
  },
  "planName": "Suscripción mensual Premium",
  "amount": 49900,
  "currency": "COP",
  "merchantName": "Tienda XYZ",
  "merchantId": "...",
  "modality": "SUBSCRIPTION",
  "expiresAt": 1712534400000,
  "allowedDomains": ["tienda.com"]
}

Respuesta 400: token expirado
Respuesta 404: token no encontrado

---

Webhooks entrantes (tu servidor ← Wepago)

Wepago envía eventos a tu Webhook URL configurada.

Header de seguridad:

X-Webhook-Signature: {hmac-sha256-hex}

Eventos:

Evento	Descripción
subscription.charge.approved	Cobro aprobado
subscription.charge.declined	Cobro rechazado
subscription.charge.error	Error técnico en el cobro
subscription.charge.voided	Cobro anulado

Ver guía de webhooks para verificación de firma y ejemplos de código.

---

Códigos de error

HTTP	Significado
400	Parámetros inválidos o sesión expirada
401	API key inválida, ausente o merchant inactivo
403	No tienes acceso a este recurso
404	Recurso no encontrado
409	Conflicto (suscripción duplicada)
500	Error interno de Wepago

---

Límites de tasa

Endpoint	Límite
POST /merchants/subscription-link	60 req/min por api_key
GET /merchants/plans/*/status	120 req/min por api_key
Otros	60 req/min por api_key