Reconciliation with Cobre Reports in Colombia

Overview

This guide explains how to properly reconcile PayOut (disbursements) and PayIn (collections) transactions in Cobre's platform for local payments in Colombia. Understanding the relationship between Money Movements, Transactions, and your internal records is essential for accurate financial reconciliation.

Core Concepts

Money Movement vs Transaction

In Cobre's platform, every payment operation involves two key identifiers:

Identifier	Description	Example	When Generated
Money Movement ID	Unique identifier for the payment request/operation	`mm_ady1n4g4ud`	When the money movement is created
Transaction ID	Unique identifier for the accounting ledger entry	`trx_sjrirldkmk`	When funds are debited or credited to your Cobre Balance

Key Relationship:

One Money Movement can generate one or more Transactions

Every Transaction is linked to a Money Movement

Money Movements represent the intent; Transactions represent the actual balance changes

Identification Methods

When creating any money movement (PayOut or PayIn), you have two ways to identify and track it:

1. Money Movement ID (Cobre-generated)

Generated by: Cobre Platform automatically

Format: mm_ prefix followed by alphanumeric string

Uniqueness: Globally unique across all Cobre operations

Availability: Always present in the API response when the money movement is created

Use case: Primary identifier for tracking with Cobre

2. External ID (Client-provided)

Generated by: Your system (provided in the API request)

Format: Any string format you define (up to 255 characters)

Uniqueness: Must be unique within your organization

Availability: Optional field in the request, echoed back in responses

Use case: Link Cobre operations to your internal records (invoices, orders, etc.)

Example Request:

curl --request POST \
  --url https://api.cobre.co/v1/money_movements \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'idempotency: ' \
  --data '{
  "source_id": "acc_1232145215",
  "destination_id": "cp_5YFeIDhNkz",
  "amount": 1000,
  "external_id": "clientUser1234",
  "metadata": {
    // Will change according to the money movement type
  },
  "checker_approval": false
}'

Example Response:

{
  "id": "mm_0987654321",
  "batch_id": "bat_0987654321" || "chk_0987654321",
  "external_id": "clientUser1234",
  "mm_approval_id": "",
  "creator": "usr_bGcdf26rR4",
  "type": "fast_pay",
  "geo": "col",
  "status": {
    "state": "initiated",
    "code": "string",
    "description": "string"
  },
  "source_id": "acc_KJnAkypWSc",
  "source": {},
  "destination_id": "cp_5YFeIDhNkz",
  "destination": {},
  "currency": "cop",
  "amount": 100,
  "metadata": {
    // Will change according to the money movement type
  },
  "created_at": "2026-06-24T15:37:37Z",
  "updated_at": "2026-06-24T15:37:38Z",
  "checker_approval": false
}

PayOut Reconciliation

PayOuts (disbursements) allow you to send money from your Cobre Balance to external bank accounts or counterparties.

PayOut Request Structure

When creating a PayOut, you specify:

Field	Description	Required
`source_id`	Your Cobre Balance (origin account)	✅ Yes
`destination_id`	Counterparty/beneficiary account	✅ Yes
`amount`	Amount to disburse (in minor units, e.g., cents)	✅ Yes
`external_id`	Your unique reference for tracking	No, but recommended

PayOut Transaction Flow

Happy Path: Successful Disbursement

┌─────────────────────────────────────┐
│  1. Create PayOut Money Movement    │
│  POST /v1/money_movements           │
│  • Amount: 10,000 COP               │
│  • External ID: INV-2025-001        │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Money Movement Created          │
│  • MM ID: mm_ady1n4g4ud             │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Debit Transaction Created       │
│  • TRX ID: trx_sjrirldkmk           │
│  • Type: debit                      │
│  • Amount: -10,000 COP              │
│  • Account: Source Balance          │
│  • Instant application              │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Funds Sent Successfully         │
│  • MM Status: completed             │
│  • Destination received funds       │
└─────────────────────────────────────┘

Reconciliation Steps:

Money Movement Created:

Money Movement ID: mm_ady1n4g4ud

External ID: INV-2025-001

Amount: 10,000 COP

Status: processing

