Bulk Money Movements

The Bulk Money Movements API allows you to process multiple Money Movements from a single file upload, making it ideal for high-volume Payout and operational batch processing.

Bulk is commonly used to:

Execute mass disbursements (e.g., payroll, vendor payments, refunds).

Reduce the number of API calls by sending many Money Movements in one request.

Create the JSON file with the list of Money Movements

The initial step is to create your JSON file that indicates the money movements that need to be processed.

JSON file requirements

Key rules for the input JSON file:

The payload must be a JSON array: starts with [ and ends with ].

Each Money Movement request must be inside { } and separated by commas. Here is an example format layout:

[ 
   { 
       money_movement_request_1
   },
   {
       money_movement_request_2
   }
]

Comments are not allowed (e.g., // ...). For example:

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",     //Comments are not allowed
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"MX Payment - Saldo Crobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    }
]

Amount must be sent in the smallest currency unit (e.g., 100.00 MXN → 10000).

The maximum input file size is approximately 4.7 MB.

Supported types

Bulk money movements allow two types of money movement objects.

Using an already created counterparty_id: The following represents a valid JSON format containing two Create a Money Movement request bodies which is accepted by bulk money movements:

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"SPEI Payment - Saldo Cobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    },
    {
        "amount":500,
        "source_id":"acc_aJmUHHWDOB",
        "destination_id":"cp_c0jhj7gn7v",
        "metadata":
        {
            "description":"ACH Payment Bancolombia",
        },
        "external_id":"BBM_32656"
    }
]

Without a previously created counterparty_id: The process allows you to create a counterparty directly by including the Create a Counterparty request body details within the destination. The following represents a valid JSON format containing one SPEI money movement with a counterparty valid destination and is accepted by bulk money movements:

[
    {
        "amount": 1,
        "source_id": "acc_poyBrvkPRI",
        "destination":
        {
            "geo": "mex",
            "type": "clabe",
            "alias": "cccc",
            "metadata":
            {
                "account_number": "710969000037970288",
                "counterparty_fullname": "Company",
                "counterparty_id_type": "rfc",
                "counterparty_id_number": "ND"
            }
        },
        "metadata":
        {
            "description": "TEST PRO BMM",
            "reference": "009911"
        }
    }

]

Supported counterparties

Payout via Bulk supports the following destination types:

Colombia Payout Counterparties

Mexico Payout Counterparties

Destination Type	Counterparty Type	Rails
Checking Account	`cc`	Fast Pay / ACH
Saving Account	`ch`	Fast Pay / ACH
Electronic Deposit	`dp`	Fast Pay / ACH
BreB Key	`breb_key`	BreB / Fast Pay* / ACH*
Cobre Balance	`cobre_balance`	Fast Pay

Counterparty idempotency in Bulk

The bulk money movement process verifies the existence of the counterparty before creation by ensuring it hasn't been created previously. This is accomplished by checking the idempotency through the concatenation of the following fields:

Counterparty Type	Concatenated Fields
`cc`	geo, type, account_number, beneficiary_institution, counterparty_fullname, counterparty_id_number, counterparty_id_type, counterparty_email, and counterparty_phone
`ch`	geo, type, account_number, beneficiary_institution, counterparty_fullname, counterparty_id_number, counterparty_id_type, counterparty_email, and counterparty_phone
`dp`	geo, type, account_number, beneficiary_institution, counterparty_fullname, counterparty_id_number, counterparty_id_type, counterparty_email, and counterparty_phone
`cobre_balance`	geo, type, cobre_tag, counterparty_email, counterparty_fullname, counterparty_id_number, counterparty_id_type, and counterparty_phone

Authorization Workflow (optional)

You can send your Bulk Money Movement for approval by setting the checker_approval flag to true in the request header.

If you choose to send the bulk for approval, all the Money Movements within the file will be submitted for approval and, if no validation or technical error is encountered, the money movements will be created with a pending_approval status.

To learn more about approvals, please refer to Bulk Money Movements Approval ~~or approve individual money movements documentation~~.

Bulk lifecycle

