Subclient Management - Payins Colombia

🚧 This flow is in active development.

Subclients are Cobre's model for identifying the end merchant behind an aggregator — a registered identity, screened before it can operate, that travels with every transaction. This guide covers the first Colombia implementation of that model: attaching a Subclient to a Request to Pay (R2P) PSE Payin, so the end merchant behind the transaction can be identified.

How It Works

Register the Subclient — Call POST /v1/subclients with the merchant's legal, tax, and beneficial ownership information. This data goes through an asynchronous screening process.

Wait for approval — The Subclient starts in processing and moves to approved (or rejected/failed) once screening completes.

Create the R2P PSE Money Movement — Once approved, pass the Subclient's id as the new root-level subclient_id field when calling POST /v1/money_movements for an r2p_pse Payin.

Prerequisites

A Cobre Balance account in Colombia to receive funds.

A Counterparty of type r2p representing the payer (see Create a Counterparty).

Access to Create a Subclient and Create a Money Movement.

Step-by-Step Guide

Step 1 – Register the Subclient

Call the Create a Subclient POST

The Subclient is created immediately in processing status while screening runs in the background:

Keep the returned id (sc_...) — this is the subclient_id you'll use in Step 3.

Step 3 – Wait for Subclient screening

Subclient screening is asynchronous:

The Subclient starts in processing.

Cobre reviews the submitted information.

The Subclient moves to approved or rejected. failed is returned in exceptional cases where a technical error occurs.

Poll Obtain one Subclient or subscribe to subclient.processing, subclient.approved, subclient.rejected, and subclient.failed events — see Subclients notifications — to track the status change.

A rejected Subclient cannot be resubmitted — create a new Subclient record with corrected information instead.

A Subclient only needs to be registered and approved once — it can then be reused across multiple R2P PSE Money Movements.

Step 4 – Create the R2P PSE Money Movement with `subclient_id`

With the Subclient approved, create the R2P PSE Payin by calling Create a Money Movement as you normally would for r2p_pse (see Direct Link for the full rail details), and include the new root-level subclient_id field alongside source_id, destination_id, amount, and metadata.

📌

subclient_id is optional by default, but mandatory for agreggators/PSP clients once this requirement is enabled for your account.

If you are an agreggator/PSP, omitting subclient_id — or sending an invalid one or one that doesn't exist — causes the Money Movement request to fail with error MM034. No Money Movement is created in that case.

If your client is not a PSP, subclient_id remains fully optional on r2p_pse Money Movements.

Core Concepts and Terminology

Subclient: A merchant identity record created via POST /subclients or Subclients module in the portal. Must be approved before its id can be used as subclient_id on a Money Movement.

subclient_id: A new root-level field on POST /money_movements. For r2p_pse Payins in Colombia, it links the Money Movement to a previously approved Subclient. Mandatory for agreggators/PSP clients once enabled.

Agreggators/PSP (Payment Service Provider): A client who uses Cobre's services to offer them to their own clients.

Things to Keep in Mind

A Subclient must be approved before its id can be used as subclient_id.

A rejected Subclient cannot be resubmitted — create a new one.

Once approved, a Subclient can be reused across multiple R2P PSE Money Movements.

Today this requirement only applies to r2p_pse Payins in Colombia.

Frequently Asked Questions

Do I need to create a new Subclient for every R2P PSE Money Movement?
No. Once approved, a Subclient can be reused across as many R2P PSE Money Movements as needed.

What happens if I omit subclient_id and I'm a PSP/aggregator?
The Money Movement request fails with error MM034 and no Money Movement is created.

Is this flow available through the Portal?
Subclient creation is available but Money Movement creation for this flow is currently API-only.

Is subclient_id required for other R2P rails (Nequi, Bancolombia, Bre-B) or for Payouts?
No. Today this applies only to r2p_pse Payins in Colombia.

Subclient Associated Movements

Subclient Management - Payins Colombia#

How It Works#

Prerequisites#

Step-by-Step Guide#

Step 1 – Register the Subclient#

Step 3 – Wait for Subclient screening#

Step 4 – Create the R2P PSE Money Movement with subclient_id#

Core Concepts and Terminology#

Things to Keep in Mind#

Frequently Asked Questions#

Subclient Management - Payins Colombia

How It Works

Prerequisites

Step-by-Step Guide

Step 1 – Register the Subclient

Step 3 – Wait for Subclient screening

Step 4 – Create the R2P PSE Money Movement with `subclient_id`

Core Concepts and Terminology

Things to Keep in Mind

Frequently Asked Questions