Payouts Reconciliation
Money Movements vs. Transactions
| Identifier | Prefix | Generated when | Represents |
|---|---|---|---|
| Money Movement ID | mm_ | The payout is created | The payment intent/request and its lifecycle status |
| Transaction ID | trx_ | Funds are debited or credited on your Cobre Balance | The actual balance-affecting ledger entry |
metadata.money_movement_id field linking it back — use this field to group Transactions by the payout that generated them.external_id when creating a payout (Create a Money Movement). It's echoed back on the Money Movement and is the simplest way to match a Cobre payout to your internal invoice, order, or payment record.Payout Lifecycle and Balance Impact
status.state tells you whether it completed, and its status.code / status.description explain why when it didn't. See Money Movement Statuses for the full catalog of reason codes, and the Money Movement guide for the complete lifecycle model.| Terminal state | Typical Transactions | Net balance impact |
|---|---|---|
completed | 1 debit | Negative (funds sent) |
canceled | 0 (canceled before a debit was applied — e.g., an approval was denied) | None |
failed | 0 — a failed payout never generates a debit at all | None |
rejected | 0, or 1 debit + 1 offsetting credit if a debit was already applied | None (if reversed) |
failed and rejected aren't interchangeable for reconciliation purposes. failed covers operational/platform-level issues caught before any debit is applied (e.g. NSF, limits exceeded, processing errors) — there's never a Transaction to look for. rejected covers rail- or bank-level rejections, which can happen after the debit already posted — that's the case that produces the offsetting credit below.completed to rejected if the destination bank returns the funds after Cobre already confirmed completion. When this happens, Cobre applies an offsetting credit transaction to your Cobre Balance. Don't treat completed as a permanently final balance state for reconciliation — always check for a later reversal Transaction under the same money_movement_id.spei_return credit Transaction that offsets the original spei_debit — reconcile MX payout reversals by matching these two transaction types under the same money_movement_id.Reconciling Payouts On Demand
GET /money_movements) directly when you need to check a specific payout or a small batch:| Filter | Use it to |
|---|---|
state | Isolate completed, rejected, failed, or canceled payouts |
external_id | Find the Money Movement for a specific internal reference (contains match) |
source_id / destination_id | Reconcile all payouts from a Cobre Balance or to a counterparty |
created_at_gte / created_at_lte | Bound the query to a date range |
amount, amount_gte, amount_lte, currency | Narrow by value |
GET /accounts/{acct_id}/transactions), filtering credit_debit_type=debit and matching metadata.money_movement_id, to confirm the balance-affecting side of each payout.Reconciling Payouts in Bulk
1.
money_movement_csv_v1 for CSV, or money_movement_v1 for JSON) and one for the Transaction side (transactions_csv_v1 for CSV, or account_transactions_v1 for JSON), over the same date range.2.
metadata.money_movement_id.3.
money_movement_id with exactly one debit row reconciles as a completed payout; one with a debit and an offsetting credit reconciles as a reversed rejection or failure.Reconciling Payouts in Real Time
money_movements.status.completed, money_movements.status.rejected, money_movements.status.failed, money_movements.status.canceled), so you can update your ledger the moment it happens rather than polling for it.Opening and Closing Balance Reconciliation
Allowed Actions on Payout Reconciliation
🔍 Retrieval — Money Movements
🔍 Retrieval — Transactions
🔍 Retrieval — Daily Balance History
🔑 Reports
Description: Query payouts on demand by state, external ID, counterparty, date range, or amount.What to expect after the action: A paginated list of Money Movement objects with their current 📘 Learn more:
status.How to Get Started
Always provide external_id on every payout
It's the fastest way to match a Cobre Money Movement to your internal record, and it's searchable via the
external_id filter.Subscribe to Money Movement status events instead of polling
See Notifications & Subscriptions to get notified in near real-time instead of repeatedly querying the API.
Know your rail's reason codes
Review Money Movement Statuses so a
failed or rejected payout's code and description are actionable rather than opaque.Decide between on-demand queries and Reports upfront
Use on-demand queries for individual payouts or small batches, and Reports for date-range or high-volume reconciliation.
What to expect after using this API
Every payout resolves to a matched Money Movement + Transaction pair
Completed payouts show one debit; reversed rejections or failures show a debit and an offsetting credit under the same
money_movement_id.Opening and closing balances validate against Daily Balance History
initial_balance and end_balance from Daily Balance History match what you compute manually from ordered Transactions.Discrepancies isolate to a specific money_movement_id
Any balance mismatch narrows down to one payout you can investigate directly via its Money Movement and Transaction records.
Modified at 2026-08-21 00:09:37