Deposits Colombia

Endpoints to receive payments and deposits in Colombia via Bancolombia, PSE, Nequi, and bank transfer (the latter with manual approval).

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

General Flow

Create Payer

Generate Payment Link

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

Redirect User

User completes payment on the banking platform.

Check Status

Verify payment status with GET /api/reload/status/{id}/.

Receive Confirmation

System notifies when payment completes successfully.

Create Payer

Endpoint

POST /api/reload/counterparty/

Headers

Content-Type: application/json
x-api-key: [API_KEY]

Request

request.json

{
  "fullname": "John Doe",
  "id_type": "cc",
  "id_number": "1234567890",
  "phone": "+573001234567",
  "email": "john@example.com"
}

Field	Type	Required	Description
`fullname`	string	✅	Payer’s full name
`id_type`	string	❌	Document type: `cc`, `ce`, `nit` (default: `cc`)
`id_number`	string	✅	Document number
`phone`	string	✅	Phone with country code
`email`	string	✅	Payer’s email

Response

201 CREATED

{
  "id": "cp_vKXigiCryI",
  "fullname": "John Doe",
  "id_type": "cc",
  "id_number": "1234567890"
}

💡

Save the payer id to use in subsequent endpoints.

Bancolombia Button

Generate a payment link for Bancolombia Button.

Endpoint

POST /api/reload/bancolombia/

Headers

Content-Type: application/json
x-api-key: [API_KEY]

Request

Field	Type	Required	Description
`counterparty_id`	string	✅	Created payer ID
`amount`	decimal	✅	Amount in COP (min 1,000)
`external_id`	string	✅	Your unique transaction ID
`description_to_payer`	string	✅	Description for customer (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": "Colurs Deposit - 50,000 COP",
  "description_to_payee": "Deposit from John Doe",
  "redirect_url": "https://app.colurs.co/payment/success",
  "fee_mode": "payer"
}

curl -X POST https://api.colurs.co/api/reload/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": "Colurs Deposit - 50,000 COP",
    "description_to_payee": "Deposit from John Doe",
    "redirect_url": "https://app.colurs.co/payment/success",
    "fee_mode": "payer"
}'

Response

201 CREATED

{
  "money_movement_id": "mm_gaO1SrCBN92BT5",
  "type": "bancolombia",
  "status": "initiated",
  "payment_link": "https://payment.colurs.co/checkout/_VIwgp1lQI5",
  "tracking_key": "917707780",
  "amount": 50000.00,
  "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 user to payment_link to complete payment.

PSE

Generate a payment link for PSE (Pagos Seguros en Línea).

Endpoint

POST /api/reload/pse/

Request

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	✅	Description for customer
`description_to_payee`	string	✅	Internal description
`redirect_url`	string	✅	Redirect URL
`financial_institution_code`	string	✅	PSE bank code
`fee_mode`	string	❌	`payer` or `receiver`

Response

201 CREATED

{
  "money_movement_id": "mm_tjfcYXguVwrNWj",
  "type": "pse",
  "status": "initiated",
  "payment_link": "https://payment.colurs.co/pse/mm_tjfcYXguVwrNWj",
  "tracking_key": "PSE_917707781",
  "amount": 100000.00,
  "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"
  }
}

Get PSE Banks

GET /api/reload/pse/banks/

Returns list of available banks for PSE with their codes.

Nequi

Generate a payment request for Nequi.

Endpoint

POST /api/reload/nequi/

Request

request.json

{
  "counterparty_id": "cp_vKXigiCryI",
  "amount": 25000.00,
  "external_id": "ORDER_123458",
  "description_to_payer": "Colurs Deposit - 25,000 COP",
  "description_to_payee": "Nequi Deposit from John Doe",
  "redirect_url": "https://app.colurs.co/payment/success",
  "fee_mode": "payer"
}

Response

201 CREATED

