Step 1 of 40 Configuration API step

Authenticate

Exchange API credentials for a short-lived Bearer token (~20 minutes). Cache and reuse it across calls — refresh proactively before expiry.

POST https://api.cobre.co/v1/auth
Headers
Content-Typeapplication/json
Request body
{
"user_id": "cli_fxpsp_lac01",User IDRequirediAPI client user id used to obtain the access token.
"secret": "sk_live_Fx8pQmT3rW"SecretRequirediAPI client secret paired with user_id for authentication.
}
Response 201
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN",Access TokeniShort-lived bearer token. Attach as Authorization: Bearer on later calls.
"type": "Bearer",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"expiration_time": 1200Expiration TimeiToken lifetime in seconds.
}
Documentation for this step
AuthenticationAuthentication Guide
Step 2 of 40 Configuration API step

Subscribe to Platform Events

Register webhooks for the wallet lifecycle, Cross-Border Money Movement lifecycle, local Money Movement status, and balance credits/debits across all three balances. Prefer events over polling; verify HMAC-SHA256 signatures on every delivery.

POST https://api.cobre.co/v1/subscriptions
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"url": "https://fxpsp.example.com/webhooks/cobre",Notification URLRequirediHTTPS URL used by this resource (e.g. webhook endpoint).
"description": "FX/stablecoin PSP lifecycle events",DescriptioniHuman-readable label or note.
"events": [EventsiList of webhook event types this subscription listens to.
"self_custodian_wallet.status.enabled",
"cross_border_money_movements.status.initiated",
"cross_border_money_movements.status.processing",
"cross_border_money_movements.status.completed",
"cross_border_money_movements.status.rejected",
"money_movements.status.initiated",
"money_movements.status.processing",
"money_movements.status.completed",
"money_movements.status.rejected",
"money_movements.status.failed",
"money_movements.status.returned",
"accounts.balance.credit",
"accounts.balance.debit"
],
"event_signature_key": "WHfxpsp7yK"Signature keyRequirediSecret you set on the subscription; Cobre uses it to HMAC-SHA256-sign deliveries (verify via event-signature + event-timestamp headers).
}
Response 201
{
"id": "sub_FxPspCb01",IdiUnique Cobre identifier for this resource.
"url": "https://fxpsp.example.com/webhooks/cobre",Notification URLRequirediHTTPS URL used by this resource (e.g. webhook endpoint).
"description": "FX/stablecoin PSP lifecycle events",DescriptioniHuman-readable label or note.
"events": [EventsiList of webhook event types this subscription listens to.
"self_custodian_wallet.status.enabled",
"cross_border_money_movements.status.initiated",
"cross_border_money_movements.status.processing",
"cross_border_money_movements.status.completed",
"cross_border_money_movements.status.rejected",
"money_movements.status.initiated",
"money_movements.status.processing",
"money_movements.status.completed",
"money_movements.status.rejected",
"money_movements.status.failed",
"money_movements.status.returned",
"accounts.balance.credit",
"accounts.balance.debit"
],
"event_signature_key": "******7yK",Signature keyRequirediSecret you set on the subscription; Cobre uses it to HMAC-SHA256-sign deliveries (verify via event-signature + event-timestamp headers).
"created_at": "2026-08-01T09:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).
}
Documentation for this step
Subscribe to EventsNotifications & Subscriptions
Step 3 of 40 Configuration API step

Create USD Global Cobre Balance

Provision the USD Global Cobre Balance that receives stablecoin payins, funds every FX conversion (Cross-Border source_id), and pays stablecoin payouts. Request US funding instructions from your KAM after creation.

POST https://api.cobre.co/v1/accounts
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"provider_id": "pr_global_cobre",ProviderRequirediCobre field at "provider_id" in this payload.
"action": "create",ActionRequirediCobre field at "action" in this payload.
"alias": "FX/Stablecoin Treasury — USD Global"AliasiDisplay name that helps identify it and clarify its purpose.
}
Response 201
{
"id": "acc_FxGlobalUsd01",IdiUnique Cobre identifier for this resource.
"provider_id": "pr_global_cobre",ProviderRequirediCobre field at "provider_id" in this payload.
"provider_name": "Cobre Balance Global",Provider NameiCobre field at "provider_name" in this payload.
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "connected",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"alias": "FX/Stablecoin Treasury — USD Global",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload.
"mm_push_from_account"
],
"cobre_tag": "@fxpsp0001"Cobre TagiCobre Balance tag identifying the destination account.
},
"account_number": "",Account NumberiBank account or CLABE number for the counterparty.
"account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload.
"obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload.
"obtained_balance_at": "2026-08-01T09:05:00Z",Obtained Balance AtiCobre field at "obtained_balance_at" in this payload.
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"tags": [],TagsiCobre field at "tags" in this payload.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"created_at": "2026-08-01T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T09:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create or Connect an AccountManaging Cobre Balances
Step 4 of 40 Configuration API step

Create MXN Treasury Cobre Balance

Provision the MXN Cobre Balance that receives converted funds (Cross-Border destination_id) and funds every Named Account before local delivery.

POST https://api.cobre.co/v1/accounts
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"provider_id": "pr_mex_cobre3",ProviderRequirediCobre field at "provider_id" in this payload.
"action": "create",ActionRequirediCobre field at "action" in this payload.
"alias": "MXN Treasury Balance"AliasiDisplay name that helps identify it and clarify its purpose.
}
Response 201
{
"id": "acc_FxMxnTreasury01",IdiUnique Cobre identifier for this resource.
"provider_id": "pr_mex_cobre3",ProviderRequirediCobre field at "provider_id" in this payload.
"provider_name": "Cobre Balance Mexico",Provider NameiCobre field at "provider_name" in this payload.
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "connected",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"alias": "MXN Treasury Balance",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload.
"mm_push_from_account"
]
},
"account_number": "",Account NumberiBank account or CLABE number for the counterparty.
"account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload.
"obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload.
"obtained_balance_at": "2026-08-01T09:06:00Z",Obtained Balance AtiCobre field at "obtained_balance_at" in this payload.
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"tags": [],TagsiCobre field at "tags" in this payload.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"created_at": "2026-08-01T09:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T09:06:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create or Connect an AccountManaging Cobre Balances
Step 5 of 40 Configuration API step

Create COP Treasury Cobre Balance

Provision the COP Cobre Balance that receives converted funds (Cross-Border destination_id) and funds local payouts over Bre-B, Fast Pay, and ACH.

POST https://api.cobre.co/v1/accounts
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"provider_id": "pr_col_cobre",ProviderRequirediCobre field at "provider_id" in this payload.
"action": "create",ActionRequirediCobre field at "action" in this payload.
"alias": "COP Treasury Balance"AliasiDisplay name that helps identify it and clarify its purpose.
}
Response 201
{
"id": "acc_FxCopTreasury01",IdiUnique Cobre identifier for this resource.
"provider_id": "pr_col_cobre",ProviderRequirediCobre field at "provider_id" in this payload.
"provider_name": "Cobre Balance Colombia",Provider NameiCobre field at "provider_name" in this payload.
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "connected",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"alias": "COP Treasury Balance",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload.
"mm_push_from_account"
]
},
"account_number": "",Account NumberiBank account or CLABE number for the counterparty.
"account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload.
"obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload.
"obtained_balance_at": "2026-08-01T09:07:00Z",Obtained Balance AtiCobre field at "obtained_balance_at" in this payload.
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"tags": [],TagsiCobre field at "tags" in this payload.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"created_at": "2026-08-01T09:07:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T09:07:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create or Connect an AccountManaging Cobre Balances
Step 6 of 40 Stablecoin Treasury API step

Create self_custodian_wallet Reference

Provision a receiving wallet on the USD Global balance. Share value with the sender once connectivity.status is enabled.

POST https://api.cobre.co/v1/account_references
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"source_id": "acc_FxGlobalUsd01",Global balanceRequirediCobre id of the source account or counterparty.
"type": "self_custodian_wallet",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"chain": "evm_compatible"ChainRequirediCobre field at "metadata.chain" in this payload.
},
"alias": "USDT/USDC Receiving Wallet"AliasiDisplay name that helps identify it and clarify its purpose.
}
Response 200
{
"id": "ref_FxStableWallet01",IdiUnique Cobre identifier for this resource.
"alias": "USDT/USDC Receiving Wallet",AliasiDisplay name that helps identify it and clarify its purpose.
"type": "self_custodian_wallet",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"value": "0x8fC2a4B1D6e9F03c5A7b2E4d1C9f6A0b3D8e5F21",ValueiCobre field at "value" in this payload.
"source_id": "acc_FxGlobalUsd01",Global balanceRequirediCobre id of the source account or counterparty.
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "processing",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"chain": "evm_compatible",ChainRequirediCobre field at "metadata.chain" in this payload.
"chain_assets": [Chain AssetsiCobre field at "metadata.chain_assets" in this payload.
"usdt",
"usdc"
]
},
"created_at": "2026-08-01T10:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T10:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create an Account ReferenceStablecoin Payins
Step 7 of 40 Stablecoin Treasury API step

Wallet Enabled (Webhook)

When self_custodian_wallet.status.enabled fires, read value and share the on-chain address with the sender (the end client remitting USDT/USDC).

GET https://api.cobre.co/v1/account_references/ref_FxStableWallet01
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Response 200
{
"id": "ref_FxStableWallet01",Reference IDRequirediUnique Cobre identifier for this resource.
"alias": "USDT/USDC Receiving Wallet",AliasiDisplay name that helps identify it and clarify its purpose.
"type": "self_custodian_wallet",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"value": "0x8fC2a4B1D6e9F03c5A7b2E4d1C9f6A0b3D8e5F21",Wallet addressRequirediCobre field at "value" in this payload.
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "enabled",StatusRequirediLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"chain": "evm_compatible",ChainiCobre field at "metadata.chain" in this payload.
"chain_assets": [Chain AssetsiCobre field at "metadata.chain_assets" in this payload.
"usdt",
"usdc"
]
},
"created_at": "2026-08-01T10:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook delivered

self_custodian_wallet.status.enabled

Wallet is ready — share value with the USDT/USDC sender.

Headers
Content-Typeapplication/json
Payload
{
"id": "ev_FxWalletEnabled01",IdiUnique Cobre identifier for this resource.
"event_key": "self_custodian_wallet.status.enabled",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "ref_FxStableWallet01",IdiUnique Cobre identifier for this resource.
"alias": "USDT/USDC Receiving Wallet",AliasiDisplay name that helps identify it and clarify its purpose.
"type": "self_custodian_wallet",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"value": "0x8fC2a4B1D6e9F03c5A7b2E4d1C9f6A0b3D8e5F21",ValueiCobre field at "content.value" in this payload.
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "enabled",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"chain": "evm_compatible",ChainiMetadata field "chain" attached to the resource.
"chain_assets": [Chain AssetsiMetadata field "chain_assets" attached to the resource.
"usdt",
"usdc"
]
},
"created_at": "2026-08-01T10:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
List one Account ReferenceObtain one Account ReferenceSelf-custodian wallet
Step 8 of 40 Stablecoin Treasury API step

