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 libro de contabilidad

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

USA: Fedwire

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)
BRE-B	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
Fedwire	Push	account_id	cobre_balance	counterparty_id	business
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.

Enrutamiento Automático de Rieles

Fast Pay a ACH - Cuando una cuenta de destino colombiana no está disponible para Fast Pay, Cobre automáticamente envía la instrucción por ACH. Consulta los Bancos Colombianos disponibles para Fast Pay o ACH

Bre-B a Fast Pay - Todos los payouts Bre-B que superen el límite de Bre-B serán automáticamente enrutados por Fast Pay (es decir, el rail más rápido de Cobre)

Pagos Divididos Bre-B - Los payouts Bre-B pueden enrutarse por el riel Bre-B en múltiples transacciones usando la funcionalidad de Pagos Divididos.

Nombre mostrado en extractos y al pagar

Payouts

Rail	Nombre en extractos	Funcionalidad de Cobre que lo habilita
SPEI	Razón social del cliente Razón social de los usuarios del cliente	Cuenta de Centro de Costos (CECO) propiedad del cliente de Cobre Cuenta de Centro de Costos (CECO) propiedad de los usuarios del cliente de Cobre
Fast Pay	Algunos bancos pueden incluir Pexto Colombia SAS en las descripciones, pero lo más frecuente es que no se proporcione ningún nombre. Varía según el banco	N/A
ACH	Algunos bancos pueden incluir Pexto Colombia SAS en las descripciones, pero lo más frecuente es que no se proporcione ningún nombre. Varía según el banco	N/A
Bre-B	Pexto Colombia SAS	Nombre de la entidad legal de Cobre configurado por defecto
Fedwire	Razón social del cliente utilizada para crear el FBO	Global Payments > Creación de Global Counterparty

Payins

Rail	Nombre en extractos	Mostrado al pagar	Funcionalidad de Cobre que lo habilita
PSE	Los bancos normalmente no incluyen nombres en las descripciones de los extractos, pero si lo hacen, suele ser Pexto Colombia SAS.	Pexto Colombia SAS Alias del cliente (nombre comercial) en la descripción de la transacción	Nombre de la entidad legal de Cobre configurado por defecto Configuración del alias del cliente a solicitud del cliente
Nequi (R2P)	Pexto Colombia SAS Razón social del cliente+PXT	Pexto Colombia SAS Razón social del cliente	Nombre de la entidad legal de Cobre configurado por defecto Configuración de la razón social del cliente a solicitud del cliente
Nequi Débito Directo	Pexto Colombia SAS Razón social del cliente+PXT	Pexto Colombia SAS Razón social del cliente+PXT	Nombre de la entidad legal de Cobre configurado por defecto Configuración de la razón social del cliente a solicitud del cliente
Bancolombia	Pexto Colombia SAS	Pexto Colombia SAS	Nombre de la entidad legal de Cobre configurado por defecto Configuración de la razón social del cliente a solicitud del cliente
Bre-B (Llave Dinámica)	Pexto Colombia SAS Razón social del cliente+PXT	Pexto Colombia SAS Razón social del cliente+PXT	Nombre de la entidad legal de Cobre configurado por defecto Configuración del alias del cliente a solicitud del cliente
Cobre Keys	Pexto Colombia SAS Razón social del cliente+PXT Nombre del cliente del cliente	Pexto Colombia SAS Razón social del cliente+PXT Nombre del cliente del cliente	Nombre de la entidad legal de Cobre configurado por defecto Configuración del alias del cliente a solicitud del cliente Configuración del nombre del cliente del cliente a solicitud del cliente y nuevos campos en la API
Transfer-In (ACH)	Pexto Pagos SAS	N/A	Configuración por defecto de Transfer-In
SPEI	Titular de la cuenta de Centro de Costos (CECO)	N/A	Cuenta de Centro de Costos (CECO) abierta durante el onboarding

Catálogo de Estados de Money Movement

Ver Money Movement Statuses

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:#

Nombre mostrado en extractos y al pagar#

Payouts#

Payins#

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:

Nombre mostrado en extractos y al pagar

Payouts

Payins

Catálogo de Estados de Money Movement