Payment Links

Crea links de pago personalizados para recibir dinero de cualquier persona.

Los Payment Links permiten recibir pagos sin necesidad de integración técnica por parte del pagador.

Flujo del Payment Link

Crear el Link

Genera un Payment Link con monto fijo o variable.

Compartir el Link

Envía la URL al pagador por email, WhatsApp, etc.

Pagador Completa el Pago

El pagador selecciona método (Bancolombia, PSE, Nequi) y paga.

Recibir Notificación

El sistema actualiza el estado a PAID y acredita el balance.

Crear Payment Link

Genera un nuevo link de pago.

Endpoint

POST /api/payment_link/

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Request

Payment Link con monto fijo

{
  "currency": "COP",
  "amount": 50000.00,
  "is_general": false,
  "description": "Pago de servicio",
  "fee_mode": "payer",
  "expires_at": "2026-03-03T00:00:00Z"
}

💡

El pagador debe pagar exactamente el monto especificado.

Campos

Campo	Tipo	Requerido	Descripción
`currency`	string	✅	Código de moneda: `COP`, `USD`
`amount`	decimal	⚠️	Monto fijo (requerido si `is_general=false`)
`is_general`	boolean	✅	`true` = monto variable, `false` = monto fijo
`description`	string	❌	Descripción del pago
`fee_mode`	string	❌	`payer` o `receiver`
`expires_at`	datetime	❌	Fecha de expiración del link

Validaciones

⚠️

Para links con monto fijo (is_general=false): - El monto debe ser mayor al mínimo configurado - El monto no puede ser negativo

Respuesta

201 CREATED

{
  "id": 123,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "owner": {
    "username": "usuario",
    "email": "usuario@ejemplo.com"
  },
  "currency": "COP",
  "amount": 50000.0,
  "colurs_fee_amount": 1000.0,
  "colurs_iva_amount": 190.0,
  "total_to_pay": 51190.0,
  "status": "PENDING",
  "expires_at": "2026-03-03T00:00:00Z",
  "link_url": "https://colurs.me/pay/550e8400-e29b-41d4-a716-446655440000",
  "allowed_methods": ["BANCOLOMBIA", "PSE", "NEQUI"],
  "description": "Pago de servicio",
  "created_at": "2026-02-03T10:00:00Z"
}

🔗

Comparte la link_url con el pagador para que pueda realizar el pago.

Modos de Fee

El sistema soporta dos modos para el cobro de comisiones:

Modo	Descripción	Ejemplo (monto: $50,000, fee: $1,190)
`payer`	El usuario paga monto + fees	Usuario paga: $51,190 → Se acredita: $50,000
`receiver`	El usuario paga solo el monto	Usuario paga: $50,000 → Se acredita: $48,810

Los fees se calculan automáticamente según la configuración del perfil (CustomFees) o los fees globales.

Procesar Pago

Cuando el pagador accede al link, puede completar el pago.

Endpoint

POST /api/payment_link/{'{uuid}'}/pay/

Request

request.json

{
  "amount": 50000.0,
  "payment_method": "BANCOLOMBIA",
  "payer_email": "pagador@ejemplo.com",
  "payer_phone": "+573001234567",
  "payer_type_document": "CC",
  "payer_document": "1234567890"
}

Campos

Campo	Tipo	Requerido	Descripción
`amount`	decimal	⚠️	Monto (requerido si `is_general=true`)
`payment_method`	string	✅	`BANCOLOMBIA`, `PSE`, `NEQUI`
`payer_email`	string	⚠️	Email del pagador
`payer_phone`	string	⚠️	Teléfono del pagador
`payer_type_document`	string	⚠️	Tipo: `CC`, `CE`, `NIT`
`payer_document`	string	⚠️	Número de documento
`bank_id`	int	⚠️	ID del banco (requerido para PSE)

Los campos requeridos varían según el payment_method seleccionado.

Respuesta

200 OK

{
  "payment_link": "https://pago.colurs.co/checkout/abc123",
  "money_movement_id": "mm_xyz789",
  "total_to_pay": 51190.0
}

Estados del Payment Link

Estado	Icono	Descripción
`PENDING`	⏳	Creado, esperando pago
`ACTIVE`	🔄	Pago en proceso
`PAID`	✅	Pago completado
`EXPIRED`	⌛	Link expirado
`CANCELLED`	❌	Link cancelado

Métodos de Pago Disponibles

Método	Descripción	Genera Link
`BANCOLOMBIA`	Botón Bancolombia	✅
`PSE`	Pagos Seguros en Línea	✅
`NEQUI`	Pago desde app Nequi	❌

Consultar Payment Link

Obtiene los detalles de un Payment Link específico.

Endpoint

GET /api/payment_link/{'{uuid}'}/

Respuesta

200 OK

{
  "id": 123,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "owner": {
    "username": "usuario",
    "email": "usuario@ejemplo.com"
  },
  "currency": "COP",
  "amount": 50000.0,
  "colurs_fee_amount": 1000.0,
  "colurs_iva_amount": 190.0,
  "total_to_pay": 51190.0,
  "status": "PAID",
  "paid_at": "2026-02-03T10:30:00Z",
  "paid_amount": 51190.0,
  "link_url": "https://colurs.me/pay/550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-02-03T10:00:00Z",
  "updated_at": "2026-02-03T10:30:00Z"
}

Listar Payment Links

Obtiene todos los Payment Links del usuario.

Endpoint

GET /api/payment_link/

Parámetros Query

Parámetro	Tipo	Descripción
`status`	string	Filtrar por estado
`currency`	string	Filtrar por moneda
`page`	int	Página de resultados

Ejemplo Completo

1. Crear el Payment Link

curl -X POST https://api.colurs.co/api/payment_link/ \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "COP",
    "amount": 100000,
    "is_general": false,
    "description": "Pago mensualidad",
    "fee_mode": "payer"
}'

2. Compartir la URL

Envía al pagador:

https://colurs.me/pay/550e8400-e29b-41d4-a716-446655440000

3. El pagador completa el pago

El pagador selecciona su método de pago y completa la transacción.

4. Verificar el estado

curl -X GET "https://api.colurs.co/api/payment_link/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]"

5. Pago confirmado

Cuando status sea PAID, el balance se acredita automáticamente.

Errores Comunes

Código	Error	Descripción
`400`	`AmountRequired`	Monto requerido para links generales
`400`	`AmountMismatch`	Monto no coincide con el del link
`400`	`InvalidStatus`	El link no está en estado válido para pago
`404`	`NotFound`	Payment Link no existe

Recargas Colombia Retiros Bancarios