Balance transfers between users (Send)

P2P transfers between Colurs users: send balance to another user by username or by ID, with or without fees depending on the channel.

All endpoints require authentication with Authorization: Bearer [TOKEN] and x-api-key.

Overview

Send types

Type	Description
Classic Send	Send by recipient username. Full validations (KYC, balance, limits).
Fast Send	Send by user ID. Option to estimate costs first. Channels with or without fees.
Multiple Send	Estimate costs for sending to multiple recipients at once.

Classic Send

Create a send by specifying the recipient’s username. The system validates KYC, sufficient balance, and limits (for COP).

Flow

Validate recipient

Recipient is identified by to_user (username). Must exist and be active.

Create send

POST /send/ with amount, currency, and optional description.

Internal process

Amount (plus fees) is debited from sender, amount is credited to recipient, balance limit updated if applicable, and notification is sent.

Create send (POST)

Endpoint

POST /send/

Headers

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

Request

Field	Type	Required	Description
`to_user`	string	✅	Recipient’s username
`amount`	decimal	✅	Amount to send (must be > 0)
`currency_code`	string	❌	Currency code (default: `COP`)
`latitude`	string	❌	GPS latitude (default: `0000`)
`longitude`	string	❌	GPS longitude (default: `0000`)
`description`	string	❌	Send description

request.json

{
  "to_user": "+573001234567",
  "amount": 50000,
  "currency_code": "COP",
  "description": "Payment for service"
}

curl -X POST "https://api.colurs.co/send/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "to_user": "+573001234567",
    "amount": 50000,
    "currency_code": "COP"
  }'

Success response (200)

200 OK

{
  "to_user": "+573001234567",
  "from_user": "+573009876543",
  "created": true,
  "pk": 12345,
  "date": "2026-02-03T10:00:00Z",
  "amount": 50000.00
}

Validations

Sender active for sends (not blocked)
Origin and destination profiles exist
User with complete KYC validation
Amount greater than 0
Sufficient balance (amount + fees)
For COP: recipient must not exceed balance limit
No self-send (origin ≠ destination)

Possible errors

Code	Cause
`403`	User blocked for sends or no KYC validation
`404`	Origin or destination profile does not exist
`400`	`BALANCE_INSUFFICIENT` — Insufficient balance
`400`	`LIMIT_BALANCE` — Recipient exceeds balance limit
`400`	`USER_DOES_NOT_SAME` — Self-send attempt
`400`	`AMOUNT_NOT_ZERO` — Amount must be greater than 0
`400`	`OPERATION_INVALID` — Operation not allowed
`400`	`UNABLE_TO_CREATE_SEND` — Error creating send

List sends (GET)

Returns sends where the user is sender or recipient.

Endpoint

GET /send/

Headers

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

Response (200)

List of sends (format per ListSend serializer).

Fast Send

Send by user ID with option to estimate costs before executing. Supports channels with and without fees.

Send channels

Channel	Description
COLURS	Send between Colurs users. No fee (fee = 0).
DALE	Send with fees applied. For COP may include GMF (financial transaction tax).

Estimate Fast Send

Calculates total amount to be debited (amount + fees) and, if applicable, GMF. Does not execute the send.

Endpoint

POST /send/fast/estimate/

Headers

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

Request

Field	Type	Required	Description
`amount`	decimal	✅	Amount to send
`currency`	string	✅	Currency code (e.g. `COP`, `USD`)
`to_user`	int	❌	Recipient user ID (optional; if sent, response may include `full_name`)
`send_channel`	string	✅	Channel: `COLURS` or `DALE`
`is_for_quote`	boolean	✅	`true` for quote only, `false` to execute later

COLURS (no fees)

{
  "amount": 50000,
  "currency": "COP",
  "send_channel": "COLURS",
  "is_for_quote": true
}

With fees (DALE)

{
  "amount": 50000,
  "currency": "COP",
  "to_user": 42,
  "send_channel": "DALE",
  "is_for_quote": true
}

curl -X POST "https://api.colurs.co/send/fast/estimate/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "COP",
    "send_channel": "COLURS",
    "is_for_quote": true
  }'

Response (200)

200 OK

{
  "result": {
    "amount": 50000.00,
    "fee_amount": 1000.00,
    "fee_iva_amount": 190.00,
    "payed_amount": 51190.00,
    "gmf_amount": 200.00,
    "full_name": "Juan Pérez"
  }
}

For COLURS channel: fee_amount and fee_iva_amount are 0, payed_amount = amount. For COP in other channels, gmf_amount may be included.

Execute Fast Send

Creates the send and, if the channel is COLURS, executes the balance transfer immediately and sends a notification to the recipient.

Endpoint

POST /send/fast/

Headers

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

Request

Field	Type	Required	Description
`to_user`	int	✅	Recipient user ID
`amount`	decimal	✅	Amount to send
`currency`	string	✅	Currency code
`send_channel`	string	✅	`COLURS` or `DALE`
`ip`	string	✅	Client IP
`latitude`	string	❌	GPS latitude
`longitude`	string	❌	GPS longitude
`description`	string	❌	Send description

request.json

{
  "to_user": 42,
  "amount": 50000,
  "currency": "COP",
  "send_channel": "COLURS",
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175",
  "description": "Refund"
}

curl -X POST "https://api.colurs.co/send/fast/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "to_user": 42,
    "amount": 50000,
    "currency": "COP",
    "send_channel": "COLURS",
    "ip": "192.168.1.1"
  }'

Success response (201)

201 CREATED

{
  "message": "OK",
  "data": {
    "id": 12345,
    "currency": "COP",
    "fee_amount": 1000.00,
    "fee_iva_amount": 190.00,
    "amount": 50000.00,
    "payed_amount": 51190.00
  }
}

If the channel is COLURS, balance is transferred immediately and the recipient receives a push notification.

Possible errors

Code	Cause
`400`	`BalanceInsufficient` — Insufficient balance
`404`	`ToUserNotExist` / `ProfileDoesNotExist` — Recipient does not exist
`400`	`ToUserDoesNotAllowBlank` — to_user required on execute
`404`	Fee or configuration not found

Multiple Send (estimate)

Calculates total cost for sending to multiple recipients in one operation. Useful for payroll or bulk payments.

Endpoint

POST /send/multiple/estimate/

Headers

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

Request

Field	Type	Required	Description
`profiles`	array	✅	List of objects: `profile_id`, `amount`, `send_channel`
`currency`	string	✅	Common currency for all sends
`is_for_quote`	boolean	✅	Whether this is quote only

Example

request.json

{
  "profiles": [
    { "profile_id": 10, "amount": 100000, "send_channel": "COLURS" },
    { "profile_id": 11, "amount": 50000, "send_channel": "DALE" }
  ],
  "currency": "COP",
  "is_for_quote": true
}

Response (200)

Object with total estimated breakdown (amount, fee_amount, fee_iva_amount, payed_amount per multiple-send logic).

📊

Use the Balance endpoints to check balance before creating sends. For classic Send in COP, the recipient’s balance limit is also validated.

Swap (Balance conversion)Bank accounts