Retiros México (MXN)

Retira fondos a una cuenta bancaria registrada en México en pesos mexicanos.

Todos los endpoints requieren autenticación con Authorization: Bearer [TOKEN] y x-api-key.

Flujo General

Consultar códigos bancarios

Obtén la lista de bancos disponibles con GET /bank-codes/mxn.

Crear destinatario

Registra la cuenta bancaria del beneficiario con POST /recipients/mxn.

Ejecutar retiro

Crea el retiro SPEI con POST /withdrawals/mxn/.

Códigos Bancarios

Obtiene la lista de códigos bancarios disponibles para un país. Necesario para registrar cuentas destinatarias.

Códigos Bancarios

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GEThttps://dev.backend.colurs.co/bank-codes/mxn

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
country	string	✓	Código de país (ej. 'mx', 'br', 'co')

request.json?country=mx

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/bank-codes/mxn?country=mx" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": [
  { "code": "40012", "name":  "BBVA México"},
  { "code": "40014", "name":  "Santander México"},
  { "code": "40021", "name":  "HSBC México"},
  { "code": "40072", "name":  "Banorte"},
  { "code": "40044", "name":  "Scotiabank México"}
]
}

💡

Guarda el `code` del banco para usarlo al crear un destinatario o método de retiro.

Destinatarios

Listar Destinatarios

Obtiene las cuentas destinatarias registradas del usuario. Puede consultar desde la base de datos local o sincronizar directamente con el servicio externo.

Listar Destinatarios

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GEThttps://dev.backend.colurs.co/recipients/mxn

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
currency	string	✕	Moneda (default: 'mxn')
network	string	✕	Red (ej. 'spei')
protocol	string	✕	Protocolo (ej. 'clabe')
source	string	✕	'db' (default) para local, 'api' para sincronizar con el servicio externo

request.json?currency=mxn&network=spei

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/recipients/mxn?currency=mxn" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": [
  {
    "recipient_id": "rec_abc123",
    "beneficiary_name": "María López",
    "account_number": "646180157000000099",
    "bank_code": 
  "40012"}
]
}

Crear Destinatario

Registra una nueva cuenta bancaria como destinatario para retiros MXN.

Crear Destinatario

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POSThttps://dev.backend.colurs.co/recipients/mxn

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
beneficiary_name	string	✓	Nombre completo del beneficiario
account_number	string	✓	Número de cuenta CLABE (18 dígitos)
bank_code	string	✓	Código del banco (obtenido de /bank-codes/mxn)
currency	string	✓	Moneda (ej. 'mxn')
network	string	✕	Red (ej. 'spei')
protocol	string	✕	Protocolo (ej. 'clabe')

request.json{
"beneficiary_name": "María López",
"account_number": "646180157000000099",
"bank_code": "40012",
"currency": "mxn",
"network": "spei",
"protocol": "clabe"
}

Ejemplo cURL

curl -X POST "https://dev.backend.colurs.co/recipients/mxn" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"beneficiary_name":"María López","account_number":"646180157000000099","bank_code":"40012","currency":"mxn"}'

Respuesta

response.json

{
"code_transaction": "OK",
"recipient_id": 
"rec_xyz789"}

Errores Posibles

Código	Error	Descripción
400	BadRequest	Datos de cuenta inválidos o CLABE incorrecta
409	Conflict	El destinatario ya está registrado

💡

Guarda el `recipient_id` para usarlo al crear retiros.

Métodos de Retiro

Listar Métodos de Retiro

Obtiene los métodos de retiro (cuentas destinatarias) registrados del usuario.

Listar Métodos de Retiro

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GEThttps://dev.backend.colurs.co/withdrawal-methods/mxn

Headers Requeridos

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

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/withdrawal-methods/mxn" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": [
  {
    "recipient_id": "rec_abc123",
    "beneficiary_name": "María López",
    "account_number": "646180157000000099",
    "bank_code": 
  "40012"},
  {
    "recipient_id": "rec_def456",
    "beneficiary_name": "Carlos García",
    "account_number": "014180605000000001",
    "bank_code": 
  "40014"}
]
}

Eliminar Método de Retiro

Elimina una cuenta destinataria registrada.

Eliminar Método de Retiro

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

DELETEhttps://dev.backend.colurs.co/withdrawal-methods/mxn

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
recipient_id	string	✓	ID del destinatario a eliminar

request.json?recipient_id=rec_abc123

Ejemplo cURL

curl -X DELETE "https://dev.backend.colurs.co/withdrawal-methods/mxn?recipient_id=rec_abc123" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"message": 
"Recipient deleted successfully"}

Errores Posibles

Código	Error	Descripción
400	BadRequest	recipient_id no proporcionado
404	NotFound	Destinatario no encontrado

Crear Retiro SPEI

Ejecuta un retiro de MXN vía SPEI a la cuenta destinataria registrada.

Crear Retiro MXN

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POSThttps://dev.backend.colurs.co/withdrawals/mxn/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
recipient_id	string	✓	ID del destinatario registrado
amount	string	✓	Monto a retirar en MXN (ej. '10000.00')
reference	string	✕	Referencia de la transferencia
concept	string	✕	Concepto de pago SPEI

request.json{
"recipient_id": "rec_abc123",
"amount": "10000.00",
"reference": "PAGO_PROVEEDOR_001",
"concept": "Pago de servicios"
}

Ejemplo cURL

curl -X POST "https://dev.backend.colurs.co/withdrawals/mxn/" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"recipient_id":"rec_abc123","amount":"10000.00","concept":"Pago de servicios"}'

Respuesta

response.json

{
"code_transaction": "OK",
"withdraw_id": 12345,
"wid": "w_abc123xyz",
"amount": "10000.00",
"fee": "15.00",
"total": "10015.00",
"status": 
"pending"}

Errores Posibles

Código	Error	Descripción
400	BadRequest	Datos inválidos o monto fuera de rango
402	InsufficientFunds	Saldo insuficiente para el retiro
404	NotFound	Destinatario no encontrado

⚠️

El campo `fee` indica la comisión cobrada. El campo `total` es el monto descontado del balance (amount + fee).

Retiros Bancarios Envío entre usuarios