Stablecoin Credited as USD

On-chain deposit approved — the USD Global balance receives global_credit (USD). Confirm via accounts.balance.credit or GET /accounts/{acct_id}/transactions.

GET https://api.cobre.co/v1/accounts/acc_FxGlobalUsd01Global balanceRequiredi/transactions
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Response 200
{
"total_items": 1,Total ItemsiTotal items matching the query across all pages.
"total_pages": 1,Total PagesiNumber of pages in this result set.
"is_last_page": true,Is Last PageiTrue when this is the final page of results.
"page_items": 1,Page ItemsiNumber of items returned on this page.
"contents": [ContentsiArray of result objects for this page.
{
"id": "trx_FxGlobalCredit01",Transaction IDiUnique Cobre identifier for this resource.
"type": "global_credit",Transaction typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxGlobalUsd01",Account IdiCobre Balance account id affected by the event.
"amount": 250000,Amount creditedRequirediAmount in cents — the last two digits are decimals.
"previous_balance": 0,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload.
"current_balance": 250000,Current BalanceiCobre field at "contents.0.current_balance" in this payload.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T11:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T11:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"tracking_key": "0xdef789abc123stablepayinfxpsp",On-chain hashiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"description": "USDT payin credited as USD"DescriptioniHuman-readable label or note.
}
}
]
}
⚡

Webhook delivered

accounts.balance.credit

USD Global balance credited after stablecoin screening approval.

Headers
Content-Typeapplication/json
Payload
{
"id": "ev_FxGlobalCredit01",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T11:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxGlobalCredit01",IdiUnique Cobre identifier for this resource.
"type": "global_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"amount": 250000,AmountiAmount in cents — the last two digits are decimals.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"date": "2026-08-01T11:00:00Z",DateiTimestamp when the balance transaction was posted (ISO 8601, UTC) — used in accounts.balance.* webhook notifications.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"tracking_key": "0xdef789abc123stablepayinfxpsp",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"description": "USDT payin credited as USD"DescriptioniHuman-readable label or note.
},
"account_id": "acc_FxGlobalUsd01",Account IdiCobre Balance account id affected by the event.
"previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 250000,Current BalanceiCobre field at "content.current_balance" in this payload.
"credit_debit_type": "credit"Credit Debit Typeicredit = funds in; debit = funds out.
}
}
Documentation for this step
Obtain one Account TransactionsStablecoin Payins
Step 9 of 40 Stablecoin Treasury Reconciliation

Reconcile the Stablecoin Payin

Match the accounts.balance.credit webhook to your treasury ledger on the on-chain tracking_key and the Cobre transaction id.

Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueTreasury ledger field
content.metadata.tracking_key
0xdef789abc123stablepayinfxpsp
 →
onchain_tx_hash
content.id
trx_FxGlobalCredit01
 →
cobre_transaction_id
content.amount
250000
 →
usd_credited_cents
250000 = $2,500.00 USD credited to the Global balance.
Step 10 of 40 Stablecoin Treasury API step

Create Global Counterparty

Register the USDT beneficiary as global_deposit_np. A stablecoin payout requires counterparty_verification_status verified.

POST https://api.cobre.co/v1/counterparties
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"geo": "usa",GeographyRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "global_deposit_np",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "USDT beneficiary",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"counterparty_firstname": "Jordan",First nameRequirediCobre field at "metadata.counterparty_firstname" in this payload.
"counterparty_lastname": "Reyes",Last nameRequirediCobre field at "metadata.counterparty_lastname" in this payload.
"counterparty_date_of_birth": "1988-03-22",Date of birthRequirediCobre field at "metadata.counterparty_date_of_birth" in this payload.
"counterparty_id_nationality": "USA",NationalityRequirediCobre field at "metadata.counterparty_id_nationality" in this payload.
"counterparty_chain": "tron",ChainRequirediCobre field at "metadata.counterparty_chain" in this payload.
"counterparty_wallet_address": "TQn9Y2khEsLMWD8ZBfxpspPayout99",Wallet addressRequirediCobre field at "metadata.counterparty_wallet_address" in this payload.
"counterparty_address": {Counterparty AddressiCobre field at "metadata.counterparty_address" in this payload.
"street_line1": "200 Demo Ave",Street Line1iCobre field at "metadata.counterparty_address.street_line1" in this payload.
"city": "Miami",CityiCobre field at "metadata.counterparty_address.city" in this payload.
"state": "FL",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"postal_code": "33131",Postal CodeiCobre field at "metadata.counterparty_address.postal_code" in this payload.
"country": "USA"CountryRequirediCobre field at "metadata.counterparty_address.country" in this payload.
}
}
}
Response 201
{
"id": "cp_FxGlobalUsdt01",IdiUnique Cobre identifier for this resource.
"geo": "global",GeographyRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "global_deposit_np",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "USDT beneficiary",AliasiDisplay name that helps identify it and clarify its purpose.
"counterparty_firstname": "Jordan",First nameRequirediCobre field at "counterparty_firstname" in this payload.
"counterparty_lastname": "Reyes",Last nameRequirediCobre field at "counterparty_lastname" in this payload.
"counterparty_date_of_birth": "1988-03-22",Date of birthRequirediCobre field at "counterparty_date_of_birth" in this payload.
"counterparty_id_nationality": "USA",NationalityRequirediCobre field at "counterparty_id_nationality" in this payload.
"counterparty_chain": "tron",ChainRequirediCobre field at "counterparty_chain" in this payload.
"counterparty_wallet_address": "TQn9Y2khEsLMWD8ZBfxpspPayout99",Wallet addressRequirediCobre field at "counterparty_wallet_address" in this payload.
"counterparty_address": {Counterparty AddressiCobre field at "counterparty_address" in this payload.
"street_line1": "200 Demo Ave",Street Line1iCobre field at "counterparty_address.street_line1" in this payload.
"city": "Miami",CityiCobre field at "counterparty_address.city" in this payload.
"state": "FL",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"postal_code": "33131",Postal CodeiCobre field at "counterparty_address.postal_code" in this payload.
"country": "USA"CountryiCobre field at "counterparty_address.country" in this payload.
},
"counterparty_verification_status": "processing",Counterparty Verification StatusiCobre field at "counterparty_verification_status" in this payload.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"counterparty_firstname": "Jordan",First nameRequirediCobre field at "metadata.counterparty_firstname" in this payload.
"counterparty_lastname": "Reyes",Last nameRequirediCobre field at "metadata.counterparty_lastname" in this payload.
"counterparty_date_of_birth": "1988-03-22",Date of birthRequirediCobre field at "metadata.counterparty_date_of_birth" in this payload.
"counterparty_id_nationality": "USA",NationalityRequirediCobre field at "metadata.counterparty_id_nationality" in this payload.
"counterparty_chain": "tron",ChainRequirediCobre field at "metadata.counterparty_chain" in this payload.
"counterparty_wallet_address": "TQn9Y2khEsLMWD8ZBfxpspPayout99"Wallet addressRequirediCobre field at "metadata.counterparty_wallet_address" in this payload.
},
"created_at": "2026-08-01T11:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T11:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create a CounterpartyGlobal Payouts in Stablecoins
Step 11 of 40 Stablecoin Treasury API step

Send USDT Payout

Pay from the USD Global balance to the verified Global Counterparty. metadata.token=usdt triggers fiat→stablecoin settlement on-chain.

POST https://api.cobre.co/v1/money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx-usdt-payout-001
Request body
{
"source_id": "acc_FxGlobalUsd01",Global balanceRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxGlobalUsdt01",Global counterpartyRequirediCobre id of the destination account or counterparty.
"amount": 75000,Amount (USD cents)RequirediAmount in cents — the last two digits are decimals.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"token": "usdt",TokenRequirediCobre field at "metadata.token" in this payload.
"description": "Stablecoin settlement payout"DescriptioniHuman-readable label or note.
},
"external_id": "fx_usdt_payout_001"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "mm_FxUsdtPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"token": "usdt",TokenRequirediCobre field at "metadata.token" in this payload.
"description": "Stablecoin settlement payout"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_usdt_payout_001",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fedwire",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxGlobalUsd01",Global balanceRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxGlobalUsdt01",Global counterpartyRequirediCobre id of the destination account or counterparty.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 75000,Amount (USD cents)RequirediAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T11:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T11:15:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Money movement

USDT payout completed on-chain to the beneficiary wallet.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxUsdtPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T11:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxUsdtPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"token": "usdt",TokeniMetadata field "token" attached to the resource.
"description": "Stablecoin settlement payout"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_usdt_payout_001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fedwire",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxGlobalUsdt01",Destination IdiCobre id of the destination account or counterparty.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 75000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T11:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T11:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxUsdtPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T11:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxUsdtPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"token": "usdt",TokeniMetadata field "token" attached to the resource.
"description": "Stablecoin settlement payout"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_usdt_payout_001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fedwire",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxGlobalUsdt01",Destination IdiCobre id of the destination account or counterparty.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 75000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T11:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T11:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R015Account not authorized to be credited.Payout
R018Payment rejected due invalid key.Payout
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R085Bank processing error.Payout
Event money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxUsdtPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T11:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxUsdtPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R018",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"token": "usdt",TokeniMetadata field "token" attached to the resource.
"description": "Stablecoin settlement payout"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_usdt_payout_001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fedwire",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxGlobalUsdt01",Destination IdiCobre id of the destination account or counterparty.
"currency": "usd",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 75000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T11:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T11:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
Create a Money MovementGlobal Payouts in Stablecoins
Step 12 of 40 Stablecoin Treasury Reconciliation

Reconcile the Stablecoin Payout

Close the USDT payout leg on your treasury ledger using external_id and the Money Movement id.

Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueTreasury ledger field
content.external_id
fx_usdt_payout_001
 →
payout_external_id
content.id
mm_FxUsdtPayout01
 →
cobre_mm_id
content.status.state
completed
 →
payout_status
Map completed → paid; rejected/failed → retry or refund.
Step 13 of 40 Cross-Border FX API step

Request USD/MXN Quote

Request a short-lived USD/MXN quote before converting Global USD into the MXN Treasury Balance. For a static quote, USD must already sit in the Global Balance. Quotes expire in ~1 minute; persist fxq_id.