Debit Transaction Applied (Instant):

Transaction ID: trx_sjrirldkmk

Type: debit

Amount: -10,000 COP

Account Balance: Reduced by 10,000 COP immediately

Linked to Money Movement: mm_ady1n4g4ud

Final Status:

Money Movement Status: completed

Your Cobre Balance: Permanently reduced by 10,000 COP

Beneficiary: Received 10,000 COP

Reconciliation Record:

Money Movement ID	External ID	Type	Amount	Transactions	Final Balance Impact
`mm_ady1n4g4ud`	`INV-2025-001`	PayOut	10,000 COP	1 debit (`trx_sjrirldkmk`)	-10,000 COP

Alternative Path: Rejected Disbursement

┌─────────────────────────────────────┐
│  1. Create PayOut Money Movement    │
│  POST /v1/money_movements           │
│  • Amount: 10,000 COP               │
│  • External ID: INV-2025-002        │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Money Movement Created          │
│  • MM ID: mm_xyz789def              │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Debit Transaction Created       │
│  • TRX ID: trx_abc123first          │
│  • Type: debit                      │
│  • Amount: -10,000 COP              │
│  • Account: Source Balance          │
│  • Instant application              │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Destination Rejects Payment     │
│  • MM Status: rejected              │
│  • Reason: Invalid account, etc.    │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  5. Credit Transaction Created      │
│  • TRX ID: trx_abc123second         │
│  • Type: credit (reversal)          │
│  • Amount: +10,000 COP              │
│  • Account: Source Balance          │
│  • Funds returned to origin         │
└─────────────────────────────────────┘

Reconciliation Steps:

Money Movement Created:

Money Movement ID: mm_xyz789def

External ID: INV-2025-002

Amount: 10,000 COP

Status: processing

Debit Transaction Applied (Instant):

Transaction ID: trx_abc123first

Type: debit

Amount: -10,000 COP

Account Balance: Reduced by 10,000 COP immediately

Rejection Occurred:

Money Movement Status: rejected

Reason: Destination account rejected or invalid

Credit Transaction Applied (Reversal):

Transaction ID: trx_abc123second

Type: credit

Amount: +10,000 COP

Account Balance: Restored by 10,000 COP

Linked to same Money Movement: mm_xyz789def

Final Status:

Money Movement Status: rejected

Your Cobre Balance: Net change = 0 COP (debit + credit)

Beneficiary: Did not receive funds

Reconciliation Record:

Money Movement ID	External ID	Type	Amount	Transactions	Final Balance Impact
`mm_xyz789def`	`INV-2025-002`	PayOut	10,000 COP	2 transactions: 1. Debit: `trx_abc123first` (-10,000) 2. Credit: `trx_abc123second` (+10,000)	0 COP (reversed)

PayOut Reconciliation Best Practices

✅ Always track both IDs: Store both money_movement_id and external_id in your records
✅ Monitor status changes: A PayOut with 2 transactions (debit + credit) indicates a rejection
✅ Use webhooks: Subscribe to status change events to update records in real-time
✅ Query Transaction Report: Download reports filtered by date range to reconcile all movements
✅ Net balance check: For rejected PayOuts, verify that debit and credit transactions offset each other

PayIn Reconciliation

PayIns (collections) allow you to receive money into your Cobre Balance from payers. Cobre offers two PayIn methods:

Direct Link — Generate a payment link for a specific payer

CheckOut — Create a flexible payment page with multiple options

PayIn Request Structure

When creating a PayIn, you specify:

Field	Description	Required
`counterparty_id`	Payer information	✅ Yes
`destination_id`	Your Cobre Balance (where funds go)	✅ Yes
`amount`	Amount to collect	✅ Yes (or open amount for CheckOut)
`external_id`	Your unique reference for tracking	No, but recommended
`payment_methods`	Allowed payment methods	✅ Yes

PayIn Transaction Flow

Happy Path: Successful Collection (Direct Link)

