Processing Refunds in Mexico

In Mexico, refunding a payin is handled by a dedicated endpoint: Return a Money Movement (POST /money_movements_return). Unlike Colombia — where a refund must be initiated as a brand new payout because the payer's details are not available — in Mexico you simply reference the credit transaction you want to return, and Cobre takes care of the rest.

This works because SPEI credit transactions retain the sender's information. When you call the Return API, Cobre uses that information to automatically create the destination counterparty and the return money movement back to the original payer. You never have to look up or register the payer's account yourself.

Returns in Mexico are currently supported for SPEI credit transactions (spei_credit).

Actions performed on a Return

A return in Mexico centers on a single endpoint. The supporting actions are:

Action	Endpoint	Purpose
Identify the credit to return	Obtain one Account Transactions / Obtain one Transaction	Find the `spei_credit` transaction and its `transaction_id`.
Return the credit	Return a Money Movement	Initiate the return; Cobre auto-creates the counterparty and the `spei_return` money movement.
Track the result	Obtain one Money Movement	Follow the resulting `spei_return` money movement to completion.

Allowed return combinations

Returns are limited to SPEI credits on supported account providers:

Country	Allowed transaction type	Account provider id
Mex	`spei_credit`	`pr_mex_cobre3`
Mex	`spei_credit`	`pr_mex_072` (coming soon)
Mex	`spei_credit`	`pr_mex_014` (coming soon)
Mex	`spei_credit`	`pr_mex_012` (coming soon)

It is not possible to perform spei_return money movements between two pr_mex_cobre3 accounts.

This type of money movement is not compatible with the Account Linkeage functionality.

How to Get Started

Before using the Returns API

Locate an eligible credit transaction

The transaction_id must reference an existing spei_credit transaction already posted to a Cobre Balance or Connect Account, matching one of the allowed combinations above. Returns of debit transactions, or of credits on rails other than SPEI, are rejected.

Confirm the amount

A return sends back the full amount of the referenced credit transaction. The amount is taken from the original transaction — you do not set it in the request.

Prepare a description

The return metadata.description is required (1–40 characters). If the rail supports it, this description accompanies the return to its destination.

Returning a SPEI credit

Step 1 — Find the credit transaction

Retrieve the spei_credit transaction you intend to return. Its metadata carries the sender information (sender_name, sender_id, sender_account_number, tracking_key) that Cobre will use to route the return — you do not need to extract or pass any of it yourself.

{
  "id": "trx_1232145215",
  "type": "spei_credit",
  "amount": 5000,
  "currency": "mxn",
  "credit_debit_type": "credit",
  "metadata": {
    "sender_name": "Fernando Alonso",
    "sender_id": "XEXX010101000",
    "sender_account_number": "1000100010001000",
    "tracking_key": "20240719CCbbbb6AAAAAA",
    "account_reference": "703011052301000014"
  }
}

Step 2 — Call the Return API

Send the transaction_id and a return metadata.description. No counterparty, amount, source, or destination is required in the request — Cobre derives them from the original transaction.

{
  "transaction_id": "trx_1232145215",
  "metadata": {
    "description": "Returned transaction"
  }
}

Both transaction_id and metadata (with its required description) are mandatory.

Step 3 — Inspect the response

A successful call returns a money movement of type spei_return, with geo: mex, currency: mxn, and status.state: initiated. The external_id echoes the transaction_id you returned, so the link to the original credit is preserved automatically.

{
  "id": "mm_123456789012",
  "external_id": "trx_1232145215",
  "creator": "usr_bGcdf26rR4",
  "type": "spei_return",
  "geo": "mex",
  "status": {
    "state": "initiated",
    "code": "",
    "description": ""
  },
  "source_id": "acc_KJnAkypWSc",
  "destination_id": "cp_012345678910",
  "currency": "mxn",
  "amount": 5000,
  "metadata": {
    "description": "Returned Transaction",
    "tracking_key": "20240624mmbgu7gkQwofrb9o",
    "reference": "0123456",
    "cep_url": ""
  },
  "created_at": "2024-06-24T15:37:37Z",
  "updated_at": "2024-06-24T15:37:38Z",
  "checker_approval": false
}

Note that for returns:

destination_id references a counterparty that Cobre created automatically, with type mm_return.

external_id always contains the transaction_id used to initiate the return.

reference in the response metadata contains the return creation date in YYYYMMDD format.

batch_id, mm_approval_id stay empty and checker_approval stays false — returns are not sent through approval flows.

What to expect after sending a Return

A new spei_return money movement is created. It represents the funds going back to the original payer and can be tracked like any other money movement, including via Notifications & Subscriptions.

A new counterparty is created. Cobre auto-registers a counterparty of type mm_return as the destination of the return; you do not manage it.

A spei_debit transaction is posted. When the return settles, a spei_debit appears on the originating Cobre Balance or Connect Account, offsetting the original credit. The accompanying spei_return transaction record links back through its money_movement_id and tracking_key.

Reconcile via external_id. Because the response external_id equals the original transaction_id, you can match returns to their source credits directly, in your ledger and in Reports.

Track final state. The return progresses through initiated → processing → completed (or returned/rejected/failed, which carry a code and description).

Processing Refunds in Mexico

Actions performed on a Return#

Allowed return combinations#

How to Get Started#

Before using the Returns API#

Returning a SPEI credit#

Step 1 — Find the credit transaction#

Step 2 — Call the Return API#

Step 3 — Inspect the response#

What to expect after sending a Return#