Money Movement

What is a Money Movement?

A Money Movement is Cobre’s unified object to represent the lifecycle of moving value in or out of your balances—whether that movement is a collection (payin) or a disbursement (payout), and regardless of the underlying rail or geography.

From an integration standpoint, the Money Movement API gives you:

A single interface to create and track money operations

A consistent lifecycle and status model

A standard pattern to handle:

asynchronous processing

approvals (Maker–Checker)

failures and rejections

returns (Mexico only)

This guide is the conceptual introduction; the subsections (SPEI, Bre-B, Checkout, Direct Link, Scheduler, Bulk, etc.) describe rail-specific fields and behaviors.

Core Concepts

1) One object, multiple rails

A Money Movement can be backed by multiple rails, but you always interact with the same resource structure and lifecycle. The rail is typically expressed in its metadata and/or in the specific guide you follow (e.g., SPEI payouts, Bre-B payouts, Checkout payins, etc.).

2) Asynchronous by design

Money Movements are processed asynchronously: they start in an initial state and evolve as Cobre and downstream systems confirm execution. The system updates status “in the background” until reaching a terminal state.

3) Idempotency for safe retries

The API supports an optional idempotency header to prevent accidental duplicates. If you retry the same request with the same idempotency key within the relevant window, Cobre returns the original Money Movement instead of creating another one.

The Universal Money Movement State Machine

Every Money Movement follows the same high-level state machine.

You can think of it as three phases:

Creation

Processing

Finalization

Below is the transversal lifecycle, valid for payins and payouts in both Mexico and Colombia.

1) Creation Phase

`initiated`

When you create a Money Movement, it begins in initiated.
This means the request was accepted and the movement exists, but execution has not progressed yet.

2) Processing Phase

`processing`

The Money Movement moves into processing when Cobre starts executing it.
At this point, the movement is in flight and you should treat it as non-final.

`pending_approval` (conditional)

Some Money Movements require explicit approval (Maker–Checker) before they can be executed. Those enter pending_approval.

If the money movement was marked with checker_approval = true, your integration must handle this state explicitly:
either by approving via the Approvals endpoints
or by expecting it to remain pending until your internal operators approve it

3) Finalization Phase (Terminal States)

Money Movements end in one of the following terminal states:

`completed`

Execution succeeded and the movement is final.

`canceled`

The Money Movement was canceled before completion (common when approvals expire or are canceled, or when scheduled/bulk items are canceled upstream).

`failed`

Processing failed due to operational or platform-level reasons.

`rejected`

Rejected means the rail, bank, or user-level validation caused the transaction to be rejected, often with rail-specific reason codes.

Money movement statuses `returned` (Mexico only)

A return means the movement succeeded initially but was later returned by the counterparty/beneficiary context (for example, beneficiary returned the payment).
Example reason: R008 Payment Returned by Beneficiary.

Status Transitions (How to reason about the lifecycle)

Here is the conceptual state diagram (simplified):

initiated → processing

initiated → pending_approval (if approval required)

pending_approval → processing (after approval)

processing → completed

processing → failed / rejected

processing → returned (post-completion return path)

pending_approval → canceled (if canceled/expired)

initiated → canceled (if canceled before execution)

Important: All terminal states are final. Once a Money Movement reaches a terminal state, it will not transition again (except that some rails may report a return after a previous completion, which is represented by returned).

Integration Pattern (Recommended)

Step 1 — Create a Money Movement

Use the Create Money Movement endpoint.

Because Money Movements are asynchronous, you must subscribe to status update events

Avoid polling the Obtain Money Movement endpoint until you reach a terminal state, since it creates unnecesary requests

See Notifications & Suscriptions

Step 3 — Handle status logic

If you receive pending_approval, approve it or wait for approval

If you receive processing, keep monitoring

If terminal:

completed → success path

failed → evaluate error code and retry strategy

rejected → correct input or treat as failed business case

returned → reconcile return and update your ledger

canceled → treat as no-op or user-intent cancellation

Where to go next (choose your rail / modality)

This page is the conceptual base. For implementation details, go to:

Payout rails

