soft_usite/BOLD_ENLACES_PAGO.md

Bold — Solicitar y consumir enlaces de pago

Requisitos previos

Tener configurada la pasarela Bold con una API key activa. Se gestiona desde:

POST /pasarelas/bold/save

---

1. Crear un enlace de pago

Endpoint: POST /pasarelas/bold/crear-link
Autenticación: requerida (sesión o token)

Request

POST /pasarelas/bold/crear-link
Content-Type: application/json
Authorization: <token>

{
  "total_amount": 50000,
  "description": "Renovación plan básico",
  "reference": "REF-UNICA-001",
  "payer_email": "cliente@correo.com",
  "callback_url": "https://tudominio.com/pago-resultado"
}

Campo	Tipo	Requerido	Descripción
total_amount	int64	✅	Monto en COP sin centavos (ej. 50000 = $50.000)
description	string	✅	Descripción visible en el checkout Bold
reference	string	✅	Referencia única por pago (usada para identificarlo)
payer_email	string	❌	Email del pagador (prellenado en el checkout)
callback_url	string	❌	URL de redirección tras el pago (override del config)

Response 200 OK

{
  "payment_link": "pl_abc123xyz",
  "url": "https://checkout.bold.co/payment/pl_abc123xyz"
}

• url → redirige al usuario a esta URL para que complete el pago.
• payment_link → ID del link, guárdalo para consultar su estado después.

---

2. Consultar el estado de un enlace

Endpoint: GET /pasarelas/bold/link/:linkID
Autenticación: requerida

GET /pasarelas/bold/link/pl_abc123xyz
Authorization: <token>

Response 200 OK

{
  "data": "{ ...payload crudo de la API de Bold... }"
}

---

3. Webhook (notificación automática de Bold)

Bold notifica los pagos a:

POST /webhooks/bold

Esta ruta es pública (sin autenticación). Bold la llama automáticamente al completarse un pago. El sistema valida la firma HMAC-SHA256 y registra el evento en bold_webhook_log.

---

4. Usar el servicio directamente en Go

import (
    "github.com/sujit-baniya/fiber-boilerplate/pkg/models"
    "github.com/sujit-baniya/fiber-boilerplate/pkg/services"
)

cfg, err := models.GetBoldConfig()
if err != nil {
    // sin configuración activa
}

result, err := services.CreateBoldPaymentLink(cfg, services.BoldPaymentLinkRequest{
    AmountType: "CLOSE",
    Amount: services.BoldAmountField{
        Currency:    "COP",
        TotalAmount: 50000,
    },
    Description: "Renovación plan X",
    Reference:   "REF-UNICA-001",
    PayerEmail:  "cliente@correo.com",
})
if err != nil {
    // error de la API Bold
}

checkoutURL := result.Payload.URL
linkID      := result.Payload.PaymentLink

---

5. Polling automático

El sistema verifica pagos pendientes cada 15 minutos mediante un cron job (VerificarPagosBoldPendientes). Esto cubre los casos donde el webhook no llega.

---

Notas

• reference debe ser única por transacción. Reutilizarla puede causar conflictos al resolver el pago.
• El modo activo (test / production) y las API keys se configuran en la tabla bold_config. Solo un registro puede estar activo a la vez.
• En modo test la secret_key es cadena vacía según la documentación oficial de Bold.