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

USA: Fedwire

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

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.

Automatic Rail Routing

Fast Pay to ACH - When a Colombian destination account is not available for Fast Pay, Cobre automatically send the instruction through ACH. Check Colombian Banks available for Fast Pay or ACH

Bre-B to Fast Pay - All the Bre-B payouts over the Bre-B limit will be automatically routed through Fast Pay (i.e., the fastest Cobre rail)

Split payments Bre-B - Bre-B payouts can be routed through the Bre-B rail in multiple transactions using the Split Payments feature.

Name displayed in statements and when paying

Payouts

Rail	Name in statements	Cobre Feature Enabling it
SPEI	Client’s legal name Client users legal name	Cost Center account (CECO) owned by Cobre’s client Cost center account (CECO) owned by the Cobre client users
Fast Pay	Some banks may include Pexto Colombia SAS in descriptions, but most frequently no name is provided. Varies per bank	N/A
ACH	Some banks may include Pexto Colombia SAS in descriptions, but most frequently no name is provided. Varies per bank	N/A
Bre-B	Pexto Colombia SAS	Cobre’s legal entity name configured by default
Fedwire	Client’s legal name used to create the FBO	Global Payments > Global Counterparty creation

Payins

Rail	Name in statements	Displayed when paying	Cobre Feature Enabling it
PSE	Banks usually don’t include names in descriptors within statements, but if they do it, it is normally Pexto Colombia SAS	Pexto Colombia SAS Client's alias (Commercial name) in the transaction description	Cobre’s legal entity name configured by default Configuration of client’s alias upon client request
Nequi (R2P)	Pexto Colombia SAS Client’s legal name+PXT	Pexto Colombia SAS Client’s legal name	Cobre’s legal entity name configured by default Configuration of client’s legal name upon client request
Nequi Direct Debit	Pexto Colombia SAS Client’s legal name+PXT	Pexto Colombia SAS Client’s legal name+PXT	Cobre’s legal entity name configured by default Configuration of client’s legal name upon client request
Bancolombia	Pexto Colombia SAS	Pexto Colombia SAS	Cobre’s legal entity name configured by default Configuration of client’s legal name upon client request
Bre-B (Dynamic Key)	Pexto Colombia SAS Client’s legal name+PXT	Pexto Colombia SAS Client’s legal name+PXT	Cobre’s legal entity name configured by default Configuration of client’s alias upon client request
Cobre Keys	Pexto Colombia SAS Client’s legal name+PXT Client's client name	Pexto Colombia SAS Client’s legal name+PXT Client's client name	Cobre’s legal entity name configured by default Configuration of client’s alias upon client request Configuration of client’s client name upon client request and new fields in API
Transfer-In (ACH)	Pexto Pagos SAS	N/A	Transfer-In default configuration
SPEI	Cost Center account (CECO) owner	N/A	Cost Center account (CECO) opened during onboarding

Money movement Statuses Catalog

See Money Movement Statuses

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

Name displayed in statements and when paying#

Payouts#

Payins#

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:

Name displayed in statements and when paying

Payouts

Payins

Money movement Statuses Catalog