POST https://api.cobre.co/v1/fx_quotes
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"currency_pair": "usd/mxn",Currency pairRequirediCobre field at "currency_pair" in this payload.
"destination_amount": 9000000,Destination amount (no decimals)RequirediCobre field at "destination_amount" in this payload.
"type": "static_quote"Quote typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
}
Response 201
{
"id": "fxq_FxUsdMxn01",IdiUnique Cobre identifier for this resource.
"type": "static_quote",Quote typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/mxn",Currency pairRequirediCobre field at "currency_pair" in this payload.
"source_amount": 500000,Source AmountiCobre field at "source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "fees_breakdown" in this payload.
"spread": 1SpreadiCobre field at "fees_breakdown.spread" in this payload.
},
"fx_rate": 18,Fx RateiCobre field at "fx_rate" in this payload.
"destination_amount": 9000000,Destination amount (no decimals)RequirediCobre field at "destination_amount" in this payload.
"quota_limit": 2000000000,Quota LimitiCobre field at "quota_limit" in this payload.
"remaining_quota": 1991000000,Remaining QuotaiCobre field at "remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "off_market" in this payload.
}
Documentation for this step
Create a FX QuoteCreate FX QuotesCross Border Payments
Step 14 of 40 Cross-Border FX API step

Execute USD/MXN Conversion

After confirmation, convert USD to MXN by debiting the USD Global Balance and crediting the MXN Treasury Balance. Reuse the idempotency header on retries (valid 24h).

POST https://api.cobre.co/v1/cross_border_money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx_usdmxn_000123
Request body
{
"source_id": "acc_FxGlobalUsd01",USD Global BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxMxnTreasury01",MXN Treasury BalanceRequirediCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdMxn01",FX Quote IDRequirediCobre field at "forex_quote_id" in this payload.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to MXN treasury funding"DescriptioniCobre field at "metadata.destination_description" in this payload.
},
"external_id": "fx_usdmxn_000123"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "mm_CbmmUsdMxn01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdmxn_000123",External IDiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"source_id": "acc_FxGlobalUsd01",USD Global BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxMxnTreasury01",MXN Treasury BalanceRequirediCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdMxn01",FX Quote IDRequirediCobre field at "forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/mxn",Currency PairiCobre field at "forex_quote.currency_pair" in this payload.
"source_amount": 500000,Source AmountiCobre field at "forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "forex_quote.fees_breakdown" in this payload.
"spread": 1SpreadiCobre field at "forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 18,Fx RateiCobre field at "forex_quote.fx_rate" in this payload.
"destination_amount": 9000000,Destination AmountiCobre field at "forex_quote.destination_amount" in this payload.
"quota_limit": 2000000000,Quota LimitiCobre field at "forex_quote.quota_limit" in this payload.
"remaining_quota": 1991000000,Remaining QuotaiCobre field at "forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "forex_quote.off_market" in this payload.
},
"geo": "usa/mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to MXN treasury funding"DescriptioniCobre field at "metadata.destination_description" in this payload.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:10Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Cross-border money movement

USD→MXN conversion completed — MXN is now available on the MXN Treasury Balance, ready to fund Named Accounts.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event cross_border_money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmUsdMxn01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmUsdMxn01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdmxn_000123",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxMxnTreasury01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdMxn01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/mxn",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 500000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 18,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 9000000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 2000000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 1991000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "usa/mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to MXN treasury funding"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F003R2P Payment link expired.Payin
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event cross_border_money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmUsdMxn01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmUsdMxn01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdmxn_000123",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxMxnTreasury01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdMxn01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/mxn",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 500000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 18,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 9000000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 2000000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 1991000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "usa/mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to MXN treasury funding"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R012The user has abandoned the transaction.Payin
R015Account not authorized to be credited.Payout
R016Payment rejected due to timeout.Payin
R017Payment rejected due to expired money movement.Payin
R018Payment rejected due invalid key.Payout
R019Payment rejected due to incorrect amount.Payin
R020Payment rejected due to user authentication failure.Payin
R021Insufficient funds in payer account.Payin
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R081The counterparty registration has expired.Payin
R082The counterparty registration has been canceled.Payin
R084The counterparty registration has been rejected.Payin
R085Bank processing error.Payout
Event cross_border_money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmUsdMxn01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmUsdMxn01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdmxn_000123",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Inactive or blocked account."DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxMxnTreasury01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdMxn01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/mxn",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 500000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 18,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 9000000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 2000000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 1991000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "usa/mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to MXN treasury funding"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
Create a Cross Border Money MovementCreate a Cross-Border Money Movement
Step 15 of 40 Cross-Border FX Reconciliation

Reconcile the USD/MXN Conversion

Match the Cross-Border completion webhook to your treasury ledger on external_id and cbmm_id.

Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueTreasury ledger field
content.external_id
fx_usdmxn_000123
 →
fx_external_id
content.id
mm_CbmmUsdMxn01
 →
cbmm_id
content.forex_quote_id
fxq_FxUsdMxn01
 →
fxq_id
content.status.state
completed
 →
fx_status
Step 16 of 40 Cross-Border FX API step

Request USD/COP Quote

Request a short-lived USD/COP quote before converting Global USD into the COP Treasury Balance. For a static quote, USD must already sit in the Global Balance. Quotes expire in ~1 minute; persist fxq_id.

POST https://api.cobre.co/v1/fx_quotes
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"currency_pair": "usd/cop",Currency pairRequirediCobre field at "currency_pair" in this payload.
"destination_amount": 200000000,Destination amount (no decimals)RequirediCobre field at "destination_amount" in this payload.
"type": "static_quote"Quote typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
}
Response 201
{
"id": "fxq_FxUsdCop01",IdiUnique Cobre identifier for this resource.
"type": "static_quote",Quote typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/cop",Currency pairRequirediCobre field at "currency_pair" in this payload.
"source_amount": 50000,Source AmountiCobre field at "source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "fx_rate" in this payload.
"destination_amount": 200000000,Destination amount (no decimals)RequirediCobre field at "destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "quota_limit" in this payload.
"remaining_quota": 95000000,Remaining QuotaiCobre field at "remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "off_market" in this payload.
}
Documentation for this step
Create a FX QuoteCreate FX QuotesCross Border Payments
Step 17 of 40 Cross-Border FX API step

Execute USD/COP Conversion

After confirmation, convert USD to COP by debiting the USD Global Balance and crediting the COP Treasury Balance. Reuse the idempotency header on retries (valid 24h).

POST https://api.cobre.co/v1/cross_border_money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx_usdcop_000456
Request body
{
"source_id": "acc_FxGlobalUsd01",USD Global BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdCop01",FX Quote IDRequirediCobre field at "forex_quote_id" in this payload.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to COP treasury funding"DescriptioniCobre field at "metadata.destination_description" in this payload.
},
"external_id": "fx_usdcop_000456"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "mm_CbmmUsdCop01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdcop_000456",External IDiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"source_id": "acc_FxGlobalUsd01",USD Global BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdCop01",FX Quote IDRequirediCobre field at "forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/cop",Currency PairiCobre field at "forex_quote.currency_pair" in this payload.
"source_amount": 50000,Source AmountiCobre field at "forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "forex_quote.fx_rate" in this payload.
"destination_amount": 200000000,Destination AmountiCobre field at "forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "forex_quote.quota_limit" in this payload.
"remaining_quota": 95000000,Remaining QuotaiCobre field at "forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "forex_quote.off_market" in this payload.
},
"geo": "usa/col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to COP treasury funding"DescriptioniCobre field at "metadata.destination_description" in this payload.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:10Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Cross-border money movement

USD→COP conversion completed — COP is now available on the COP Treasury Balance, ready for local delivery over Bre-B, Fast Pay, or ACH.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event cross_border_money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmUsdCop01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmUsdCop01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdcop_000456",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxCopTreasury01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdCop01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/cop",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 50000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 200000000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 95000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "usa/col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to COP treasury funding"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F003R2P Payment link expired.Payin
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event cross_border_money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmUsdCop01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmUsdCop01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdcop_000456",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxCopTreasury01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdCop01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/cop",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 50000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 200000000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 95000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "usa/col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to COP treasury funding"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R012The user has abandoned the transaction.Payin
R015Account not authorized to be credited.Payout
R016Payment rejected due to timeout.Payin
R017Payment rejected due to expired money movement.Payin
R018Payment rejected due invalid key.Payout
R019Payment rejected due to incorrect amount.Payin
R020Payment rejected due to user authentication failure.Payin
R021Insufficient funds in payer account.Payin
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R081The counterparty registration has expired.Payin
R082The counterparty registration has been canceled.Payin
R084The counterparty registration has been rejected.Payin
R085Bank processing error.Payout
Event cross_border_money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmUsdCop01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmUsdCop01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_usdcop_000456",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Inactive or blocked account."DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxGlobalUsd01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxCopTreasury01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxUsdCop01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "usd/cop",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 50000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 200000000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 95000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "usa/col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "USD to COP treasury funding"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
Create a Cross Border Money MovementCreate a Cross-Border Money Movement
Step 18 of 40 Cross-Border FX Reconciliation

Reconcile the USD/COP Conversion

Match the Cross-Border completion webhook to your treasury ledger on external_id and cbmm_id.

Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueTreasury ledger field
content.external_id
fx_usdcop_000456
 →
fx_external_id
content.id
mm_CbmmUsdCop01
 →
cbmm_id
content.forex_quote_id
fxq_FxUsdCop01
 →
fxq_id
content.status.state
completed
 →
fx_status
Step 19 of 40 Cross-Border FX API step

Request COP/USD (Rebalancing) Quote

Cobre also quotes the reverse corridor: request a COP/USD quote to repatriate idle COP liquidity back into the USD Global Balance. Same static_quote / rolling_quote mechanics, with source_id and destination_id swapped relative to the forward leg.

POST https://api.cobre.co/v1/fx_quotes
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"currency_pair": "cop/usd",Currency pairRequirediCobre field at "currency_pair" in this payload.
"destination_amount": 10000,Destination amount (no decimals)RequirediCobre field at "destination_amount" in this payload.
"type": "static_quote"Quote typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
}
Response 201
{
"id": "fxq_FxCopUsd01",IdiUnique Cobre identifier for this resource.
"type": "static_quote",Quote typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "cop/usd",Currency pairRequirediCobre field at "currency_pair" in this payload.
"source_amount": 40000000,Source AmountiCobre field at "source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "fx_rate" in this payload.
"destination_amount": 10000,Destination amount (no decimals)RequirediCobre field at "destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "quota_limit" in this payload.
"remaining_quota": 60000000,Remaining QuotaiCobre field at "remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "off_market" in this payload.
}
Documentation for this step
Create a FX QuoteCreate FX QuotesCross Border Payments
Step 20 of 40 Cross-Border FX API step

