Colombia top-ups

Available top-up methods in Colombia: Bancolombia, PSE, Nequi, and Efecty. Endpoints to receive payments and top-ups through Bancolombia, PSE, Nequi, and bank transfer (manual approval flow).

All these endpoints require the x-api-key header for authorization.

Catalogs and estimation

Banks by country: GET /banks/ - Query: country (country code, e.g. CO, US).
Transfer account: GET /base/transfer_account - Query: country.
Estimate top-up: POST /reload/estimate - Body: amount, currency (e.g. COP), by_pse (depending on method).

General flow

Create payer

Generate payment link

Create the payment link based on method: Bancolombia, PSE, or Nequi.

Redirect user

The user completes payment on the banking platform.

Check status

Check payment status with GET /api/reload/r2p/status/{id}/.

Receive confirmation

The system notifies when payment is completed successfully.

Registers the data of the person who will make the payment.

Create Payer

Authorizations

The x-api-key header is required for authorization.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/counterparty/

Required Headers

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

Request Body

Field	Type	Required	Description
fullname	string	✓	Full payer name
id_type	string	✕	cc, ce, nit (default: cc)
id_number	string	✓	Document number
phone	string	✓	Phone with country code
email	string	✓	Payer email

request.json{
"fullname": "Juan Pérez",
"id_type": "cc",
"id_number": "1234567890",
"phone": "+573001234567",
"email": "juan@ejemplo.com"
}

Response

response.json

{
"id": "cp_vKXigiCryI",
"fullname": "Juan Pérez",
"id_type": "cc",
"id_number": 
"1234567890"}

💡

Save payer `id` to use in the next endpoints.

Generates a payment link for Bancolombia Button.

Bancolombia Button

Authorizations

The x-api-key header is required for authorization.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/bancolombia/

Required Headers

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

Request Body

Field	Type	Required	Description
counterparty_id	string	✓	Created payer ID
amount	decimal	✓	Amount in COP (minimum 1,000)
external_id	string	✓	Unique transaction ID
description_to_payer	string	✓	Customer-facing description (max 255)
description_to_payee	string	✓	Internal description (max 255)
redirect_url	string	✓	Post-payment redirect URL
fee_mode	string	✕	payer or receiver (default: payer)

request.json{
"counterparty_id": "cp_vKXigiCryI",
"amount": 50000.00,
"external_id": "ORDER_123456",
"description_to_payer": "Recarga Colurs - 50,000 COP",
"description_to_payee": "Recarga de Juan Pérez",
"redirect_url": "https://app.colurs.co/payment/success",
"fee_mode": "payer"
}

cURL Example

curl -X POST https://api.colurs.co/api/reload/r2p/bancolombia/ \
-H "Content-Type: application/json" \
-H "x-api-key: [API_KEY]" \
-d '{
  "counterparty_id": "cp_vKXigiCryI",
  "amount": 50000.00,
  "external_id": "ORDER_123456",
  "description_to_payer": "Recarga Colurs - 50,000 COP",
  "description_to_payee": "Recarga de Juan Pérez",
  "redirect_url": "https://app.colurs.co/payment/success",
  "fee_mode": "payer"
}'

Response

response.json

{
"money_movement_id": "mm_gaO1SrCBN92BT5",
"type": "bancolombia",
"status": "initiated",
"payment_link": "https://pago.colurs.co/checkout/_VIwgp1lQI5",
"tracking_key": "917707780",
"amount": 50000.0,
"currency": "COP",
"external_id": "ORDER_123456",
"created_at": "2025-11-14T15:44:39Z",
"fee_breakdown": {
  "reload_amount": "50000.00",
  "fee_colurs": "1000.00",
  "fee_iva": "190.00",
  "total_fee": "1190.00",
  "total_to_pay": "51190.00",
  "fee_mode": "payer",
  "fee_percentage": "2.00",
  "iva_percentage": 
"19.00"}
}

🔗

Redirect the user to `payment_link` to complete payment.

Generates a payment link for PSE.

PSE

Authorizations

The x-api-key header is required for authorization.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/pse/

Required Headers

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

Request Body

Field	Type	Required	Description
counterparty_id	string	✓	Payer ID
amount_cop	decimal	✓	Amount in COP
external_id	string	✓	Unique transaction ID
description_to_payer	string	✓	Customer-facing description
description_to_payee	string	✓	Internal description
redirect_url	string	✓	Redirect URL
financial_institution_code	string	✓	PSE bank code
fee_mode	string	✕	payer or receiver

request.json{
"counterparty_id": "cp_vKXigiCryI",
"amount_cop": 100000.00,
"external_id": "ORDER_123457",
"description_to_payer": "Recarga Colurs - 100,000 COP",
"description_to_payee": "Recarga PSE de Juan Pérez",
"redirect_url": "https://app.colurs.co/payment/success",
"financial_institution_code": "1007",
"fee_mode": "payer"
}

Response

response.json

{
"money_movement_id": "mm_tjfcYXguVwrNWj",
"type": "pse",
"status": "initiated",
"payment_link": "https://pago.colurs.co/pse/mm_tjfcYXguVwrNWj",
"tracking_key": "PSE_917707781",
"amount": 100000.0,
"currency": "COP",
"external_id": "ORDER_123457",
"financial_institution_code": "1007",
"created_at": "2025-11-14T15:44:40Z",
"fee_breakdown": {
  "reload_amount": "100000.00",
  "fee_colurs": "2000.00",
  "fee_iva": "380.00",
  "total_fee": "2380.00",
  "total_to_pay": "102380.00",
  "fee_mode": "payer",
  "fee_percentage": "2.00",
  "iva_percentage": 
"19.00"}
}

