Destinatarios México (MXN)

Registra y gestiona cuentas destinatarias (recipients) para retiros en pesos mexicanos vía SPEI.

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

Flujo

Consultar códigos bancarios

Obtén la lista de bancos con GET /bank-codes/mxn para usar el code al crear destinatarios.

Crear destinatario

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

Listar o eliminar

Consulta tus destinatarios con GET /recipients/mxn o elimina uno con DELETE /recipients/mxn.

Códigos bancarios

Obtiene los códigos de banco disponibles en México. Necesario para registrar cuentas destinatarias.

Códigos Bancarios MXN

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')

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"}
]
}

💡

Usa el campo `code` del banco en `bank_code` al crear un destinatario.

Destinatarios

Listar destinatarios

Obtiene las cuentas destinatarias registradas del usuario.

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 base local, 'api' para sincronizar con el servicio

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 SPEI en **Retiros México (MXN)**.

Eliminar destinatario

Elimina una cuenta destinataria registrada.

Eliminar Destinatario

Autorización

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

Endpoint

DELETEhttps://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
recipient_id	string	✓	ID del destinatario a eliminar

request.json?recipient_id=rec_abc123

Ejemplo cURL

curl -X DELETE "https://dev.backend.colurs.co/recipients/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

📄

Para ejecutar un retiro a un destinatario ya registrado, consulta Retiros México (MXN) en la sección Pagos.

Cuentas bancarias EEUU Índice de referencia