Execute COP/USD (Rebalancing) Conversion

Convert COP back to USD by debiting the COP Treasury Balance and crediting the USD Global Balance — the same cross_border_money_movements endpoint used for the forward legs, direction reversed for treasury rebalancing.

POST https://api.cobre.co/v1/cross_border_money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx_copusd_rebal001
Request body
{
"source_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxGlobalUsd01",USD Global BalanceRequirediCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxCopUsd01",FX Quote IDRequirediCobre field at "forex_quote_id" in this payload.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "COP to USD treasury rebalancing"DescriptioniCobre field at "metadata.destination_description" in this payload.
},
"external_id": "fx_copusd_rebal001"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "mm_CbmmCopUsd01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_copusd_rebal001",External IDiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"source_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxGlobalUsd01",USD Global BalanceRequirediCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxCopUsd01",FX Quote IDRequirediCobre field at "forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "cop/usd",Currency PairiCobre field at "forex_quote.currency_pair" in this payload.
"source_amount": 40000000,Source AmountiCobre field at "forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "forex_quote.fx_rate" in this payload.
"destination_amount": 10000,Destination AmountiCobre field at "forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "forex_quote.quota_limit" in this payload.
"remaining_quota": 60000000,Remaining QuotaiCobre field at "forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "forex_quote.off_market" in this payload.
},
"geo": "col/usa",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "COP to USD treasury rebalancing"DescriptioniCobre field at "metadata.destination_description" in this payload.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:10Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Cross-border money movement

COP→USD rebalancing completed — idle COP liquidity is now back on the USD Global Balance, available for stablecoin payouts or re-conversion to any local corridor.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event cross_border_money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmCopUsd01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmCopUsd01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_copusd_rebal001",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxGlobalUsd01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxCopUsd01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "cop/usd",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 40000000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 10000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 60000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "col/usa",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "COP to USD treasury rebalancing"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F003R2P Payment link expired.Payin
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event cross_border_money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmCopUsd01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmCopUsd01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_copusd_rebal001",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxGlobalUsd01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxCopUsd01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "cop/usd",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 40000000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 10000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 60000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "col/usa",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "COP to USD treasury rebalancing"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R012The user has abandoned the transaction.Payin
R015Account not authorized to be credited.Payout
R016Payment rejected due to timeout.Payin
R017Payment rejected due to expired money movement.Payin
R018Payment rejected due invalid key.Payout
R019Payment rejected due to incorrect amount.Payin
R020Payment rejected due to user authentication failure.Payin
R021Insufficient funds in payer account.Payin
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R081The counterparty registration has expired.Payin
R082The counterparty registration has been canceled.Payin
R084The counterparty registration has been rejected.Payin
R085Bank processing error.Payout
Event cross_border_money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_CbmmCopUsd01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "cross_border_money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:00:45Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_CbmmCopUsd01",IdiUnique Cobre identifier for this resource.
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"external_id": "fx_copusd_rebal001",External IdiYour own reference echoed by Cobre for reconciliation.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Inactive or blocked account."DescriptioniHuman-readable label or note.
},
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "acc_FxGlobalUsd01",Destination IdiCobre id of the destination account or counterparty.
"forex_quote_id": "fxq_FxCopUsd01",Forex Quote IdiCobre field at "content.forex_quote_id" in this payload.
"forex_quote": {Forex QuoteiCobre field at "content.forex_quote" in this payload.
"type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"currency_pair": "cop/usd",Currency PairiCobre field at "content.forex_quote.currency_pair" in this payload.
"source_amount": 40000000,Source AmountiCobre field at "content.forex_quote.source_amount" in this payload.
"fees_breakdown": {Fees BreakdowniCobre field at "content.forex_quote.fees_breakdown" in this payload.
"spread": 1.2SpreadiCobre field at "content.forex_quote.fees_breakdown.spread" in this payload.
},
"fx_rate": 4000,Fx RateiCobre field at "content.forex_quote.fx_rate" in this payload.
"destination_amount": 10000,Destination AmountiCobre field at "content.forex_quote.destination_amount" in this payload.
"quota_limit": 100000000,Quota LimitiCobre field at "content.forex_quote.quota_limit" in this payload.
"remaining_quota": 60000000,Remaining QuotaiCobre field at "content.forex_quote.remaining_quota" in this payload.
"created_at": "2026-08-01T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"valid_until": "2026-08-01T12:01:00Z",Valid UntiliCobre field at "content.forex_quote.valid_until" in this payload.
"last_quote": true,Last QuoteiCobre field at "content.forex_quote.last_quote" in this payload.
"off_market": falseOff MarketiCobre field at "content.forex_quote.off_market" in this payload.
},
"geo": "col/usa",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"destination_description": "COP to USD treasury rebalancing"Destination DescriptioniMetadata field "destination_description" attached to the resource.
},
"created_at": "2026-08-01T12:00:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:00:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
Create a Cross Border Money MovementCreate a Cross-Border Money Movement
Step 21 of 40 Cross-Border FX Reconciliation

Reconcile the COP/USD (Rebalancing) Conversion

Match the Cross-Border completion webhook to your treasury ledger on external_id and cbmm_id.

Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueTreasury ledger field
content.external_id
fx_copusd_rebal001
 →
fx_external_id
content.id
mm_CbmmCopUsd01
 →
cbmm_id
content.forex_quote_id
fxq_FxCopUsd01
 →
fxq_id
content.status.state
completed
 →
fx_status
Step 22 of 40 Mexico — Named Account Payout API step

Register the End Client as a Subclient

Before a Named Account can exist, the end client must be onboarded as a Subclient: legal, tax, and beneficial-ownership details go through async compliance screening. Store the returned id — it feeds the Named Account creation next.

POST https://api.cobre.co/v1/subclients
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"legal_name": "Beneficiary Trading Co. S.A. de C.V.",Legal nameRequirediCobre field at "legal_name" in this payload.
"short_name": "BeneficiaryTradingCo",Short nameRequirediCobre field at "short_name" in this payload.
"id_type": "rfc",ID typeRequirediCobre field at "id_type" in this payload.
"id_number": "BTC150320AB1",RFCRequirediCobre field at "id_number" in this payload.
"email": "contacto@beneficiarytradingco.mx",EmailRequirediCobre field at "email" in this payload.
"phone": "+525512345678",PhoneRequirediE.164 international format.
"website": "https://www.beneficiarytradingco.mx",WebsiteRequirediCobre field at "website" in this payload.
"industry": "financial_services",IndustryRequirediCobre field at "industry" in this payload.
"date_of_incorporation": "2015-03-20",Date of incorporationRequirediCobre field at "date_of_incorporation" in this payload.
"country_of_incorporation": "MEX",Country of incorporationRequirediISO 3166-1 alpha-3.
"address": {AddressiCobre field at "address" in this payload.
"street": "Av. Insurgentes Sur 1234",StreetiCobre field at "address.street" in this payload.
"city": "Ciudad de Mexico",CityRequirediCobre field at "address.city" in this payload.
"state": "CDMX",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"postal_code": "03100",Postal CodeiCobre field at "address.postal_code" in this payload.
"country": "MEX"CountryiCobre field at "address.country" in this payload.
},
"ubos": [UbosiCobre field at "ubos" in this payload.
{
"first_name": "Ana",UBO first nameRequirediCobre field at "ubos.0.first_name" in this payload.
"last_name": "Martinez Lopez",UBO last nameRequirediCobre field at "ubos.0.last_name" in this payload.
"id_type": "curp",Id TypeiCobre field at "ubos.0.id_type" in this payload.
"id_number": "MALA900101HDFRPN08",Id NumberiCobre field at "ubos.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "ubos.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1990-01-01"Date Of BirthiCobre field at "ubos.0.date_of_birth" in this payload.
}
],
"legal_representatives": [Legal RepresentativesiCobre field at "legal_representatives" in this payload.
{
"first_name": "Luis",Legal rep. first nameRequirediCobre field at "legal_representatives.0.first_name" in this payload.
"last_name": "Hernandez Ruiz",Legal rep. last nameRequirediCobre field at "legal_representatives.0.last_name" in this payload.
"id_type": "rfc",ID typeRequirediCobre field at "legal_representatives.0.id_type" in this payload.
"id_number": "HERL850615ABC",Id NumberiCobre field at "legal_representatives.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "legal_representatives.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1985-06-15"Date Of BirthiCobre field at "legal_representatives.0.date_of_birth" in this payload.
}
]
}
Response 200
{
"id": "sc_FxNamedMx01",IdiUnique Cobre identifier for this resource.
"object": "subclient",ObjectiCobre field at "object" in this payload.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "processing"StateiCurrent lifecycle state (e.g. completed, failed, rejected).
},
"legal_name": "Beneficiary Trading Co. S.A. de C.V.",Legal nameRequirediCobre field at "legal_name" in this payload.
"short_name": "BeneficiaryTradingCo",Short nameRequirediCobre field at "short_name" in this payload.
"id_type": "rfc",ID typeRequirediCobre field at "id_type" in this payload.
"id_number": "BTC150320AB1",RFCRequirediCobre field at "id_number" in this payload.
"email": "contacto@beneficiarytradingco.mx",EmailRequirediCobre field at "email" in this payload.
"phone": "+525512345678",PhoneRequirediE.164 international format.
"website": "https://www.beneficiarytradingco.mx",WebsiteRequirediCobre field at "website" in this payload.
"industry": "financial_services",IndustryRequirediCobre field at "industry" in this payload.
"date_of_incorporation": "2015-03-20",Date of incorporationRequirediCobre field at "date_of_incorporation" in this payload.
"country_of_incorporation": "MEX",Country of incorporationRequirediISO 3166-1 alpha-3.
"address": {AddressiCobre field at "address" in this payload.
"street": "Av. Insurgentes Sur 1234",StreetiCobre field at "address.street" in this payload.
"city": "Ciudad de Mexico",CityRequirediCobre field at "address.city" in this payload.
"state": "CDMX",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"postal_code": "03100",Postal CodeiCobre field at "address.postal_code" in this payload.
"country": "MEX"CountryiCobre field at "address.country" in this payload.
},
"ubos": [UbosiCobre field at "ubos" in this payload.
{
"first_name": "Ana",UBO first nameRequirediCobre field at "ubos.0.first_name" in this payload.
"last_name": "Martinez Lopez",UBO last nameRequirediCobre field at "ubos.0.last_name" in this payload.
"id_type": "curp",Id TypeiCobre field at "ubos.0.id_type" in this payload.
"id_number": "MALA900101HDFRPN08",Id NumberiCobre field at "ubos.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "ubos.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1990-01-01"Date Of BirthiCobre field at "ubos.0.date_of_birth" in this payload.
}
],
"legal_representatives": [Legal RepresentativesiCobre field at "legal_representatives" in this payload.
{
"first_name": "Luis",Legal rep. first nameRequirediCobre field at "legal_representatives.0.first_name" in this payload.
"last_name": "Hernandez Ruiz",Legal rep. last nameRequirediCobre field at "legal_representatives.0.last_name" in this payload.
"id_type": "rfc",ID typeRequirediCobre field at "legal_representatives.0.id_type" in this payload.
"id_number": "HERL850615ABC",Id NumberiCobre field at "legal_representatives.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "legal_representatives.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1985-06-15"Date Of BirthiCobre field at "legal_representatives.0.date_of_birth" in this payload.
}
],
"created_at": "2026-08-01T12:55:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:55:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create a SubclientNamed Accounts (MX) GuideNamed Accounts in Mexico
Step 23 of 40 Mexico — Named Account Payout API step