┌─────────────────────────────────────┐
│  1. Create Direct Link              │
│  POST /v1/money_movements           │
│  • Amount: 10,000 COP               │
│  • External ID: ORDER-2025-050      │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Direct Link Created             │
│  • MM ID: mm_payin123abc            │
│  • Payment link URL generated       │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Payer Opens Link                │
│  • Chooses payment method           │
│  • Completes payment                │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Payment Confirmed               │
│  • MM Status: completed             │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  5. Credit Transaction Created      │
│  • TRX ID: trx_credit999xyz         │
│  • Type: credit                     │
│  • Amount: +10,000 COP              │
│  • Account: Destination Balance     │
└─────────────────────────────────────┘

Reconciliation Steps:

Direct Link Created:

Money Movement ID: mm_payin123abc

External ID: ORDER-2025-050

Amount: 10,000 COP

Status: pending

Payment URL: Shared with payer

Payer Completes Payment:

Payer uses the link to pay

Payment method processed successfully

Money Movement Status Updated:

Status changes to: completed

Credit Transaction Created (Only After Completion):

Transaction ID: trx_credit999xyz

Type: credit

Amount: +10,000 COP

Account Balance: Increased by 10,000 COP

Linked to Money Movement: mm_payin123abc

Final Status:

Money Movement Status: completed

Your Cobre Balance: Increased by 10,000 COP

Payer: Successfully paid

Reconciliation Record:

Money Movement ID	External ID	Type	Amount	Transactions	Final Balance Impact
`mm_payin123abc`	`ORDER-2025-050`	PayIn (Direct Link)	10,000 COP	1 credit (`trx_credit999xyz`)	+10,000 COP

Happy Path: Successful Collection (CheckOut)

┌─────────────────────────────────────┐
│  1. Create CheckOut                 │
│  POST /v1/checkouts                 │
│  • Amount: 10,000 COP (or open)     │
│  • External ID: INV-2025-150        │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. CheckOut Created                │
│  • CheckOut ID: chk_809821845       │
│  • Payment page URL generated       │
│  • Status: pending                  │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Payer Opens CheckOut            │
│  • Chooses payment method           │
│  • Enters amount (if open)          │
│  • Completes payment                │
│   MM ID: mm_checkout456def          │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Payment Confirmed               │
│  • MM Status: completed             │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  5. Credit Transaction Created      │
│  • TRX ID: trx_checkout888ghi       │
│  • Type: credit                     │
│  • Amount: +10,000 COP              │
│  • Account: Destination Balance     │
└─────────────────────────────────────┘

Reconciliation Steps: (Same as Direct Link)

The flow is identical to Direct Link, with the same transaction creation pattern:

Credit transaction is only created when status = completed

If payment fails or is rejected, no transaction is created

Reconciliation Record:

Money Movement ID	External ID	Type	Amount	Transactions	Final Balance Impact
`mm_checkout456def`	`INV-2025-150`	PayIn (CheckOut)	10,000 COP	1 credit (`trx_checkout888ghi`)	+10,000 COP

Alternative Path: Failed Collection

┌─────────────────────────────────────┐
│  1. Create Direct Link/CheckOut     │
│  • Amount: 10,000 COP               │
│  • External ID: ORDER-2025-999      │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Money Movement Created          │
│  • MM ID: mm_failed777ghi           │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Payer Attempts Payment          │
│  • Payment method fails             │
│  • Insufficient funds, etc.         │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Payment Rejected                │
│  • MM Status: rejected              │
│  • NO transaction created           │
└─────────────────────────────────────┘

Reconciliation Steps:

Money Movement Created:

Money Movement ID: mm_failed777ghi

External ID: ORDER-2025-999

Amount: 10,000 COP

Status: pending

Payment Failed:

Payer's payment method was declined

Status changes to: rejected

No Transaction Created:

Important: No credit transaction is generated

Your Cobre Balance remains unchanged

Final Status:

Money Movement Status: rejected

Your Cobre Balance: No change (0 COP impact)

Payer: Did not successfully pay

Reconciliation Record:

Money Movement ID	External ID	Type	Amount	Transactions	Final Balance Impact
`mm_failed777ghi`	`ORDER-2025-999`	PayIn	10,000 COP	0 transactions	0 COP (no funds received)

PayIn Reconciliation Best Practices