Generates a payment request for Nequi.

Nequi

Authorizations

The x-api-key header is required for authorization.

Endpoint

POSThttps://api.colurs.co/api/reload/r2p/nequi/

Required Headers

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

Request Body

Field	Type	Required	Description
counterparty_id	string	✓	Payer ID
amount	decimal	✓	Amount in COP
external_id	string	✓	Unique transaction ID
description_to_payer	string	✓	Customer-facing description
description_to_payee	string	✓	Internal description
redirect_url	string	✓	Redirect URL
fee_mode	string	✕	payer or receiver

request.json{
"counterparty_id": "cp_vKXigiCryI",
"amount": 25000.0,
"external_id": "ORDER_123458",
"description_to_payer": "Recarga Colurs - 25,000 COP",
"description_to_payee": "Recarga Nequi de Juan Pérez",
"redirect_url": "https://app.colurs.co/payment/success",
"fee_mode": "payer"
}

Response

response.json

{
"money_movement_id": "mm_abc123def456",
"type": "nequi",
"status": "initiated",
"payment_link": null,
"tracking_key": "NEQUI_12345",
"amount": 25000.0,
"currency": "COP",
"external_id": "ORDER_123458",
"created_at": "2025-11-14T15:44:41Z",
"note": "User must complete payment from the Nequi app",
"fee_breakdown": {
  "reload_amount": "25000.00",
  "fee_colurs": "500.00",
  "fee_iva": "95.00",
  "total_fee": "595.00",
  "total_to_pay": "25595.00",
  "fee_mode": 
"payer"}
}

📱

**Important:** Nequi does NOT generate a `payment_link`. The user must complete payment from their Nequi app using `tracking_key`.

Bank transfer top-up (BANK_TRANSFER)

Manual top-up method: the user uploads bank transfer evidence and an operator reviews it and approves or rejects crediting balance. Unlike Bancolombia, PSE, and Nequi, there is no automatic webhook.

👤

Approval or rejection is done from the operator panel (POST /panel/reload/). Only superusers or operators can use that endpoint.

Flow

User creates top-up

Send POST /reload/create with reload_method: BANK_TRANSFER, amount, currency, evidence (proof URL), source bank, and destination bank.

Backend creates record

The top-up stays in Created state (pending approval). Fees are calculated at creation.

Operator reviews evidence

From the panel, the operator reviews evidence (image or PDF).

Operator approves or rejects

POST /panel/reload with reload_id and status: APPROVED or REJECTED.

If approved

The system credits user balance, records fees (Colurs, VAT), and referral commission if applicable.

Step 1: Create top-up with evidence (user)

The user indicates they made a bank transfer top-up and attaches the evidence URL.

Create BANK_TRANSFER top-up

Authorizations

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

Endpoint

POSThttps://api.colurs.co/reload/create

Required Headers

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

Request Body

Field	Type	Required	Description
reload_method	string	✓	BANK_TRANSFER
currency	string	✓	COP or USD
amount	decimal	✓	Top-up amount (up to 20 digits, 2 decimals)
evidence	string	✓	Evidence URL (image or PDF)
bank_id	int	✓	Source bank ID
target_bank_id	int	✓	Destination bank ID (Colurs account)
ip	string	✓	Client IP
latitude	string	✓	Latitude GPS
longitude	string	✓	Longitude GPS
payer_email	string	✕	Payer email
payer_phone	string	✕	Payer phone
payer_type_document	string	✕	CC, CE, TI, NIT, etc.
payer_document	string	✕	Document number
account_name	string	✕	Source account name

request.json{
"reload_method": "BANK_TRANSFER",
"currency": "COP",
"amount": 500000,
"evidence": "https://storage.colurs.co/evidence/recarga-123.pdf",
"bank_id": 1,
"target_bank_id": 2,
"ip": "192.168.1.1",
"latitude": "4.60971",
"longitude": "-74.08175",
"payer_email": "pagador@ejemplo.com",
"account_name": "Juan Pérez"
}

cURL Example

curl -X POST "https://api.colurs.co/reload/create" \
-H "Authorization: Bearer [TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{
  "reload_method": "BANK_TRANSFER",
  "currency": "COP",
  "amount": 500000,
  "evidence": "https://storage.colurs.co/evidence/recarga-123.pdf",
  "bank_id": 1,
  "target_bank_id": 2,
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175"
}'

Response

response.json

{
"message": "OK",
"data": {
  "id": 316,
  "state": "Creado",
  "owner": "colurs@colurs.io",
  "reload_method": "BANK_TRANSFER",
  "currency": "COP",
  "bank_name": "BANCO_BAN100",
  "transfer_account": "BANCO_BBVA",
  "payed_amount": "989.00",
  "evidence": "url-to-evidence",
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175",
  "checkout": null
}
}

📎

`evidence` must be an accessible **URL** to payment proof (image or PDF uploaded to your storage).

The top-up remains in Created status until an operator approves or rejects it.

Modos de Fee

The system supports two fee charging modes:

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 based on profile configuration (CustomFees) or global fees.

Common errors

Code	Error	Description
`400`	Validation failed	Invalid request data
`404`	Not found	Money Movement does not exist
`500`	Internal error	Processing error

How to fund an account Mexico deposits (MXN)