Subclient Approved (Webhook)

Track compliance screening via webhook (subclient.approved / rejected / failed) or by polling GET /subclients/{id}. Do not proceed to Named Account creation until status.state is approved.

GET https://api.cobre.co/v1/subclients/sc_FxNamedMx01Subclient IDRequiredi
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Response 200
{
"id": "sc_FxNamedMx01",IdiUnique Cobre identifier for this resource.
"object": "subclient",ObjectiCobre field at "object" in this payload.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "approved"StatusRequirediCurrent lifecycle state (e.g. completed, failed, rejected).
},
"legal_name": "Beneficiary Trading Co. S.A. de C.V.",Legal NameiCobre field at "legal_name" in this payload.
"short_name": "BeneficiaryTradingCo",Short NameiCobre field at "short_name" in this payload.
"id_type": "rfc",Id TypeiCobre field at "id_type" in this payload.
"id_number": "BTC150320AB1",Id NumberiCobre field at "id_number" in this payload.
"email": "contacto@beneficiarytradingco.mx",EmailiCobre field at "email" in this payload.
"phone": "+525512345678",PhoneiCobre field at "phone" in this payload.
"website": "https://www.beneficiarytradingco.mx",WebsiteiCobre field at "website" in this payload.
"industry": "financial_services",IndustryiCobre field at "industry" in this payload.
"date_of_incorporation": "2015-03-20",Date Of IncorporationiCobre field at "date_of_incorporation" in this payload.
"country_of_incorporation": "MEX",Country Of IncorporationiCobre field at "country_of_incorporation" in this payload.
"address": {AddressiCobre field at "address" in this payload.
"street": "Av. Insurgentes Sur 1234",StreetiCobre field at "address.street" in this payload.
"city": "Ciudad de Mexico",CityiCobre field at "address.city" in this payload.
"state": "CDMX",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"postal_code": "03100",Postal CodeiCobre field at "address.postal_code" in this payload.
"country": "MEX"CountryiCobre field at "address.country" in this payload.
},
"ubos": [UbosiCobre field at "ubos" in this payload.
{
"first_name": "Ana",First NameiCobre field at "ubos.0.first_name" in this payload.
"last_name": "Martinez Lopez",Last NameiCobre field at "ubos.0.last_name" in this payload.
"id_type": "curp",Id TypeiCobre field at "ubos.0.id_type" in this payload.
"id_number": "MALA900101HDFRPN08",Id NumberiCobre field at "ubos.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "ubos.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1990-01-01"Date Of BirthiCobre field at "ubos.0.date_of_birth" in this payload.
}
],
"legal_representatives": [Legal RepresentativesiCobre field at "legal_representatives" in this payload.
{
"first_name": "Luis",First NameiCobre field at "legal_representatives.0.first_name" in this payload.
"last_name": "Hernandez Ruiz",Last NameiCobre field at "legal_representatives.0.last_name" in this payload.
"id_type": "rfc",Id TypeiCobre field at "legal_representatives.0.id_type" in this payload.
"id_number": "HERL850615ABC",Id NumberiCobre field at "legal_representatives.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "legal_representatives.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1985-06-15"Date Of BirthiCobre field at "legal_representatives.0.date_of_birth" in this payload.
}
],
"created_at": "2026-08-01T12:55:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:58:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook delivered

subclient.approved

Fires once compliance screening clears the Subclient — safe to create the Named Account referencing this subclient_id.

Headers
Content-Typeapplication/json
Payload
{
"id": "ev_FxSubclientApproved01",IdiUnique Cobre identifier for this resource.
"event_key": "subclient.approved",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T12:58:30Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "sc_FxNamedMx01",IdiUnique Cobre identifier for this resource.
"object": "subclient",ObjectiCobre field at "content.object" in this payload.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "approved"StateiCurrent lifecycle state (e.g. completed, failed, rejected).
},
"legal_name": "Beneficiary Trading Co. S.A. de C.V.",Legal NameiCobre field at "content.legal_name" in this payload.
"short_name": "BeneficiaryTradingCo",Short NameiCobre field at "content.short_name" in this payload.
"id_type": "rfc",Id TypeiCobre field at "content.id_type" in this payload.
"id_number": "BTC150320AB1",Id NumberiCobre field at "content.id_number" in this payload.
"email": "contacto@beneficiarytradingco.mx",EmailiCobre field at "content.email" in this payload.
"phone": "+525512345678",PhoneiCobre field at "content.phone" in this payload.
"website": "https://www.beneficiarytradingco.mx",WebsiteiCobre field at "content.website" in this payload.
"industry": "financial_services",IndustryiCobre field at "content.industry" in this payload.
"date_of_incorporation": "2015-03-20",Date Of IncorporationiCobre field at "content.date_of_incorporation" in this payload.
"country_of_incorporation": "MEX",Country Of IncorporationiCobre field at "content.country_of_incorporation" in this payload.
"address": {AddressiCobre field at "content.address" in this payload.
"street": "Av. Insurgentes Sur 1234",StreetiCobre field at "content.address.street" in this payload.
"city": "Ciudad de Mexico",CityiCobre field at "content.address.city" in this payload.
"state": "CDMX",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"postal_code": "03100",Postal CodeiCobre field at "content.address.postal_code" in this payload.
"country": "MEX"CountryiCobre field at "content.address.country" in this payload.
},
"ubos": [UbosiCobre field at "content.ubos" in this payload.
{
"first_name": "Ana",First NameiCobre field at "content.ubos.0.first_name" in this payload.
"last_name": "Martinez Lopez",Last NameiCobre field at "content.ubos.0.last_name" in this payload.
"id_type": "curp",Id TypeiCobre field at "content.ubos.0.id_type" in this payload.
"id_number": "MALA900101HDFRPN08",Id NumberiCobre field at "content.ubos.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "content.ubos.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1990-01-01"Date Of BirthiCobre field at "content.ubos.0.date_of_birth" in this payload.
}
],
"legal_representatives": [Legal RepresentativesiCobre field at "content.legal_representatives" in this payload.
{
"first_name": "Luis",First NameiCobre field at "content.legal_representatives.0.first_name" in this payload.
"last_name": "Hernandez Ruiz",Last NameiCobre field at "content.legal_representatives.0.last_name" in this payload.
"id_type": "rfc",Id TypeiCobre field at "content.legal_representatives.0.id_type" in this payload.
"id_number": "HERL850615ABC",Id NumberiCobre field at "content.legal_representatives.0.id_number" in this payload.
"nationalities": [NationalitiesiCobre field at "content.legal_representatives.0.nationalities" in this payload.
"MEX"
],
"date_of_birth": "1985-06-15"Date Of BirthiCobre field at "content.legal_representatives.0.date_of_birth" in this payload.
}
],
"created_at": "2026-08-01T12:55:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T12:58:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
Obtain one SubclientSubclient Webhook EventsNamed Accounts (MX) Guide
Step 24 of 40 Mexico — Named Account Payout API step

Create the Named MXN Account

Provision a dedicated Cobre Balance for the end client, referencing the approved Subclient via subclient_id. This is the Named Account model: money leaving this balance is attributed to the underlying client (the Subclient), not the platform.

POST https://api.cobre.co/v1/accounts
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"provider_id": "pr_mex_cobre3",ProviderRequirediCobre field at "provider_id" in this payload.
"action": "create",ActionRequirediCobre field at "action" in this payload.
"subclient_id": "sc_FxNamedMx01",Subclient IDRequirediThe approved Subclient this account is named after — links the account to the end client's verified identity.
"alias": "Beneficiary Trading Co — Named MXN Account"AliasiDisplay name that helps identify it and clarify its purpose.
}
Response 201
{
"id": "acc_FxNamedMxn01",IdiUnique Cobre identifier for this resource.
"provider_id": "pr_mex_cobre3",ProviderRequirediCobre field at "provider_id" in this payload.
"provider_name": "Cobre Balance Mexico",Provider NameiCobre field at "provider_name" in this payload.
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "connected",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"alias": "Beneficiary Trading Co — Named MXN Account",AliasiDisplay name that helps identify it and clarify its purpose.
"subclient_id": "sc_FxNamedMx01",Subclient IDRequirediThe approved Subclient this account is named after — links the account to the end client's verified identity.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload.
"mm_push_from_account"
]
},
"account_number": "",Account NumberiBank account or CLABE number for the counterparty.
"account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload.
"obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload.
"obtained_balance_at": "2026-08-01T13:00:00Z",Obtained Balance AtiCobre field at "obtained_balance_at" in this payload.
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"tags": [],TagsiCobre field at "tags" in this payload.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"created_at": "2026-08-01T13:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create or Connect an AccountNamed Accounts (MX) GuideManaging Cobre Balances
Step 25 of 40 Mexico — Named Account Payout API step

Manual Transfer: Treasury → Named Account

Move MXN from the MXN Treasury Balance to the end-client's Named Account with POST /money_movements (Cobre Balance → Cobre Balance). The same endpoint moves funds in reverse by swapping source_id and destination_id.