A Payout through Bulk Money Movement follows a simple lifecycle:

1. Build the JSON File
Build the JSON file with all Money Movements to be processed.

2. Upload the file
Upload the file to create the Bulk Money Movement.

3. Validation Process
Cobre validates the file and starts processing each Money Movement, tracking the bulk process status (e.g., validating, processing, completed, etc.).

4. Money Movement creation
Money Movements created through Bulk will include a batch_id (useful for reconciliation).

5. Receive status updates
Track progress using retrieval endpoints and/or Webhooks.

Even if a Money Movement encounters a functional error, the Money Movement object can still be created and the error will be reflected in its status description.

Bulk money movement process

The platform will receive and validate a file containing multiple money movements.
Upon validation, the execution timestamp and total number of payments will be updated.
Then the process will execute all the money movements listed in the file and complete the process by updating the execution time and the total number of payments.

Bulk money movement statuses

Validating: Initial status of the bulk money movement. Reflects the moment when the process started validating the file format.

Failed: Status that indicates that the validation process has encountered an error.

Processing: Status that indicates that the file has been validated, and each money movement in the file will be processed.

Pending Approval: Status that indicates that the file is awaiting for approval.

Canceled: Status that indicates that the bulk money movement processes has been canceled,.

Completed: Status that indicates that the bulk money movement processes has been completed.

The bulk money movement will only validate the uploaded file's format. If a functional error occurs, the Money Movement object will still be created, and the error (from the Error Dictionary) will be included in the description of the money movement.

Allowed file formats

As we continue to evolve the bulk money movement process to incorporate new available formats, the following are allowed:

File Format	Object Format	Maximum Size
JSON	Money Movement request	4.7 Mb

Actions performed on Bulk Money Movements

🔑 Create

🔍 Retrieval

👍 Approval

Description: Bulk Money Movement Creation.
What to expect after the action: Bulk Money Movement is created in Cobre.
📘 Learn more:

🔗 Create a Bulk Money Movement

How to Get Started

Before you begin, we recommend reviewing the following considerations.

Before using this API

Prepare your JSON file

Create a JSON array containing all Money Movement requests.

Follow the JSON file requirements.

Ensure each entry uses either an existing destination_id or an inline destination object.

Consider leveraging Counterparty idempotency according to the concatenated fileds per counterparty type.

Ensure the correct money movement request

Make sure that the money movement fields are correctly represented:

Remember that the combination between source and destination should have a valid money movement combination.

The source_id has to be valid and exist.

The destination_id (if provided) has to be valid and exist.

The fields within the metadata will need to be aligned depending on the source and destination money movement combination.

The amount is the smallest unit of the currency (e.g., 100.00 MXN should be represented as 10000).

The maximun input json file size of is approximately 4.7 MB.

Consider usign external_id to link each payment to an external object or process

Consider implemeting the checker_approval logic.

Send your Bulk money movement for approval (optional)

Use the Bulk Money Decision Endpoint to provide the decision outcome on the Bulk.

See Bulk Money Movements Approval Workflow for more details.

Implement Webhooks to track Money Movement status

To stay informed about the status of Payout transactions, we strongly recommend implementing Webhooks. Webhooks notify your system when a payment is initiated, processed, completed, or failed. Also subscribe to the required events to receive notifications about transaction debits and credits.

See Notifications for more details.

What to expect after using this API

Bulk process status updates

The bulk process transitions through states such as validating, processing, and completed.

Reconcile using batch_id

Money Movements created from bulk include a batch_id, enabling correlation between the batch and each resulting payout.

Handle errors per Money Movement

Some Money Movements may fail due to functional requirements. Use retrieval endpoints and Webhooks to identify and retry only the affected entries.

Bulk Money Movements

Create the JSON file with the list of Money Movements#

JSON file requirements#

Supported types#

Supported counterparties#

Counterparty idempotency in Bulk#

Authorization Workflow (optional)#

Bulk lifecycle#

Bulk money movement process#

Bulk money movement statuses#

Allowed file formats#

Actions performed on Bulk Money Movements#

How to Get Started#

Before using this API#

What to expect after using this API#