✅ Credit only on completion: Transactions are ONLY created when status = completed
✅ Track pending payments: Monitor processing status money movements for payer action
✅ Handle rejections: Money movements with rejected status will have 0 transactions
✅ Use external_id: Link to your orders, invoices, or customer records
✅ Webhook integration: Get notified when payers complete payments
✅ Reconcile by transaction: Use Transaction Report to verify all credits match completed money movements

Transaction Reports

Cobre provides Transaction Reports to facilitate reconciliation across all your money movements.

Report Structure

The follow fields in the layout report will help to do the reconciliation process:

Field	Description	Example
`id`	Unique transaction identifier	`trx_sjrirldkmk`
`metadata.money_movement_id`	Linked money movement	`mm_ady1n4g4ud`
`type`	Type of operation	`col_debit`, `col_credit`, `r2p_credit`
`credit_debit_type`	Debit or credit	`debit`, `credit`
`amount`	Transaction amount	`10000` (in minor units)
`currency`	Currency code	`COP`
`account_id`	Your Cobre Balance affected	`acc_123abc`
`metadata.mm_external_id`	Your reference	`INV-2025-001`
`created_at`	Transaction timestamp	`2024-06-24T15:37:38Z`

Querying Transaction Reports

API Endpoint:

GET /v1/reports

Example Request

Example Response:

{
  "id": "repo_kJs8GO03vC",
  "resource": "string",
  "start_date": "2024-09-28T00:00:00Z",
  "end_date": "2024-10-05T00:00:00Z",
  "offset": "-05:00",
  "requested_at": "2024-10-28T12:39:11Z",
  "created_at": "2024-10-28T12:39:11Z",
  "metadata": {
    "account_id": "acc_123456",
    "statement_date": "2025-05"
  },
  "file_name":"20240928_20241028_transactions_repo_kjs8go03vc.csv",
 "file_format": "csv",
 "file_layout": "transactions_csv_v1",
 "sensitive_data": false
}

Reconciliation Workflow

Step-by-Step Process

1. Download Transaction Report

2. Group by Money Movement ID

Organize transactions by their linked money movement:

Money Movement: mm_ady1n4g4ud
├─ Transaction 1: trx_sjrirldkmk (debit: -10,000 COP)
   
Money Movement: mm_xyz789def  
├─ Transaction 1: trx_abc123first (debit: -10,000 COP)
├─ Transaction 2: trx_abc123second (credit: +10,000 COP)

3. Match External IDs

Cross-reference external_id with your internal systems:

Cobre External ID: INV-2025-001
→ Matches Internal Invoice: INV-2025-001
→ Money Movement: mm_ady1n4g4ud
→ Net Impact: -10,000 COP

4. Verify Net Balance Impact

For PayOuts:

Completed: 1 debit transaction (net impact: negative)

Rejected: 1 debit + 1 credit transaction (net impact: zero)

For PayIns:

Completed: 1 credit transaction (net impact: positive)

Rejected: 0 transactions (net impact: zero)


---

## Reconciliation Formulas

### Expected Balance Calculation

Current Balance = Previous Balance + Credits - Debits


**Example:**

Previous Balance: 100,000 COP
Credits (PayIns): +50,000 COP
Debits (PayOuts): -30,000 COP
Current Balance: 100,000 + 50,000 - 30,000 = 120,000 COP


### Money Movement Transaction Count

**PayOut:**
- Completed: 1 transaction (debit)
- Rejected: 2 transactions (debit + credit reversal)

**PayIn:**
- Completed: 1 transaction (credit)
- Rejected: 0 transactions

---

## Common Reconciliation Scenarios

### Scenario 1: All PayOuts Successful

Money Movements: 5 PayOuts
Expected Transactions: 5 debits
Net Impact: -50,000 COP (sum of all PayOuts)


### Scenario 2: PayOut with Rejection

Money Movement: mm_rejected001
Transaction 1: -10,000 COP (debit)
Transaction 2: +10,000 COP (credit)
Net Impact: 0 COP
Status: rejected


### Scenario 3: PayIn Completed

