Payment Links

Genera links de pago personalizados para cobrar a terceros sin necesidad de integración técnica.

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 de pago y completa la transacción.

Recibir Notificación

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

Genera un nuevo link de pago.

Crear Payment Link

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POSThttps://dev.backend.colurs.co/payment-links

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
currency	string	✓	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

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

Respuesta

response.json

{
"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"}

⚠️

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

🔗

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

Opciones de métodos de pago

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/payment-links/methods/options

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"PSE": true,
"CARD": true,
"BREB": false,
"UMA": false,
"BANCOLOMBIA": true,
"NEQUI": true
}

Personalizar métodos de un link

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

PATCH/payment-links/{link_uuid}/custom

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
allowed_methods	object	✓	Claves: PSE, CARD, BREB, UMA, BANCOLOMBIA, NEQUI (boolean cada una)

request.json{
"allowed_methods": {
  "PSE": true,
  "BANCOLOMBIA": true,
  "NEQUI": false
}
}

Respuesta

response.json

{
"id": 123,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"allowed_methods": { "PSE": true, "BANCOLOMBIA": true, "NEQUI": false }
}

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.

Depositar / pagar un Payment Link

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POST/payment-links/{uuid}/deposit

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
amount	number	✓	Monto a pagar
payment_method	string	✓	BANCOLOMBIA, PSE, NEQUI, etc.
payer_data	object	✕	Datos del pagador según el método

request.json{
"amount": 51190.0,
"payment_method": "PSE",
"payer_data": {}
}

Respuesta

response.json

{
"status": "PENDING",
"checkout_url": "https://checkout.colurs.me/...",
"amount": 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 un Payment Link

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/payment-links/{link_uuid}/custom

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"id": 123,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"owner": { "username": "usuario", "email":  "usuario@ejemplo.com"},
"currency": "COP",
"amount": 50000.0,
"status": "PENDING",
"link_url": "https://colurs.me/pay/550e8400-e29b-41d4-a716-446655440000",
"allowed_methods": ["BANCOLOMBIA", "PSE", "NEQUI"]
}

Link general por usuario

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/payment-links/{user_reference}/general

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"id": 456,
"uuid": "...",
"currency": "COP",
"is_general": true,
"link_url": 
"https://colurs.me/pay/..."}

Ejemplo Completo

1. Crear el Payment Link

curl -X POST https://api.colurs.co/payment-links \
  -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 la link_url devuelta (ej. https://colurs.me/pay/550e8400-e29b-41d4-a716-446655440000).

3. El pagador completa el pago

El pagador usa POST /payment-links/{uuid}/deposit o completa el flujo en la URL del link.

4. Consultar el link

curl -X GET "https://api.colurs.co/payment-links/550e8400-e29b-41d4-a716-446655440000/custom" \
  -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

Envío entre usuarios Cómo hacer un intercambio