POST https://api.cobre.co/v1/money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx-fund-named-001
Request body
{
"source_id": "acc_FxMxnTreasury01",MXN Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxNamedMxn01",Named MXN AccountRequirediCobre id of the destination account or counterparty.
"amount": 300000000,Amount (MXN cents)RequirediAmount in cents — the last two digits are decimals.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Fund named account for client payout"DescriptionRequirediHuman-readable label or note.
},
"external_id": "fx_fund_named_001",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": falseChecker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
}
Response 201
{
"id": "mm_FxFundNamed01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Fund named account for client payout"DescriptionRequirediHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_fund_named_001",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxMxnTreasury01",MXN Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "acc_FxNamedMxn01",Named MXN AccountRequirediCobre id of the destination account or counterparty.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 300000000,Amount (MXN cents)RequirediAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T13:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create a Money MovementManaging Cobre Balances
Step 26 of 40 Mexico — Named Account Payout API step

Register the Final Beneficiary

Register the true underlying beneficiary — the end-client's own customer — as a CLABE counterparty. This is who gets paid; the Named Account is only the sender.

POST https://api.cobre.co/v1/counterparties
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"geo": "mex",GeoRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "clabe",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Final beneficiary - Named Account payout",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"counterparty_fullname": "Ana Martinez Lopez",Beneficiary nameRequirediLegal or display name of the counterparty beneficiary.
"account_number": "012180001234567895",CLABERequirediBank account or CLABE number for the counterparty.
"counterparty_id_type": "curp",ID typeRequirediType of identification document for the counterparty (e.g. nit, cc, rfc).
"counterparty_id_number": "MALA900101HDFRPN08"CURPRequirediIdentification number for the counterparty.
}
}
Response 201
{
"id": "cp_FxMxBeneficiary01",IdiUnique Cobre identifier for this resource.
"geo": "mex",GeoRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "clabe",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Final beneficiary - Named Account payout",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"counterparty_fullname": "Ana Martinez Lopez",Beneficiary nameRequirediLegal or display name of the counterparty beneficiary.
"account_number": "012180001234567895",CLABERequirediBank account or CLABE number for the counterparty.
"counterparty_id_type": "curp",ID typeRequirediType of identification document for the counterparty (e.g. nit, cc, rfc).
"counterparty_id_number": "MALA900101HDFRPN08",CURPRequirediIdentification number for the counterparty.
"registered_account": falseRegistered AccountiCobre field at "metadata.registered_account" in this payload.
},
"created_at": "2026-08-01T13:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create a CounterpartyManaging Counterparties
Step 27 of 40 Mexico — Named Account Payout API step

Pay via SPEI from the Named Account

Create a Money Movement from the Named Account (not the Treasury Balance) to the final beneficiary over SPEI. Because the source is a named, client-attributed Cobre Balance, the beneficiary's bank statement shows the named account's own display name as sender — a payment made on behalf of a third party, not on behalf of the platform or Cobre. metadata.reference must be numeric (1–7 digits).

POST https://api.cobre.co/v1/money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx-named-payout-001
Request body
{
"source_id": "acc_FxNamedMxn01",Named MXN AccountRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxMxBeneficiary01",BeneficiaryRequirediCobre id of the destination account or counterparty.
"amount": 150000000,Amount (MXN cents)RequirediAmount in cents — the last two digits are decimals.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Payout on behalf of end client",DescriptionRequirediHuman-readable label or note.
"reference": "4455667"SPEI referenceRequirediPayment reference echoed in metadata for reconciliation.
},
"external_id": "fx_named_payout_001",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": falseChecker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
}
Response 201
{
"id": "mm_NamedPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Payout on behalf of end client",DescriptionRequirediHuman-readable label or note.
"reference": "4455667"SPEI referenceRequirediPayment reference echoed in metadata for reconciliation.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_named_payout_001",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxNamedMxn01",Named MXN AccountRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxMxBeneficiary01",BeneficiaryRequirediCobre id of the destination account or counterparty.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 150000000,Amount (MXN cents)RequirediAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T13:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:15:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Money movement

Named Account payout completed — MXN debited from acc_FxNamedMxn01. Reconcile on external_id fx_named_payout_001.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_NamedPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T13:17:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_NamedPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Payout on behalf of end client",DescriptioniHuman-readable label or note.
"reference": "4455667",ReferenceiPayment reference echoed in metadata for reconciliation.
"tracking_key": "20260801mmNamedPayout01"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_named_payout_001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxNamedMxn01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxMxBeneficiary01",Destination IdiCobre id of the destination account or counterparty.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 150000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T13:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:17:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_NamedPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T13:17:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_NamedPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Payout on behalf of end client",DescriptioniHuman-readable label or note.
"reference": "4455667",ReferenceiPayment reference echoed in metadata for reconciliation.
"tracking_key": "20260801mmNamedPayout01"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_named_payout_001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxNamedMxn01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxMxBeneficiary01",Destination IdiCobre id of the destination account or counterparty.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 150000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T13:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:17:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R015Account not authorized to be credited.Payout
R018Payment rejected due invalid key.Payout
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R085Bank processing error.Payout
Event money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_NamedPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T13:17:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_NamedPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R018",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Payout on behalf of end client",DescriptioniHuman-readable label or note.
"reference": "4455667",ReferenceiPayment reference echoed in metadata for reconciliation.
"tracking_key": "20260801mmNamedPayout01"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx_named_payout_001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxNamedMxn01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxMxBeneficiary01",Destination IdiCobre id of the destination account or counterparty.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 150000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T13:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:17:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}
Documentation for this step
Create a Money MovementMoney Movements Guide
Step 28 of 40 Mexico — Named Account Payout Reconciliation

Reconcile the Named Account Payout

Match the completion webhook to the end-client's own ledger on external_id and the Money Movement id. Cross-check the MXN debit on acc_FxNamedMxn01 via GET /accounts/{acct_id}/transactions.

Mapping the webhook payload from an earlier step onto Client ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueClient ledger field
content.external_id
fx_named_payout_001
 →
payout_external_id
content.id
mm_NamedPayout01
 →
cobre_mm_id
content.metadata.reference
4455667
 →
spei_reference
content.status.state
completed
 →
payout_status
Step 29 of 40 Mexico — Virtual CLABE Payin API step

Create Virtual CLABE for the Named Account

Create a Virtual CLABE account reference linked directly to the Named Account (not the Treasury Balance). Inbound SPEI transfers to this CLABE credit acc_FxNamedMxn01 — reconcile via metadata.account_reference.

POST https://api.cobre.co/v1/account_references
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"source_id": "acc_FxNamedMxn01",Named MXN AccountRequirediCobre id of the source account or counterparty.
"type": "virtual_clabe_accounts",Reference typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Beneficiary Trading Co — Virtual CLABE"AliasiDisplay name that helps identify it and clarify its purpose.
}
Response 200
{
"id": "ref_FxNamedClabe01",IdiUnique Cobre identifier for this resource.
"alias": "Beneficiary Trading Co — Virtual CLABE",AliasiDisplay name that helps identify it and clarify its purpose.
"type": "virtual_clabe_accounts",Reference typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"value": "70301105231100099",ValueiCobre field at "value" in this payload.
"source_id": "acc_FxNamedMxn01",Named MXN AccountRequirediCobre id of the source account or counterparty.
"geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"connectivity": {ConnectivityiConnection/registration status for keys or accounts.
"status": "enabled",StatusiLifecycle status object for the resource or movement.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {},MetadataiCustom key-value metadata attached to the resource.
"created_at": "2026-08-01T13:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T13:20:05Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create an Account ReferenceVirtual CLABEs Guide
Step 30 of 40 Mexico — Virtual CLABE Payin API step

Named Virtual CLABE Credit

The end client sends MXN via SPEI to the Virtual CLABE. Cobre credits acc_FxNamedMxn01 with spei_credit — reconcile using metadata.account_reference 70301105231100099 (ref_FxNamedClabe01).

GET https://api.cobre.co/v1/accounts/acc_FxNamedMxn01Named MXN AccountRequiredi/transactions
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Response 200
{
"total_items": 1,Total ItemsiTotal items matching the query across all pages.
"total_pages": 1,Total PagesiNumber of pages in this result set.
"is_last_page": true,Is Last PageiTrue when this is the final page of results.
"page_items": 1,Page ItemsiNumber of items returned on this page.
"contents": [ContentsiArray of result objects for this page.
{
"id": "trx_FxNamedClabe01",Transaction IDiUnique Cobre identifier for this resource.
"type": "spei_credit",Transaction typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxNamedMxn01",Account IdiCobre Balance account id affected by the event.
"amount": 50000000,Amount creditediAmount in cents — the last two digits are decimals.
"previous_balance": 150000000,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload.
"current_balance": 200000000,Current BalanceiCobre field at "contents.0.current_balance" in this payload.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T14:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T14:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"reference": "9988776",ReferenceiPayment reference echoed in metadata for reconciliation.
"sender_name": "Beneficiary Trading Co Client",Sender NameiMetadata field "sender_name" attached to the resource.
"sender_clabe": "012180009988776655",Sender ClabeiMetadata field "sender_clabe" attached to the resource.
"tracking_key": "20260801140000001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"description": "SPEI funding via named virtual CLABE",DescriptioniHuman-readable label or note.
"account_reference": "70301105231100099"Account referenceiTransfer-In reference number used to reconcile incoming deposits.
}
}
]
}
⚡

Webhook delivered

accounts.balance.credit

Fires when the Virtual CLABE credit posts on acc_FxNamedMxn01. Map metadata.account_reference to the named end-client account.

Headers
Content-Typeapplication/json
Payload
{
"id": "ev_FxNamedClabeCredit01",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T14:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxNamedClabe01",IdiUnique Cobre identifier for this resource.
"type": "spei_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"amount": 50000000,AmountiAmount in cents — the last two digits are decimals.
"currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn).
"date": "2026-08-01T14:00:00Z",DateiTimestamp when the balance transaction was posted (ISO 8601, UTC) — used in accounts.balance.* webhook notifications.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"reference": "9988776",ReferenceiPayment reference echoed in metadata for reconciliation.
"sender_name": "Beneficiary Trading Co Client",Sender NameiMetadata field "sender_name" attached to the resource.
"sender_clabe": "012180009988776655",Sender ClabeiMetadata field "sender_clabe" attached to the resource.
"tracking_key": "20260801140000001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"description": "SPEI funding via named virtual CLABE",DescriptioniHuman-readable label or note.
"account_reference": "70301105231100099"Account ReferenceiTransfer-In reference number used to reconcile incoming deposits.
},
"account_id": "acc_FxNamedMxn01",Account IdiCobre Balance account id affected by the event.
"previous_balance": 150000000,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 200000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"credit_debit_type": "credit"Credit Debit Typeicredit = funds in; debit = funds out.
}
}
Documentation for this step
Obtain one Account TransactionsAccount Balance Credit
Step 31 of 40 Mexico — Virtual CLABE Payin Reconciliation

Reconcile the Virtual CLABE Payin

Match the accounts.balance.credit webhook to the end-client's own ledger using account_reference — no Money Movement is created for a Virtual CLABE credit.

Mapping the webhook payload from an earlier step onto Client ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valueClient ledger field
content.metadata.account_reference
70301105231100099
 →
virtual_clabe_reference
content.id
trx_FxNamedClabe01
 →
cobre_transaction_id
content.amount
50000000
 →
mxn_credited_cents
50000000 = $500,000.00 MXN credited to the named account.
Step 32 of 40 Colombia — Payout API step

Verify the Beneficiary's Bre-B Key