{
  "money_movement_id": "mm_abc123def456",
  "type": "nequi",
  "status": "initiated",
  "payment_link": null,
  "tracking_key": "NEQUI_12345",
  "amount": 25000.00,
  "currency": "COP",
  "external_id": "ORDER_123458",
  "created_at": "2025-11-14T15:44:41Z",
  "note": "User must complete payment from their 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 payment_link. User must complete payment from their Nequi app using the tracking_key.

Bank transfer reload (BANK_TRANSFER)

Manual reload method: the user submits a bank transfer proof and an operator reviews and approves or rejects it to credit the balance. Unlike Bancolombia, PSE, and Nequi, there is no automatic webhook.

👤

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

Flow

User creates the reload

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

Backend creates the record

The reload stays in Created state (pending approval). Fees are calculated on creation.

Operator reviews the proof

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

Operator approves or rejects

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

If approved

The system credits the user’s balance, records fees (Colurs, IVA), and referral commission if applicable.

Step 1: Create reload with proof (user)

The user indicates they reloaded via bank transfer and provides the proof URL.

Endpoint

POST /reload/create/

Headers

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

Request

Field	Type	Required	Description
`reload_method`	string	✅	`BANK_TRANSFER`
`currency`	string	✅	`COP`, `USD`, `MXN`, or `BRL`
`amount`	decimal	✅	Amount to reload (up to 20 digits, 2 decimals)
`evidence`	string	✅	URL of the proof (image or PDF)
`bank_id`	int	✅	ID of the bank the transfer was made from
`target_bank_id`	int	✅	ID of the destination bank (Colurs account)
`ip`	string	✅	Client IP
`latitude`	string	✅	GPS latitude
`longitude`	string	✅	GPS longitude
`payer_email`	string	❌	Payer’s email
`payer_phone`	string	❌	Payer’s phone
`payer_type_document`	string	❌	Document type: `CC`, `CE`, `TI`, `NIT`, etc.
`payer_document`	string	❌	Payer’s document number
`account_name`	string	❌	Name of the account the transfer was made from

request.json

{
  "reload_method": "BANK_TRANSFER",
  "currency": "COP",
  "amount": 500000,
  "evidence": "https://storage.colurs.co/evidence/reload-123.pdf",
  "bank_id": 1,
  "target_bank_id": 2,
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175",
  "payer_email": "payer@example.com",
  "account_name": "John Doe"
}

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/reload-123.pdf",
    "bank_id": 1,
    "target_bank_id": 2,
    "ip": "192.168.1.1",
    "latitude": "4.60971",
    "longitude": "-74.08175"
  }'

📎

The evidence field must be an accessible URL of the proof (image or PDF uploaded beforehand to your storage).

Success response (200)

200 OK

{
  "message": "OK",
  "data": {
    "id": 316,
    "state": "Created",
    "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
  }
}

The reload remains in Created state until an operator approves or rejects it.

Step 2: Approve or reject reload (operator)

Superusers or operators only. They review the proof and approve or reject the reload.

Endpoint

POST /panel/reload/

Permissions

User must be a superuser or operator. Otherwise the API returns 403 FORBIDDEN.

Headers

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

Request

Field	Type	Required	Description
`reload_id`	int	✅	Reload ID (the `id` from step 1)
`status`	string	✅	`APPROVED` or `REJECTED`

request.json

{
  "reload_id": 316,
  "status": "APPROVED"
}

Success response (200)

200 OK

{
  "code_transaction": "OK",
  "result": "The reload transaction have been APPROVED"
}

If status is REJECTED, the result indicates the reload was rejected and the reload state is set to error.

Process when approved

Reload state → Paid (STATE_PAYED).
User balance is credited (MAIN wallet).
Fees are credited to Colurs (fee and IVA).
Referral commission is credited if applicable.

Process when rejected

Reload state → Error (STATE_ERROR). No balance is credited.

Possible errors

Code	Cause
`403`	User lacks permissions (not superuser or operator)
`404`	Profile not found
`400`	`IncorrectReloadMethod` — Reload is not bank transfer
`400`	`ReloadAlreadyPayed` — Reload was already approved

Check Status

Check payment status at any time.

Endpoint

GET /api/reload/status/{money_movement_id}/

Possible Statuses

Status	Icon	Description
`initiated`	⏳	Payment started, waiting for user
`pending`	🔄	Pending confirmation
`processing`	⚙️	Processing payment
`succeeded`	✅	Payment completed successfully
`failed`	❌	Payment failed
`expired`	⌛	Link expired

Response

Status: initiated

{
  "money_movement_id": "mm_gaO1SrCBN92BT5",
  "type": "bancolombia",
  "status": "initiated",
  "payment_link": "https://payment.colurs.co/checkout/_VIwgp1lQI5",
  "tracking_key": "917707780",
  "amount": 50000.00,
  "currency": "COP",
  "external_id": "ORDER_123456",
  "created_at": "2025-11-14T15:44:39Z",
  "updated_at": "2025-11-14T15:44:39Z"
}

🔄

Recommendation: Poll every 5-10 seconds until status is succeeded or failed.

Fee Modes

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

Common Errors

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

Balance Payment Links