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_credit on 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; phone must match the payer's Nequi wallet — Cobre uses it to send the push notification.
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": "Nequi 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"PhoneRequirediRequired for Nequi push — must match the payer's Nequi wallet (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": "Nequi 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"PhoneRequirediRequired for Nequi push — must match the payer's Nequi wallet (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 Nequi (Direct Link)
Create a Direct Link Money Movement: source = r2p payer counterparty, destination = your COP Cobre Balance. Set metadata.r2p_rail to nequi — Cobre sends a push notification to the payer's Nequi app (no payment_link). The payer has 15 minutes to accept or reject. 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-nequi-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": "nequi",R2P railRequiredinequi 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. "redirect_url": "https://yourplatform.co/payin/return"Return URLRequirediOptional landing page after the payer completes or rejects in the Nequi app. }, "external_id": "payin_ref_001"External IDiYour payin reference — primary reconciliation join key.}Response 201
{ "id": "mm_NequiPayin001",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_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. "r2p_rail": "nequi",R2P railRequiredinequi for this demo — other Direct Link rails use the same pattern. "redirect_url": "https://yourplatform.co/payin/return"Return URLRequirediOptional landing page after the payer completes or rejects in the Nequi app. }, "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_nequi",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 accepts the Nequi push and funds settle, Cobre delivers this webhook. Mark the payin as received using external_id. Cobre also credits your Cobre Balance (r2p_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_NequiPayin001Cmp",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: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_NequiPayin001",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_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. "r2p_rail": "nequi",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://yourplatform.co/payin/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "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_nequi",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: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
| 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_NequiPayin001Cmp",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: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_NequiPayin001",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. "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. "r2p_rail": "nequi",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://yourplatform.co/payin/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "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_nequi",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: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
| 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_NequiPayin001Cmp",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: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_NequiPayin001",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. "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. "r2p_rail": "nequi",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://yourplatform.co/payin/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "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_nequi",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:20: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_NequiPayinCr",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: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": "trx_NequiPayin00Cr",IdiUnique Cobre identifier for this resource. "type": "r2p_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:20:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-31T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_NequiPayin001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Platform payin",DescriptioniHuman-readable label or note. "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "r2p_method": "nequi",R2p MethodiR2P channel for r2p_credit transactions (e.g. pse). "tracking_key": "",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "sender_id": ""Sender IdiMetadata field "sender_id" attached to the resource. } }}
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_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_NequiPayin001 |
→ | 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 nequi |
→ | payin_rail |