Movimiento de Dinero

¿Qué es un Money Movement?

Un Money Movement es el objeto unificado de Cobre para representar el ciclo de vida del movimiento de valor hacia o desde tus saldos—ya sea que ese movimiento sea una cobranza (payin) o un desembolso (payout), e independientemente del rail subyacente o la geografía.

Desde el punto de vista de la integración, la API de Money Movement te proporciona:

Una interfaz única para crear y rastrear operaciones de dinero

Un modelo consistente de ciclo de vida y estado

Un patrón estándar para manejar:

procesamiento asíncrono

aprobaciones (Maker–Checker)

fallas y rechazos

devoluciones (solo México)

Esta guía es la introducción conceptual; las subsecciones (SPEI, Bre-B, Checkout, Direct Link, Scheduler, Bulk, etc.) describen campos y comportamientos específicos del rail.

Conceptos Centrales

1) Un objeto, múltiples rails

Un Money Movement puede estar respaldado por múltiples rails, pero siempre interactúas con la misma estructura de recurso y ciclo de vida. El rail típicamente se expresa en sus metadatos y/o en la guía específica que sigas (ej., payouts SPEI, payouts Bre-B, payins Checkout, etc.).

2) Asíncrono por diseño

Los Money Movements se procesan de forma asíncrona: comienzan en un estado inicial y evolucionan mientras Cobre y los sistemas downstream confirman la ejecución. El sistema actualiza el estado "en segundo plano" hasta alcanzar un estado terminal.

3) Idempotencia para reintentos seguros

La API soporta un header de idempotencia opcional para prevenir duplicados accidentales. Si reintentas la misma solicitud con la misma clave de idempotencia dentro de la ventana relevante, Cobre devuelve el Money Movement original en lugar de crear otro.

La Máquina de Estados Universal de Money Movement

Todo Money Movement sigue la misma máquina de estados de alto nivel.

Puedes pensarlo como tres fases:

Creación

Procesamiento

Finalización

A continuación está el ciclo de vida transversal, válido para payins y payouts tanto en México como en Colombia.

1) Fase de Creación

`initiated`

Cuando creas un Money Movement, comienza en initiated.
Esto significa que la solicitud fue aceptada y el movimiento existe, pero la ejecución no ha progresado aún.

2) Fase de Procesamiento

`processing`

El Money Movement se mueve a processing cuando Cobre comienza a ejecutarlo.
En este punto, el movimiento está en vuelo y debes tratarlo como no final.

`pending_approval` (condicional)

Algunos Money Movements requieren aprobación explícita (Maker–Checker) antes de poder ser ejecutados. Estos entran en pending_approval.

Si el money movement fue marcado con checker_approval = true, tu integración debe manejar este estado explícitamente:
ya sea aprobándolo vía los endpoints de Approvals
o esperando que permanezca pendiente hasta que tus operadores internos lo aprueben

3) Fase de Finalización (Estados Terminales)

Los Money Movements terminan en uno de los siguientes estados terminales:

`completed`

La ejecución fue exitosa y el movimiento es final.

`canceled`

El Money Movement fue cancelado antes de completarse (común cuando las aprobaciones expiran o se cancelan, o cuando elementos programados/bulk se cancelan upstream).

`failed`

El procesamiento falló debido a razones operacionales o de nivel de plataforma.

`rejected`

Rechazado significa que el rail, banco, o validación de nivel de usuario causó que la transacción fuera rechazada, a menudo con códigos de razón específicos del rail.

Estados de money movement `returned` (solo México)

Una devolución significa que el movimiento fue exitoso inicialmente pero luego fue devuelto por el contexto de la contraparte/beneficiario (por ejemplo, el beneficiario devolvió el pago).
Ejemplo de razón: R008 Pago Devuelto por el Beneficiario.

Transiciones de Estado (Cómo razonar sobre el ciclo de vida)

Aquí está el diagrama de estado conceptual (simplificado):

initiated → processing

initiated → pending_approval (si se requiere aprobación)

pending_approval → processing (después de la aprobación)

processing → completed

processing → failed / rejected

processing → returned (ruta de devolución post-completación)

pending_approval → canceled (si se cancela/expira)

initiated → canceled (si se cancela antes de la ejecución)

Importante: Todos los estados terminales son finales. Una vez que un Money Movement alcanza un estado terminal, no volverá a transicionar (excepto que algunos rails pueden reportar una devolución después de una completación previa, que se representa por returned).

Patrón de Integración (Recomendado)

Paso 1 — Crear un Money Movement

Usa el endpoint Create Money Movement.

Paso 2 — Suscribirse a eventos de cambio de estado de Money Movement

Dado que los Money Movements son asíncronos, debes suscribirte a eventos de actualización de estado

Evita hacer polling al endpoint Obtain Money Movement hasta alcanzar un estado terminal, ya que crea solicitudes innecesarias

Ver Notifications & Suscriptions

Paso 3 — Manejar la lógica de estados

Si recibes pending_approval, apruébalo o espera la aprobación

Si recibes processing, continúa monitoreando

Si es terminal:

completed → ruta de éxito

failed → evalúa el código de error y estrategia de reintento

rejected → corrige la entrada o trata como caso de negocio fallido

returned → reconcilia la devolución y actualiza tu ledger

canceled → trata como no-op o cancelación intencional del usuario

A dónde ir después (elige tu rail / modalidad)

Esta página es la base conceptual. Para detalles de implementación, ve a:

Rails de payout

Colombia: Fast Pay & ACH, Bre-B

México: SPEI

Rails de payin

Colombia: Checkout, Cobre Keys, Direct Link

México: Virtual CLABEs

Modos de ejecución transversales

Bulk Money Movements

Money Movement Scheduler

Approvals (Maker–Checker)