Money Movement: mm_payin001
Transaction 1: +25,000 COP (credit)
Net Impact: +25,000 COP
Status: completed


### Scenario 4: PayIn Pending (No Payment Yet)

Money Movement: mm_pending001
Transactions: 0
Net Impact: 0 COP
Status: pending
Action: Wait for payer to complete payment


---

## Troubleshooting

### Issue 1: Missing External ID in Report
**Problem:** Transaction shows null `external_id`  
**Cause:** External ID not provided in money movement creation  
**Solution:** Always include `external_id` in your API requests

### Issue 2: Balance Mismatch
**Problem:** Calculated balance doesn't match actual balance  
**Cause:** Missing transactions or unreported reversals  
**Solution:** 
1. Query full transaction history for the period
2. Check for rejected money movements (2 transactions each)
3. Verify all money movement statuses

### Issue 3: Duplicate Reconciliation
**Problem:** Same transaction reconciled twice  
**Cause:** Using non-unique `external_id`  
**Solution:** Ensure `external_id` is unique per money movement

### Issue 4: PayIn with No Transaction
**Problem:** Completed PayIn has no credit transaction  
**Cause:** Money movement status is not `completed`  
**Solution:** Check money movement status; transactions only created on `completed`

---

## API Endpoints Reference

### Create PayOut

POST /v1/money_movements


### Create Direct Link (PayIn)

POST /v1/money_movements


### Create CheckOut (PayIn)

POST /v1/checkouts


### Get Money Movement Status

GET /v1/money_movements/{money_movement_id}


### Get Transaction Details

GET /v1/transactions/{transaction_id}


### Download Transaction Report

GET /v1/reports


---

## Key Takeaways

✅ **Every money movement has a unique ID** — Use `money_movement_id` as primary identifier  
✅ **External IDs are critical** — Always provide `external_id` for reconciliation  
✅ **Transaction timing differs** — PayOuts create instant debits; PayIns create credits only on completion  
✅ **Rejections create reversals** — PayOut rejections generate 2 transactions (debit + credit)  
✅ **Use Transaction Reports** — Download reports by date range for bulk reconciliation  
✅ **Monitor status changes** — Subscribe to webhooks for real-time reconciliation updates  
✅ **Net balance formula** — Completed PayOuts = -amount, Completed PayIns = +amount, Rejections = 0  

---

Reconciliation with Cobre Reports in Colombia

Overview#

Core Concepts#

Money Movement vs Transaction#

Identification Methods#

1. Money Movement ID (Cobre-generated)#

2. External ID (Client-provided)#

PayOut Reconciliation#

PayOut Request Structure#

PayOut Transaction Flow#

Happy Path: Successful Disbursement#

Alternative Path: Rejected Disbursement#

PayOut Reconciliation Best Practices#

PayIn Reconciliation#

PayIn Request Structure#

PayIn Transaction Flow#

Happy Path: Successful Collection (Direct Link)#

Happy Path: Successful Collection (CheckOut)#

Alternative Path: Failed Collection#

PayIn Reconciliation Best Practices#

Transaction Reports#

Report Structure#

Querying Transaction Reports#

Reconciliation Workflow#

Step-by-Step Process#

1. Download Transaction Report#

2. Group by Money Movement ID#

3. Match External IDs#

4. Verify Net Balance Impact#

Overview

Core Concepts

Money Movement vs Transaction

Identification Methods

1. Money Movement ID (Cobre-generated)

2. External ID (Client-provided)

PayOut Reconciliation

PayOut Request Structure

PayOut Transaction Flow

Happy Path: Successful Disbursement

Alternative Path: Rejected Disbursement

PayOut Reconciliation Best Practices

PayIn Reconciliation

PayIn Request Structure

PayIn Transaction Flow

Happy Path: Successful Collection (Direct Link)

Happy Path: Successful Collection (CheckOut)

Alternative Path: Failed Collection

PayIn Reconciliation Best Practices

Transaction Reports

Report Structure

Querying Transaction Reports

Reconciliation Workflow

Step-by-Step Process

1. Download Transaction Report

2. Group by Money Movement ID

3. Match External IDs

4. Verify Net Balance Impact