Crear retiro

Esta página documenta el contrato mejor conocido para retiros a terceros en Colombia a partir de exports legacy de Cobru. Revalida el comportamiento exacto en sandbox antes de convertirlo en una dependencia de producción.

Endpoint

POST /thirdpartywithdraw/

Payload de ejemplo

{
  "account_holder_name": "Carlos Alberto Perez Gomez",
  "account_type": 0,
  "account_holder_document_type": 0,
  "account_holder_document": "1045672890",
  "account_number": "1234567890",
  "bank_name": 7,
  "override": true,
  "amount": 50000,
  "latitude": "10.9711",
  "longitude": "-74.7837",
  "idempotency_key": "6f3e8b7e-0b7d-4e4c-8c32-6b0d0f8c9a21",
  "description": "Pago proveedor",
  "coupon": ""
}

Campos del request

Campo	Tipo	Requerido	Notas
`account_holder_name`	`string`	sí	Nombre completo del titular de la cuenta destino. Sale del input de nombre o de una cuenta guardada.
`account_type`	`number`	sí	Tipo de cuenta bancaria destino. Sale del selector de tipo de cuenta.
`account_holder_document_type`	`number`	sí	Tipo de documento del titular de la cuenta destino. Sale del selector de tipo de documento.
`account_holder_document`	`string`	sí	Número de documento del titular destino.
`account_number`	`string`	sí	Número de cuenta destino. La app limpia caracteres y envía solo dígitos.
`bank_name`	`number`	sí	ID del banco destino cargado desde el listado de bancos para retiros a terceros. No es el nombre del banco en texto.
`override`	`boolean`	sí	Bandera enviada por la app para continuar con la creación del retiro.
`amount`	`number`	sí	Monto del retiro en COP.
`latitude`	`string`	sí	Latitud enviada por la app.
`longitude`	`string`	sí	Longitud enviada por la app.
`idempotency_key`	`string`	sí	Identificador único para deduplicar intentos de payout.
`description`	`string`	no	Nota opcional del payout o descripción interna.
`coupon`	`string`	no	Código de cupón o cadena vacía cuando no aplica.

Valores usados por la app

Tipo de cuenta

Valor	Significado
`0`	Ahorros
`1`	Corriente

Tipo de documento

Valor	Significado
`0`	Cédula de ciudadanía
`1`	Cédula de extranjería
`3`	NIT
`4`	Pasaporte
`5`	Permiso de Protección Temporal

Banco destino

El campo bank_name usa el value del banco seleccionado en el listado de bancos, no el label.

{
  "value": 7,
  "label": "BANCOLOMBIA"
}

Entonces el request envía:

{
  "bank_name": 7
}

Qué debes confirmar con Cobru antes de salir a producción

si override debe enviarse siempre en true o depende de una validación previa
si los callbacks siguen soportados o fueron reemplazados por webhooks
tiempos de settlement y estados terminales del payout

Señales de error vistas en materiales antiguos

Señal	Significado
`R010`	Datos bancarios inválidos o rechazo de validación.
`P002`	Falla de procesamiento o del proveedor.
`E001`	Error genérico de validación o proveedor downstream.

Notas de producción

Envía siempre una idempotency_key si Cobru confirma que sigue soportada.
Guarda el identificador del retiro retornado por Cobru para reconciliar cambios de estado.
Trata los retiros bancarios como asíncronos incluso si la respuesta inicial es exitosa.
Usa el ID numérico del banco en bank_name; no envíes el nombre visible del selector.

Crear retiro

On this page