Best practice before any first payout: confirm the destination Bre-B key belongs to the declared identity. The col_key_ownership_1 model checks the key against the holder's ID in Colombia's directory.

POST https://api.cobre.co/v1/account_verifications
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"model": "col_key_ownership_1",ModelRequirediVerification model identifier (region- and rail-specific).
"verification_request": {Verification RequestiInput fields sent to the verification model.
"key_value": "@BeneficiaryCo10",Bre-B keyRequirediBre-B key value (e.g. @merchant123).
"account_holder_id_number": "9008765432"Holder IDRequirediCobre field at "verification_request.account_holder_id_number" in this payload.
},
"external_id": "verify-fx-breb-10"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "av_FxCopBreb01",IdiUnique Cobre identifier for this resource.
"creator_id": "cli_fxpsp_lac01",Creator IdiCobre field at "creator_id" in this payload.
"model": "col_key_ownership_1",ModelRequirediVerification model identifier (region- and rail-specific).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"verification_request": {Verification RequestiInput fields sent to the verification model.
"key_value": "@BeneficiaryCo10",Bre-B keyRequirediBre-B key value (e.g. @merchant123).
"account_holder_id_number": "9008765432"Holder IDRequirediCobre field at "verification_request.account_holder_id_number" in this payload.
},
"status": {StatusiLifecycle status object for the resource or movement.
"state": "processing",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"external_id": "verify-fx-breb-10",External IDiYour own reference echoed by Cobre for reconciliation.
"created_at": "2026-08-01T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create an Account VerificationAccount Verification Guide
Step 33 of 40 Colombia — Payout API step

Retrieve Beneficiary Key Verification Result

Poll the Account Verification by id until status.state is completed. Continue with the payout only when verification_response.verification_result is matched; route unmatched or failed results to manual review.

GET https://api.cobre.co/v1/account_verifications/av_FxCopBreb01
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Response 200
{
"id": "av_FxCopBreb01",Verification IDRequirediThe av_… identifier returned by the create response.
"creator_id": "cli_fxpsp_lac01",Creator IdiCobre field at "creator_id" in this payload.
"model": "col_key_ownership_1",ModeliVerification model identifier (region- and rail-specific).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"verification_request": {Verification RequestiInput fields sent to the verification model.
"key_value": "@BeneficiaryCo10",Key ValueiBre-B key value (e.g. @merchant123).
"account_holder_id_number": "9008765432"Account Holder Id NumberiCobre field at "verification_request.account_holder_id_number" in this payload.
},
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StatusRequirediMust be completed before creating the counterparty or Money Movement.
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"external_id": "verify-fx-breb-10",External IdiYour own reference echoed by Cobre for reconciliation.
"created_at": "2026-08-01T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:00:00Z",Updated AtiTimestamp of the last update (ISO 8601, UTC).
"verification_response": {Verification ResponseiResult returned by the verification model.
"verification_result": "matched"Ownership resultRequiredimatched confirms the key ownership check; unmatched or failed blocks the payout.
}
}
Documentation for this step
Obtain one Account VerificationAccount Verification Guide
Step 34 of 40 Colombia — Payout API step

Create the Bre-B Counterparty

Register the verified Bre-B key as a breb_key counterparty. The counterparty type is what selects the Bre-B rail at payout time.

POST https://api.cobre.co/v1/counterparties
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"geo": "col",GeographyRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "breb_key",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Colombia beneficiary - Bre-B",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"key_value": "@BeneficiaryCo10",Bre-B keyRequirediCobre Key that received the Bre-B deposit (breb_credit notifications).
"counterparty_email": "pagos@beneficiaryco.co"EmailiCobre field at "metadata.counterparty_email" in this payload.
}
}
Response 201
{
"id": "cp_FxCopBreb01",IdiUnique Cobre identifier for this resource.
"geo": "col",GeographyRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "breb_key",TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Colombia beneficiary - Bre-B",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"key_value": "@BeneficiaryCo10",Bre-B keyRequirediCobre Key that received the Bre-B deposit (breb_credit notifications).
"key_type": "alphanumeric",Key TypeiCobre field at "metadata.key_type" in this payload.
"counterparty_email": "pagos@beneficiaryco.co"EmailiCobre field at "metadata.counterparty_email" in this payload.
},
"created_at": "2026-08-01T15:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create a CounterpartyManaging Counterparties
Step 35 of 40 Colombia — Payout API step

Send the Bre-B Payout

Create a Money Movement from the COP Treasury Balance to the Bre-B counterparty. Bre-B settles instantly, 24/7 (max ~$12,110,000 COP per transaction). The response type is 'breb'.

POST https://api.cobre.co/v1/money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx-payout-breb-001
Request body
{
"amount": 3000000,Amount (cents)RequirediAmount in cents — the last two digits are decimals.
"source_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBreb01",Destination (counterparty)RequirediCobre id of the destination account or counterparty.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Bre-B"DescriptionRequirediHuman-readable label or note.
},
"external_id": "fx-payout-breb-001"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "mm_FxBrebPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Bre-B"DescriptionRequirediHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-breb-001",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBreb01",Destination (counterparty)RequirediCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,Amount (cents)RequirediAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Money movement

Fires when the Bre-B payout settles (typically seconds). Mark the payout paid by external_id.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide. Cobre Balance transactions are covered in the <b>Transaction</b> tab.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxBrebPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:10:09Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxBrebPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Bre-B",DescriptioniHuman-readable label or note.
"tracking_key": "10091500901",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"key_value": "@BeneficiaryCo10",Key ValueiBre-B key value (e.g. @merchant123).
"beneficiary_account_number": "@BeneficiaryCo10"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-breb-001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBreb01",Destination IdiCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:10:09Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxBrebPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:10:09Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxBrebPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Bre-B",DescriptioniHuman-readable label or note.
"tracking_key": "10091500901",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"key_value": "@BeneficiaryCo10",Key ValueiBre-B key value (e.g. @merchant123).
"beneficiary_account_number": "@BeneficiaryCo10"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-breb-001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBreb01",Destination IdiCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:10:09Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R015Account not authorized to be credited.Payout
R018Payment rejected due invalid key.Payout
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R085Bank processing error.Payout
Event money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxBrebPayout01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:10:09Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxBrebPayout01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R018",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Bre-B",DescriptioniHuman-readable label or note.
"tracking_key": "10091500901",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"key_value": "@BeneficiaryCo10",Key ValueiBre-B key value (e.g. @merchant123).
"beneficiary_account_number": "@BeneficiaryCo10"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-breb-001",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBreb01",Destination IdiCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:10:09Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Payouts debit the source Cobre Balance while the movement is processing to lock funds. If the movement ends in failed, rejected, or canceled, Cobre posts a compensation credit (breb_credit or col_cb_credit). Payins credit the destination on completion only.

While the movement is in processing, Cobre debits the source Cobre Balance to lock the payout amount. Subscribe to accounts.balance.debit and money_movements.status.processing.

Event accounts.balance.debit
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxBrebPayoLk",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxBrebPayoutLk",IdiUnique Cobre identifier for this resource.
"type": "breb_debit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxCopTreasury01",Account IdiCobre Balance account id affected by the event.
"amount": -3000000,AmountiAmount in cents — the last two digits are decimals.
"previous_balance": 8000000,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"currency": "COP",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T15:10:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"beneficiary_account_number": "@BeneficiaryCo10",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
"beneficiary_account_type": "ch",Beneficiary Account TypeiMetadata field "beneficiary_account_type" attached to the resource.
"beneficiary_name": "",Beneficiary NameiMetadata field "beneficiary_name" attached to the resource.
"beneficiary_id": "",Beneficiary IdiMetadata field "beneficiary_id" attached to the resource.
"description": "Colombia payout via Bre-B",DescriptioniHuman-readable label or note.
"money_movement_id": "mm_FxBrebPayout01",Money Movement IdiMoney Movement that generated this balance transaction.
"tracking_key": "10091500901"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
}
}
}

On completion the locked funds are sent to the beneficiary. The processing debit remains on the ledger — no compensation credit is posted.

Event accounts.balance.debit
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxBrebPayoLk",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxBrebPayoutLk",IdiUnique Cobre identifier for this resource.
"type": "breb_debit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxCopTreasury01",Account IdiCobre Balance account id affected by the event.
"amount": -3000000,AmountiAmount in cents — the last two digits are decimals.
"previous_balance": 8000000,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"currency": "COP",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T15:10:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T15:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"beneficiary_account_number": "@BeneficiaryCo10",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
"beneficiary_account_type": "ch",Beneficiary Account TypeiMetadata field "beneficiary_account_type" attached to the resource.
"beneficiary_name": "",Beneficiary NameiMetadata field "beneficiary_name" attached to the resource.
"beneficiary_id": "",Beneficiary IdiMetadata field "beneficiary_id" attached to the resource.
"description": "Colombia payout via Bre-B",DescriptioniHuman-readable label or note.
"money_movement_id": "mm_FxBrebPayout01",Money Movement IdiMoney Movement that generated this balance transaction.
"tracking_key": "10091500901"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
}
}
}

If the movement reaches a terminal failed, rejected, or canceled state, Cobre credits the source Cobre Balance to release the lock (breb_credit for Bre-B, col_cb_credit for bank rails).

Event accounts.balance.credit
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxBrebPayoCp",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:10:09Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxBrebPayoutCp",IdiUnique Cobre identifier for this resource.
"type": "breb_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxCopTreasury01",Account IdiCobre Balance account id affected by the event.
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 3000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"currency": "COP",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T15:10:09Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T15:10:09Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Bre-B",DescriptioniHuman-readable label or note.
"money_movement_id": "mm_FxBrebPayout01",Money Movement IdiMoney Movement that generated this balance transaction.
"tracking_key": "10091500901"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
}
}
}
Documentation for this step
Create a Money MovementMoney Movements ApprovalBre-B PayoutsMoney Movement Statuses
Step 36 of 40 Colombia — Payout Reconciliation

Reconcile the Bre-B Payout

Close the Bre-B payout leg on your ledger using external_id and the Money Movement id.

Mapping the webhook payload from an earlier step onto Platform ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valuePlatform ledger field
content.external_id
fx-payout-breb-001
 →
payout_external_id
content.id
mm_FxBrebPayout01
 →
cobre_mm_id
content.status.state
completed
 →
payout_status
Step 37 of 40 Colombia — Payout API step

Create the Bank-Account Counterparty

For a payout to a Colombian bank account, register a cc, ch, or dp counterparty with the account number and beneficiary institution. The same counterparty serves both Fast Pay and ACH.