Reutilizarás el mismo modelo de ciclo de vida descrito aquí en todos ellos.

Para iniciar un movimiento de dinero a través de nuestra API, sus datos de entrada deberían verse similar a lo siguiente:

Tipo de Movimiento de Dinero	Flujo	Origen	Tipo de Origen Permitido	Destino	Tipo de Destino Permitido
SPEI	Push	account_id	clabe	counterparty_id or account_id	clabe or spei_card
FAST PAY	Push	account_id	cobre_balance	counterparty_id or account_id	checking(cc), saving (ch), cobre_balance, electronic deposit (dp)
ACH	Push	account_id	checking(cc), saving (ch) or cobre_balance	counterparty_id or account_id	checking(cc), saving (ch) or electronic deposit (dp)
BREB	Push	account_id	cobre_balance	counterparty_id	Breb-B (breb_key)
GLOBAL	Push	account_id	cobre_balance	counterparty_id	global_deposit_le or global_deposit_np
R2P Direct Dynamic Key	Pull	counterparty_id	r2p or r2p_breb	account_id	cobre_balance
R2P Direct Link	Pull	counterparty_id	r2p	account_id	cobre_balance
DIRECT DEBIT	Pull	counterparty_id	checking(cc), saving (ch) or cobre_balance	account_id	cobre_balance

La flexibilidad de la API para manejar la combinación de objetos de origen y destino garantiza el inicio sin problemas de movimientos de dinero, satisfaciendo una amplia gama de necesidades transaccionales.

Catálogo de Estados de Money Movement

Estado	Código	Descripción
initiated	NA	NA
processing	NA	NA
completed	NA	NA
pending_approval	NA	NA
canceled	NA	NA
failed	F001	Falla en el procesamiento del pago, por favor intenta de nuevo
failed	F002	NSF - Fondos insuficientes en la cuenta designada
failed	F003	Enlace de pago R2P expirado
failed	F004	Se ha alcanzado el límite de monto de transacciones diarias
failed	F005	El monto excede el límite máximo permitido de transacción
failed	F098	No se pudo procesar el money movement en este momento
failed	F099	No se pudo procesar el money movement en este momento
rejected	R000	Transacción rechazada
rejected	R001	Cuenta inactiva o bloqueada
rejected	R002	La cuenta e identificación proporcionadas no coinciden
rejected	R004	ID no válido
rejected	R005	La cuenta no existe
rejected	R006	Número de cuenta inválido
returned	R008	Pago Devuelto por el Beneficiario
rejected	R009	Excede el monto máximo permitido
rejected	R010	Cuenta no autorizada para débito
rejected	R011	Tipo de cuenta inválido.
rejected	R012	El usuario ha abandonado la transacción
rejected	R015	Cuenta no autorizada para ser acreditada
rejected	R016	Pago rechazado por timeout
rejected	R017	Pago rechazado por clave expirada
rejected	R018	Pago rechazado por clave inválida
rejected	R019	Pago rechazado por monto incorrecto
rejected	R020	Pago rechazado por falla de autenticación del usuario
rejected	R021	Fondos insuficientes en la cuenta del pagador
rejected	R023	Pago cancelado por el usuario
rejected	R024	Excede el número máximo permitido de transacciones
rejected	R025	Información requerida faltante
rejected	R026	Pago rechazado por servicios bancarios no disponibles
rejected	R027	La cuenta excede el límite máximo permitido de transacción
rejected	R034	Cuenta cerrada
rejected	R081	El registro de la contraparte ha expirado
rejected	R082	El registro de la contraparte ha sido cancelado
rejected	R084	El registro de la contraparte ha sido rechazado

Movimiento de Dinero

¿Qué es un Money Movement?#

Conceptos Centrales#

1) Un objeto, múltiples rails#

2) Asíncrono por diseño#

3) Idempotencia para reintentos seguros#

La Máquina de Estados Universal de Money Movement#

1) Fase de Creación#

initiated#

2) Fase de Procesamiento#

processing#

pending_approval (condicional)#

3) Fase de Finalización (Estados Terminales)#

completed#

canceled#

failed#

rejected#

Estados de money movement returned (solo México)#

Transiciones de Estado (Cómo razonar sobre el ciclo de vida)#

Patrón de Integración (Recomendado)#

Paso 1 — Crear un Money Movement#

Paso 2 — Suscribirse a eventos de cambio de estado de Money Movement#

Paso 3 — Manejar la lógica de estados#

A dónde ir después (elige tu rail / modalidad)#

Rails de payout#

Rails de payin#

Modos de ejecución transversales#

Para iniciar un movimiento de dinero a través de nuestra API, sus datos de entrada deberían verse similar a lo siguiente:#

Catálogo de Estados de Money Movement#

¿Qué es un Money Movement?

Conceptos Centrales

1) Un objeto, múltiples rails

2) Asíncrono por diseño

3) Idempotencia para reintentos seguros

La Máquina de Estados Universal de Money Movement

1) Fase de Creación

`initiated`

2) Fase de Procesamiento

`processing`

`pending_approval` (condicional)

3) Fase de Finalización (Estados Terminales)

`completed`

`canceled`

`failed`

`rejected`

Estados de money movement `returned` (solo México)

Transiciones de Estado (Cómo razonar sobre el ciclo de vida)

Patrón de Integración (Recomendado)

Paso 1 — Crear un Money Movement

Paso 2 — Suscribirse a eventos de cambio de estado de Money Movement

Paso 3 — Manejar la lógica de estados

A dónde ir después (elige tu rail / modalidad)

Rails de payout

Rails de payin

Modos de ejecución transversales

Para iniciar un movimiento de dinero a través de nuestra API, sus datos de entrada deberían verse similar a lo siguiente:

Catálogo de Estados de Money Movement