Payment Links
Create personalized payment links to receive money from anyone.
Payment Links allow you to receive payments without requiring technical integration from the payer.
Payment Link Flow
Create the Link
Generate a Payment Link with fixed or variable amount.
Share the Link
Send the URL to the payer via email, WhatsApp, etc.
Payer Completes Payment
Payer selects method (Bancolombia, PSE, Nequi) and pays.
Receive Notification
System updates status to PAID and credits the balance.
Create Payment Link
Generate a new payment link.
Endpoint
POST /api/payment_link/Headers
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]Request
Payment Link with fixed amount
{
"currency": "COP",
"amount": 50000.00,
"is_general": false,
"description": "Service payment",
"fee_mode": "payer",
"expires_at": "2026-03-03T00:00:00Z"
}💡
The payer must pay exactly the specified amount.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | ✅ | Currency code: COP, USD |
amount | decimal | ⚠️ | Fixed amount (required if is_general=false) |
is_general | boolean | ✅ | true = variable amount, false = fixed amount |
description | string | ❌ | Payment description |
fee_mode | string | ❌ | payer or receiver |
expires_at | datetime | ❌ | Link expiration date |
Validations
⚠️
For fixed amount links (is_general=false):
- Amount must be greater than configured minimum
- Amount cannot be negative
Response
201 CREATED
{
"id": 123,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"owner": {
"username": "user",
"email": "user@example.com"
},
"currency": "COP",
"amount": 50000.00,
"colurs_fee_amount": 1000.00,
"colurs_iva_amount": 190.00,
"total_to_pay": 51190.00,
"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": "Service payment",
"created_at": "2026-02-03T10:00:00Z"
}🔗
Share the link_url with the payer so they can make the payment.
Process Payment
When the payer accesses the link, they can complete the payment.
Endpoint
POST /api/payment_link/{'{uuid}'}/pay/Request
request.json
{
"amount": 50000.00,
"payment_method": "BANCOLOMBIA",
"payer_email": "payer@example.com",
"payer_phone": "+573001234567",
"payer_type_document": "CC",
"payer_document": "1234567890"
}Fields
| Field | Type | Required | Description |
|---|---|---|---|
amount | decimal | ⚠️ | Amount (required if is_general=true) |
payment_method | string | ✅ | BANCOLOMBIA, PSE, NEQUI |
payer_email | string | ⚠️ | Payer’s email |
payer_phone | string | ⚠️ | Payer’s phone |
payer_type_document | string | ⚠️ | Type: CC, CE, NIT |
payer_document | string | ⚠️ | Document number |
bank_id | int | ⚠️ | Bank ID (required for PSE) |
Required fields vary based on selected payment_method.
Response
200 OK
{
"payment_link": "https://payment.colurs.co/checkout/abc123",
"money_movement_id": "mm_xyz789",
"total_to_pay": 51190.00
}Payment Link Statuses
| Status | Icon | Description |
|---|---|---|
PENDING | ⏳ | Created, awaiting payment |
ACTIVE | 🔄 | Payment in progress |
PAID | ✅ | Payment completed |
EXPIRED | ⌛ | Link expired |
CANCELLED | ❌ | Link cancelled |
Available Payment Methods
| Method | Description | Generates Link |
|---|---|---|
BANCOLOMBIA | Bancolombia Button | ✅ |
PSE | Pagos Seguros en Línea | ✅ |
NEQUI | Payment from Nequi app | ❌ |
Get Payment Link
Get details of a specific Payment Link.
Endpoint
GET /api/payment_link/{'{uuid}'}/Response
200 OK
{
"id": 123,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"owner": {
"username": "user",
"email": "user@example.com"
},
"currency": "COP",
"amount": 50000.00,
"colurs_fee_amount": 1000.00,
"colurs_iva_amount": 190.00,
"total_to_pay": 51190.00,
"status": "PAID",
"paid_at": "2026-02-03T10:30:00Z",
"paid_amount": 51190.00,
"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"
}List Payment Links
Get all user’s Payment Links.
Endpoint
GET /api/payment_link/Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status |
currency | string | Filter by currency |
page | int | Results page |
Complete Example
1. Create the 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": "Monthly payment",
"fee_mode": "payer"
}'2. Share the URL
Send to payer:
https://colurs.me/pay/550e8400-e29b-41d4-a716-4466554400003. Payer completes payment
Payer selects their payment method and completes the transaction.
4. Verify status
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. Payment confirmed
When status is PAID, balance is automatically credited.
Common Errors
| Code | Error | Description |
|---|---|---|
400 | AmountRequired | Amount required for general links |
400 | AmountMismatch | Amount doesn’t match link amount |
400 | InvalidStatus | Link not in valid status for payment |
404 | NotFound | Payment Link doesn’t exist |