134 lines
3.4 KiB
Markdown
134 lines
3.4 KiB
Markdown
# 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.
|