Payment Links

Generate custom payment links to charge third parties without technical integration.

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.

Send the URL to the payer by email, WhatsApp, etc.

Payer completes payment

The payer selects payment method and completes the transaction.

Receive notification

The system updates status to PAID and credits balance.

Generate a new payment link.

Create Payment Link

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

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

Required Headers

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

Request Body

Field	Type	Required	Description
currency	string	✓	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

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

Response

response.json

{
"id": 123,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"owner": {
  "username": "user",
  "email": 
"user@example.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": "Service payment",
"created_at": 
"2026-02-03T10:00:00Z"}

⚠️

For fixed amount links (`is_general=false`): amount must be greater than configured minimum and cannot be negative.

🔗

Share `link_url` with the payer so they can complete payment.

Payment method options

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/payment-links/methods/options

Required Headers

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

Response

response.json

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

Customize methods for a link

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

PATCH/payment-links/{link_uuid}/custom

Required Headers

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

Request Body

Field	Type	Required	Description
allowed_methods	object	✓	Keys: PSE, CARD, BREB, UMA, BANCOLOMBIA, NEQUI (boolean each)

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

Response

response.json

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

Fee modes

The system supports two modes for charging fees:

Mode	Description	Example (amount: $50,000, fee: $1,190)
`payer`	User pays amount + fees	User pays: $51,190 -> Credited: $50,000
`receiver`	User pays only amount	User pays: $50,000 -> Credited: $48,810

Fees are calculated automatically according to profile configuration (CustomFees) or global fees.

Deposit / pay a Payment Link

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

POST/payment-links/{uuid}/deposit

Required Headers

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

Request Body

Field	Type	Required	Description
amount	number	✓	Amount to pay
payment_method	string	✓	BANCOLOMBIA, PSE, NEQUI, etc.
payer_data	object	✕	Payer data according to method

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

Response

response.json

{
"status": "PENDING",
"checkout_url": "https://checkout.colurs.me/...",
"amount": 51190.0
}

Payment Link statuses

Status	Icon	Description
`PENDING`	⏳	Created, waiting payment
`ACTIVE`	🔄	Payment in progress
`PAID`	✅	Payment completed
`EXPIRED`	⌛	Link expired
`CANCELLED`	❌	Link canceled

Available payment methods

Method	Description	Generates link
`BANCOLOMBIA`	Bancolombia Button	✅
`PSE`	Online secure payments	✅
`NEQUI`	Payment from Nequi app	❌

Get a Payment Link

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/payment-links/{link_uuid}/custom

Required Headers

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

Response

response.json

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

General link by user

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

GET/payment-links/{user_reference}/general

Required Headers

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

Response

response.json

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

Full example

1. Create the 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": "Monthly payment",
    "fee_mode": "payer"
}'

Send returned link_url to payer (e.g. https://colurs.me/pay/550e8400-e29b-41d4-a716-446655440000).

3. Payer completes payment

Payer uses POST /payment-links/{uuid}/deposit or completes flow at link URL.

4. Check the 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. Payment confirmed

When status becomes PAID, balance is credited automatically.

Common errors

Code	Error	Description
`400`	`AmountRequired`	Amount required for general links
`400`	`AmountMismatch`	Amount does not match link amount
`400`	`InvalidStatus`	Link is not in a valid status for payment
`404`	`NotFound`	Payment Link does not exist

User-to-user transfer How to make an exchange

Payment Links

Payment Link flow

Create the link

Share the link

Payer completes payment

Receive notification

Create Payment Link

Authorizations

Endpoint

Required Headers

Request Body

Response

Payment method options

Authorizations

Endpoint

Required Headers

Response

Customize methods for a link

Authorizations

Endpoint

Required Headers

Request Body

Response

Fee modes

Deposit / pay a Payment Link

Authorizations

Endpoint

Required Headers

Request Body

Response

Payment Link statuses

Available payment methods

Get a Payment Link

Authorizations

Endpoint

Required Headers

Response

General link by user

Authorizations

Endpoint

Required Headers

Response

Full example

1. Create the Payment Link

2. Share the URL

3. Payer completes payment

4. Check the link

5. Payment confirmed

Common errors