POST https://api.cobre.co/v1/counterparties
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
Request body
{
"geo": "col",GeographyRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "cc",Account TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Colombia beneficiary - Bank",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"counterparty_fullname": "Beneficiary Trading Colombia SAS",Beneficiary NameRequirediLegal or display name of the counterparty beneficiary.
"beneficiary_institution": "1007",Bank CodeRequirediBank or institution code for the destination account.
"account_number": "1013777777",Account NumberRequirediBank account or CLABE number for the counterparty.
"counterparty_id_type": "nit",ID TypeRequirediType of identification document for the counterparty (e.g. nit, cc, rfc).
"counterparty_id_number": "9007654321"ID NumberRequirediIdentification number for the counterparty.
}
}
Response 201
{
"id": "cp_FxCopBank01",IdiUnique Cobre identifier for this resource.
"geo": "col",GeographyRequirediGeography code (e.g. col = Colombia, mex = Mexico).
"type": "cc",Account TypeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"alias": "Colombia beneficiary - Bank",AliasiDisplay name that helps identify it and clarify its purpose.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"counterparty_fullname": "Beneficiary Trading Colombia SAS",Beneficiary NameRequirediLegal or display name of the counterparty beneficiary.
"beneficiary_institution": "1007",Bank CodeRequirediBank or institution code for the destination account.
"account_number": "1013777777",Account NumberRequirediBank account or CLABE number for the counterparty.
"counterparty_id_type": "nit",ID TypeRequirediType of identification document for the counterparty (e.g. nit, cc, rfc).
"counterparty_id_number": "9007654321",ID NumberRequirediIdentification number for the counterparty.
"registered_account": falseRegistered AccountiCobre field at "metadata.registered_account" in this payload.
},
"created_at": "2026-08-01T15:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
Documentation for this step
Create a CounterpartyManaging Counterparties
Step 38 of 40 Colombia — Payout API step

Send the Fast Pay / ACH Payout

Create a Money Movement to the bank counterparty. Cobre routes it over Fast Pay (near real-time) when supported, otherwise ACH (batch) — the response type shows which rail was used. For cost-sensitive, non-urgent payouts, ask your KAM about an ACH-only routing tier to avoid Fast Pay's real-time premium.

POST https://api.cobre.co/v1/money_movements
Headers
AuthorizationBearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZnhwc3BfbGFjMDEifQ.Fx7mQ2pL9vK4wR8aH3gJ6yT0bZ5eN
Content-Typeapplication/json
idempotencyfx-payout-fp-002
Request body
{
"amount": 3000000,Amount (cents)RequirediAmount in cents — the last two digits are decimals.
"source_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBank01",Destination (counterparty)RequirediCobre id of the destination account or counterparty.
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Fast Pay/ACH"DescriptionRequirediHuman-readable label or note.
},
"external_id": "fx-payout-fp-002"External IDiYour own reference echoed by Cobre for reconciliation.
}
Response 201
{
"id": "mm_FxFastPay01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable detail for the current status.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Fast Pay/ACH"DescriptionRequirediHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-fp-002",External IDiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",COP Treasury BalanceRequirediCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBank01",Destination (counterparty)RequirediCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,Amount (cents)RequirediAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:25:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
⚡

Webhook outcomes — Money movement

Fires when the Fast Pay payout settles. If the bank had not supported Fast Pay, type would be 'ach' and settlement D+0/D+1 — reconciliation logic is identical.

Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide. Cobre Balance transactions are covered in the <b>Transaction</b> tab.

Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.

Event money_movements.status.completed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxFastPay01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:25:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxFastPay01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": ""DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Fast Pay/ACH"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-fp-002",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBank01",Destination IdiCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:25:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
F001Payment processing failed please try again.Payin and payout
F002NSF - Not Sufficient Funds in the designated account.Payin and payout
F004Daily transaction amount limit has been reached.Payin and payout
F005Amount exceeds the maximum allowed transaction limit.Payin and payout
F098Could not process the money movement at this time.Payin and payout
F099Could not process the money movement at this time.Payin and payout
Event money_movements.status.failed
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxFastPay01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:25:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxFastPay01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "NSF - Not Sufficient Funds in the designated account."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Fast Pay/ACH"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-fp-002",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBank01",Destination IdiCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:25:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):

Possible status codes
CodeDescriptionApplies to
R000Transaction rejected.Payin and payout
R001Inactive or blocked account.Payin and payout
R002Account and identification provided do not coincide.Payin and payout
R004ID not valid.Payout
R005Account does not exist.Payin and payout
R006Invalid account number.Payin and payout
R009Exceeds maximum allowed amount.Payin and payout
R010Account not authorized to debit.Payin and payout
R011Invalid Account type.Payout
R015Account not authorized to be credited.Payout
R018Payment rejected due invalid key.Payout
R023Payment cancelled by the user.Payin and payout
R024Exceeds maximum allowed number of transactions.Payout
R025Required information missing.Payout
R026Payment rejected due to unavailable bank services.Payin and payout
R027Account exceeds the maximum allowed transaction limit.Payin and payout
R034Account closed.Payin and payout
R085Bank processing error.Payout
Event money_movements.status.rejected
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxFastPay01Cmp",IdiUnique Cobre identifier for this resource.
"event_key": "money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:25:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "mm_FxFastPay01",IdiUnique Cobre identifier for this resource.
"status": {StatusiLifecycle status object for the resource or movement.
"state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected).
"code": "R018",CodeiProvider or Cobre status code when the state is failed or rejected.
"description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note.
},
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"description": "Colombia payout via Fast Pay/ACH"DescriptioniHuman-readable label or note.
},
"creator": "cli_fxpsp_lac01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user.
"external_id": "fx-payout-fp-002",External IdiYour own reference echoed by Cobre for reconciliation.
"checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.
"mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint.
"type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico).
"source_id": "acc_FxCopTreasury01",Source IdiCobre id of the source account or counterparty.
"destination_id": "cp_FxCopBank01",Destination IdiCobre id of the destination account or counterparty.
"currency": "cop",CurrencyiISO currency code (e.g. cop, mxn).
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"updated_at": "2026-08-01T15:25:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).
}
}

Payouts debit the source Cobre Balance while the movement is processing to lock funds. If the movement ends in failed, rejected, or canceled, Cobre posts a compensation credit (breb_credit or col_cb_credit). Payins credit the destination on completion only.

While the movement is in processing, Cobre debits the source Cobre Balance to lock the payout amount. Subscribe to accounts.balance.debit and money_movements.status.processing.

Event accounts.balance.debit
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxFastPay0Lk",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxFastPay01Lk",IdiUnique Cobre identifier for this resource.
"type": "col_cb_debit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxCopTreasury01",Account IdiCobre Balance account id affected by the event.
"amount": -3000000,AmountiAmount in cents — the last two digits are decimals.
"previous_balance": 8000000,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"currency": "COP",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T15:25:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"money_movement_id": "mm_FxFastPay01",Money Movement IdiMoney Movement that generated this balance transaction.
"description": "Colombia payout via Fast Pay/ACH",DescriptioniHuman-readable label or note.
"beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
"tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
}
}
}

On completion the locked funds are sent to the beneficiary. The processing debit remains on the ledger — no compensation credit is posted.

Event accounts.balance.debit
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxFastPay0Lk",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxFastPay01Lk",IdiUnique Cobre identifier for this resource.
"type": "col_cb_debit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxCopTreasury01",Account IdiCobre Balance account id affected by the event.
"amount": -3000000,AmountiAmount in cents — the last two digits are decimals.
"previous_balance": 8000000,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"currency": "COP",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T15:25:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T15:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"money_movement_id": "mm_FxFastPay01",Money Movement IdiMoney Movement that generated this balance transaction.
"description": "Colombia payout via Fast Pay/ACH",DescriptioniHuman-readable label or note.
"beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource.
"tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
}
}
}

If the movement reaches a terminal failed, rejected, or canceled state, Cobre credits the source Cobre Balance to release the lock (breb_credit for Bre-B, col_cb_credit for bank rails).

Event accounts.balance.credit
Headers
Content-Typeapplication/json
Example payload
{
"id": "ev_FxFastPay0Cp",IdiUnique Cobre identifier for this resource.
"event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed).
"created_at": "2026-08-01T15:25:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"content": {ContentiEvent-specific payload — same layout as the GET response for that resource.
"id": "trx_FxFastPay01Cp",IdiUnique Cobre identifier for this resource.
"type": "col_cb_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).
"account_id": "acc_FxCopTreasury01",Account IdiCobre Balance account id affected by the event.
"amount": 3000000,AmountiAmount in cents — the last two digits are decimals.
"previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload.
"current_balance": 3000000,Current BalanceiCobre field at "content.current_balance" in this payload.
"currency": "COP",CurrencyiISO currency code (e.g. cop, mxn).
"credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out.
"transaction_date": "2026-08-01T15:25:21Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC).
"created_at": "2026-08-01T15:25:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC).
"metadata": {MetadataiCustom key-value metadata attached to the resource.
"money_movement_id": "mm_FxFastPay01",Money Movement IdiMoney Movement that generated this balance transaction.
"description": "Colombia payout via Fast Pay/ACH",DescriptioniHuman-readable label or note.
"tracking_key": "",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key).
"sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource.
"sender_id": "",Sender IdiMetadata field "sender_id" attached to the resource.
"sender_account_number": ""Sender Account NumberiMetadata field "sender_account_number" attached to the resource.
}
}
}
Documentation for this step
Create a Money MovementMoney Movements ApprovalFast Pay & ACHMoney Movement Statuses
Step 39 of 40 Colombia — Payout Reconciliation

Reconcile the Fast Pay / ACH Payout

Close the Fast Pay/ACH payout leg on your ledger using external_id, the Money Movement id, and the response type (fast_pay or ach) to record which rail was actually used.

Mapping the webhook payload from an earlier step onto Platform ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valuePlatform ledger field
content.external_id
fx-payout-fp-002
 →
payout_external_id
content.id
mm_FxFastPay01
 →
cobre_mm_id
content.type
fast_pay
 →
payout_rail
fast_pay or ach — the rail Cobre selected for bank-account delivery.
content.status.state
completed
 →
payout_status
Step 40 of 40 Reconciliation Reconciliation

Reconcile End-of-Day Treasury Ledger

Close end-of-day positions across the USD Global, MXN Treasury, Named MXN, and COP Treasury balances using external_id, account_reference, fxq_id, and cbmm_id from every leg above. The Named Account model means each end-client's flows reconcile independently, while the platform still closes a single consolidated treasury position.

Mapping the webhook payload from an earlier step onto Platform ledger. No API call is made — this step closes the loop in your own system.

Cobre field & valuePlatform ledger field
content.external_id
fx-payout-fp-002
 →
last_leg_external_id
content.id
mm_FxFastPay01
 →
last_leg_mm_id
content.status.state
completed
 →
eod_status
All legs completed → close the day; any rejected/failed leg → carry forward to next-day reconciliation.