Step 1 of 5
Configuration
API step
Authenticate
Exchange API credentials for a short-lived Bearer token (~20 minutes). Reuse the same token string on every later call in this flow.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_demo_co_payin01",User IDRequirediAPI user id issued by Cobre (cli_…). "secret": "sk_live_2Hg8nP4qR7"SecretRequirediAPI secret from key creation — treat like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19wYXlpbjAxIn0.R2pP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ",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.}
Step 2 of 5
Configuration
API step
Subscribe to Payin Events
Register webhooks for Money Movement payin status and Cobre Balance credits. Direct Link creates a Money Movement — subscribe to both MM events and accounts.balance.credit (r2p_breb_credit on Bre-B completion). Verify deliveries with HMAC-SHA256.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19wYXlpbjAxIn0.R2pP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "url": "https://yourplatform.co/webhooks/cobre",Notification URLRequirediHTTPS endpoint that receives Cobre POST notifications. "description": "Direct Link payin lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "accounts.balance.credit" ], "event_signature_key": "WHr2pCo9xZ"Signature keyRequirediSecret you provide; Cobre HMAC-signs each delivery.}Response 201
{ "id": "sub_R2pPayin01",IdiUnique Cobre identifier for this resource. "url": "https://yourplatform.co/webhooks/cobre",Notification URLRequirediHTTPS endpoint that receives Cobre POST notifications. "description": "Direct Link payin lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "accounts.balance.credit" ], "event_signature_key": "******9xZ",Signature keyRequirediSecret you provide; Cobre HMAC-signs each delivery. "created_at": "2026-07-02T10:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 5
Direct Link Payin
API step
Register the Payer (r2p Counterparty)
Direct Link payins require an r2p counterparty representing the payer. Register once per customer — the same cp_… can be reused across sessions. Email and phone are required by the OAS for all Direct Link rails.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19wYXlpbjAxIn0.R2pP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequiredicol = Colombia. "type": "r2p",TypeRequiredir2p = Direct Link payer (PSE, Nequi, Bancolombia, Bre-B QR). "alias": "Bre-B QR payer - payin_ref_001",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Juliana Restrepo",Full nameRequirediPayer's full legal name. "counterparty_email": "payer@example.co",EmailRequirediRequired by the OAS for r2p counterparties — must be valid. "counterparty_id_type": "cc",ID typeRequirediColombian identification type. "counterparty_id_number": "5334623427",ID numberRequirediPayer identification number. "counterparty_phone": "+573123927834"PhoneRequirediPayer phone with country code (e.g. +57…). }}Response 201
{ "id": "cp_PayerR2P001",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequiredicol = Colombia. "type": "r2p",TypeRequiredir2p = Direct Link payer (PSE, Nequi, Bancolombia, Bre-B QR). "alias": "Bre-B QR payer - payin_ref_001",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_email": "payer@example.co",EmailRequirediRequired by the OAS for r2p counterparties — must be valid. "counterparty_fullname": "Juliana Restrepo",Full nameRequirediPayer's full legal name. "counterparty_id_number": "5334623427",ID numberRequirediPayer identification number. "counterparty_id_type": "cc",ID typeRequirediColombian identification type. "counterparty_phone": "+573123927834"PhoneRequirediPayer phone with country code (e.g. +57…). }, "created_at": "2026-07-02T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 5
Direct Link Payin
API step
Collect via Bre-B QR (Direct Link)
Create a Direct Link Money Movement: source = r2p payer counterparty, destination = your COP Cobre Balance. Set metadata.r2p_rail to breb_qr and metadata.valid_until for QR expiry (min 5 minutes, max 3 days — defaults to ~5 minutes if omitted). Render metadata.qr_value from the response as an EMVCo QR for the payer to scan in any Bre-B-enabled bank app. Amount is integer cents (500000 = COP 5,000.00). Reuse idempotency on retries — valid 24h.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19wYXlpbjAxIn0.R2pP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | payin-breb-qr-001 |
Request body
{ "amount": 500000,Amount (cents)Requiredi500000 cents = COP 5,000.00. "source_id": "cp_PayerR2P001",Payer counterpartyRequiredicp_… of the registered r2p payer. "destination_id": "acc_FundingCOP01",Destination balanceRequirediYour COP Cobre Balance that receives the payin. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_qr",R2P railRequiredibreb_qr for this demo — other Direct Link rails use the same pattern. "description_to_payer": "Platform payin",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Platform payin",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "valid_until": "2026-07-31T10:15:00Z"QR expiryRequirediISO 8601 UTC timestamp — QR expires at this time (min 5 minutes, max 3 days from creation). }, "external_id": "payin_ref_001"External IDiYour payin reference — primary reconciliation join key.}Response 201
{ "id": "mm_BrebQrPayin001",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": "QR generated — awaiting payer authorization."DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_qr",R2P railRequiredibreb_qr for this demo — other Direct Link rails use the same pattern. "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiCobre field at "metadata.qr_value" in this payload. "description_to_payee": "Platform payin",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform payin",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "valid_until": "2026-07-31T10:15:00Z"QR expiryRequirediISO 8601 UTC timestamp — QR expires at this time (min 5 minutes, max 3 days from creation). }, "creator": "cli_demo_co_payin01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payin_ref_001",External IDiYour payin reference — primary reconciliation join key. "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": "r2p_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": "cp_PayerR2P001",Payer counterpartyRequiredicp_… of the registered r2p payer. "destination_id": "acc_FundingCOP01",Destination balanceRequirediYour COP Cobre Balance that receives the payin. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,Amount (cents)Requiredi500000 cents = COP 5,000.00. "created_at": "2026-07-31T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-31T10:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
After the payer scans the QR and authorizes payment in their bank app, Cobre delivers this webhook. Mark the payin as received using external_id. Cobre also credits your Cobre Balance (r2p_breb_credit) — see the Transaction tab.
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.completedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BrebQrPayin001Cmp",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-07-31T10:14: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_BrebQrPayin001",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. "r2p_rail": "breb_qr",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiMetadata field "qr_value" attached to the resource. "description_to_payee": "Platform payin",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform payin",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "valid_until": "2026-07-31T10:15:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_demo_co_payin01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payin_ref_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": "r2p_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": "cp_PayerR2P001",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-31T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-31T10:14: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
| Code | Description | Applies to |
|---|---|---|
F001 | Payment processing failed please try again. | Payin and payout |
F002 | NSF - Not Sufficient Funds in the designated account. | Payin and payout |
F003 | R2P Payment link expired. | Payin |
F004 | Daily transaction amount limit has been reached. | Payin and payout |
F005 | Amount exceeds the maximum allowed transaction limit. | Payin and payout |
F098 | Could not process the money movement at this time. | Payin and payout |
F099 | Could not process the money movement at this time. | Payin and payout |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BrebQrPayin001Cmp",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-07-31T10:14: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_BrebQrPayin001",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": "F003",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "R2P Payment link expired."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_qr",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiMetadata field "qr_value" attached to the resource. "description_to_payee": "Platform payin",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform payin",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "valid_until": "2026-07-31T10:15:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_demo_co_payin01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payin_ref_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": "r2p_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": "cp_PayerR2P001",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-31T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-31T10:14: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
| Code | Description | Applies to |
|---|---|---|
R000 | Transaction rejected. | Payin and payout |
R001 | Inactive or blocked account. | Payin and payout |
R002 | Account and identification provided do not coincide. | Payin and payout |
R005 | Account does not exist. | Payin and payout |
R006 | Invalid account number. | Payin and payout |
R009 | Exceeds maximum allowed amount. | Payin and payout |
R010 | Account not authorized to debit. | Payin and payout |
R012 | The user has abandoned the transaction. | Payin |
R016 | Payment rejected due to timeout. | Payin |
R017 | Payment rejected due to expired money movement. | Payin |
R019 | Payment rejected due to incorrect amount. | Payin |
R020 | Payment rejected due to user authentication failure. | Payin |
R021 | Insufficient funds in payer account. | Payin |
R023 | Payment cancelled by the user. | Payin and payout |
R026 | Payment rejected due to unavailable bank services. | Payin and payout |
R027 | Account exceeds the maximum allowed transaction limit. | Payin and payout |
R034 | Account closed. | Payin and payout |
R081 | The counterparty registration has expired. | Payin |
R082 | The counterparty registration has been canceled. | Payin |
R084 | The counterparty registration has been rejected. | Payin |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BrebQrPayin001Cmp",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-07-31T10:14: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_BrebQrPayin001",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": "R016",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due to timeout."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_qr",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiMetadata field "qr_value" attached to the resource. "description_to_payee": "Platform payin",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform payin",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "valid_until": "2026-07-31T10:15:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_demo_co_payin01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payin_ref_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": "r2p_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": "cp_PayerR2P001",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-31T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-31T10:14:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}When a payin Money Movement completes, Cobre credits the destination Cobre Balance and delivers accounts.balance.credit. Transaction type matches the movement type — see GET /accounts/{id}/transactions OAS examples.
When the payin settles, Cobre credits the destination Cobre Balance.
Event
accounts.balance.creditHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BrebQrPayiCr",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-31T10:14: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_BrebQrPayin0Cr",IdiUnique Cobre identifier for this resource. "type": "r2p_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_FundingCOP01",Account IdiCobre Balance account id affected by the event. "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 500000,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-07-31T10:14:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-31T10:14:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_account_number": "",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_id": "",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "key_value": "",Key ValueiBre-B key value (e.g. @merchant123). "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "description": "Platform payin",DescriptioniHuman-readable label or note. "money_movement_id": "mm_BrebQrPayin001"Money Movement IdiMoney Movement that generated this balance transaction. } }}
Step 5 of 5
Reconciliation
Reconciliation
Reconcile the Direct Link Payin
Match the completion webhook to your platform ledger on external_id and mm_id. Cross-check the COP balance credit (r2p_breb_credit) via GET /accounts/{acct_id}/transactions. For D+1 close, export payins with POST /reports.
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 & value | Platform ledger field | |
content.external_id payin_ref_001 |
→ | payin_reference Primary join key — your payin or order id. |
content.id mm_BrebQrPayin001 |
→ | cobre_mm_id |
content.amount 500000 |
→ | received_amount_cents |
content.status.state completed |
→ | payin_status Map completed → RECEIVED; failed/rejected → review or retry. |
content.metadata.r2p_rail breb_qr |
→ | payin_rail |