Colombia: Fast Pay & ACH, Bre-B

Mexico: SPEI

Payin rails

Colombia: Checkout, Cobre Keys, Direct Link

Mexico: Virtual CLABEs

Cross-cutting execution modes

Bulk Money Movements

Money Movement Scheduler

Approvals (Maker–Checker)

You will reuse the same lifecycle model described here across all of them.

To initiate a money movement through our API, your input should look like this:

Money Movement type	Flow	Source	Allowed source type	Destination	Allowed destination type
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

The API's flexibility in handling the combination of source and destination objects ensures the seamless initiation of money movements, catering to a wide range of transactional needs.

Money movement Statuses Catalog

Status	Code	Description
initiated	NA	NA
processing	NA	NA
completed	NA	NA
pending_approval	NA	NA
canceled	NA	NA
failed	F001	Payment processing failed please try again
failed	F002	NSF - Not Sufficient Funds in the designated account
failed	F003	R2P Payment link expired
failed	F004	Daily transaction amount limit has been reached
failed	F005	Amount exceeds the maximum allowed transaction limit
failed	F098	Could not process the money movement at this time
failed	F099	Could not process the money movement at this time
rejected	R000	Transaction rejected
rejected	R001	Inactive or blocked account
rejected	R002	Account and identification provided do not coincide
rejected	R004	ID not valid
rejected	R005	Account does not exist
rejected	R006	Invalid account number
returned	R008	Payment Returned by Beneficiary
rejected	R009	Exceeds maximum allowed amount
rejected	R010	Account not authorized to debit
rejected	R011	Invalid Account type.
rejected	R012	The user has abandoned the transaction
rejected	R015	Account not authorized to be credited
rejected	R016	Payment rejected due to timeout
rejected	R017	Payment rejected due to expired key
rejected	R018	Payment rejected due invalid key
rejected	R019	Payment rejected due to incorrect amount
rejected	R020	Payment rejected due to user authentication failure
rejected	R021	Insufficient funds in payer account
rejected	R023	Payment cancelled by the user
rejected	R024	Exceeds maximum allowed number of transactions
rejected	R025	Required information missing
rejected	R026	Payment rejected due to unavailable bank services
rejected	R027	Account exceeds the maximum allowed transaction limit
rejected	R034	Account closed
rejected	R081	The counterparty registration has expired
rejected	R082	The counterparty registration has been canceled
rejected	R084	The counterparty registration has been rejected

Money Movement

What is a Money Movement?#

Core Concepts#

1) One object, multiple rails#

2) Asynchronous by design#

3) Idempotency for safe retries#

The Universal Money Movement State Machine#

1) Creation Phase#

initiated#

2) Processing Phase#

processing#

pending_approval (conditional)#

3) Finalization Phase (Terminal States)#

completed#

canceled#

failed#

rejected#

Money movement statuses returned (Mexico only)#

Status Transitions (How to reason about the lifecycle)#

Integration Pattern (Recommended)#

Step 1 — Create a Money Movement#

Step 2 — Subscribe to Money Movement status change events#

Step 3 — Handle status logic#

Where to go next (choose your rail / modality)#

Payout rails#

Payin rails#

Cross-cutting execution modes#

To initiate a money movement through our API, your input should look like this:#

Money movement Statuses Catalog#

What is a Money Movement?

Core Concepts

1) One object, multiple rails

2) Asynchronous by design

3) Idempotency for safe retries

The Universal Money Movement State Machine

1) Creation Phase

`initiated`

2) Processing Phase

`processing`

`pending_approval` (conditional)

3) Finalization Phase (Terminal States)

`completed`

`canceled`

`failed`

`rejected`

Money movement statuses `returned` (Mexico only)

Status Transitions (How to reason about the lifecycle)

Integration Pattern (Recommended)

Step 1 — Create a Money Movement

Step 2 — Subscribe to Money Movement status change events

Step 3 — Handle status logic

Where to go next (choose your rail / modality)

Payout rails

Payin rails

Cross-cutting execution modes

To initiate a money movement through our API, your input should look like this:

Money movement Statuses Catalog