# 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

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

```json
{
  "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`

```json
{
  "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

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

### Response `200 OK`

```json
{
  "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

```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.