Procesando Reembolsos en México

En México, el reembolso de un payin se gestiona a través de un endpoint dedicado: Devolver un Movimiento de Dinero (POST /money_movements_return). A diferencia de Colombia —donde un reembolso debe iniciarse como un nuevo payout porque los datos del pagador no están disponibles— en México simplemente referencias la transacción de crédito que deseas devolver, y Cobre se encarga del resto.

Esto funciona porque las transacciones de crédito SPEI conservan la información del remitente. Cuando llamas al API de Devolución, Cobre utiliza esa información para crear automáticamente la contraparte de destino y el Money Movement de devolución de vuelta al pagador original. Nunca necesitas buscar ni registrar la cuenta del pagador por tu cuenta.

Las devoluciones en México actualmente son compatibles con transacciones de crédito SPEI (spei_credit).

Acciones Realizadas en una Devolución

Una devolución en México se centra en un único endpoint. Las acciones de soporte son:

Acción	Endpoint	Propósito
Identificar el crédito a devolver	Obtener una Transacción / Obtener transacciones de una cuenta	Encuentra la transacción `spei_credit` y su `transaction_id`.
Devolver el crédito	Devolver un Movimiento de Dinero	Inicia la devolución; Cobre crea automáticamente la contraparte y el Money Movement `spei_return`.
Rastrear el resultado	Obtener un Movimiento de Dinero	Sigue el Money Movement `spei_return` resultante hasta su completación.

Combinaciones de Devolución Permitidas

Las devoluciones están limitadas a créditos SPEI en proveedores de cuenta compatibles:

País	Tipo de transacción permitido	ID de proveedor de cuenta
Mex	`spei_credit`	`pr_mex_cobre3`
Mex	`spei_credit`	`pr_mex_072` (próximamente)
Mex	`spei_credit`	`pr_mex_014` (próximamente)
Mex	`spei_credit`	`pr_mex_012` (próximamente)

No es posible realizar Money Movements spei_return entre dos cuentas pr_mex_cobre3.

Este tipo de Money Movement no es compatible con la funcionalidad de Vinculación de Cuentas.

Cómo Comenzar

Antes de Usar el API de Devoluciones

Localiza una transacción de crédito elegible

El transaction_id debe referenciar una transacción spei_credit existente ya registrada en un Cobre Balance o Cuenta Connect, que coincida con una de las combinaciones permitidas anteriores. Las devoluciones de transacciones de débito, o de créditos en rieles distintos a SPEI, son rechazadas.

Confirma el monto

Una devolución envía de vuelta el monto completo de la transacción de crédito referenciada. El monto se toma de la transacción original — no lo estableces en la solicitud.

Prepara una descripción

El metadata.description de la devolución es requerido (1–40 caracteres). Si el riel lo soporta, esta descripción acompaña la devolución hasta su destino.

Devolviendo un Crédito SPEI

Paso 1 — Encuentra la Transacción de Crédito

Recupera la transacción spei_credit que deseas devolver. Su metadata contiene la información del remitente (sender_name, sender_id, sender_account_number, tracking_key) que Cobre utilizará para enrutar la devolución — no necesitas extraerla ni pasarla tú mismo.

{
  "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"
  }
}

Paso 2 — Llama al API de Devolución

Envía el transaction_id y un metadata.description de devolución. No se requiere contraparte, monto, origen ni destino en la solicitud — Cobre los deriva de la transacción original.

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

Tanto transaction_id como metadata (con su description requerido) son obligatorios.

Paso 3 — Inspecciona la Respuesta

Una llamada exitosa devuelve un Money Movement de tipo spei_return, con geo: mex, currency: mxn y status.state: initiated. El external_id repite el transaction_id que devolviste, por lo que el vínculo con el crédito original se preserva automáticamente.

{
  "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
}

Ten en cuenta que para las devoluciones:

destination_id referencia una contraparte que Cobre creó automáticamente, de tipo mm_return.

external_id siempre contiene el transaction_id usado para iniciar la devolución.

reference en el metadata de la respuesta contiene la fecha de creación de la devolución en formato YYYYMMDD.

batch_id, mm_approval_id quedan vacíos y checker_approval permanece en false — las devoluciones no pasan por flujos de aprobación.

Qué Esperar Después de Enviar una Devolución

Se crea un nuevo Money Movement spei_return. Representa los fondos que regresan al pagador original y puede rastrearse como cualquier otro Money Movement, incluso a través de Notificaciones y Suscripciones.

Se crea una nueva contraparte. Cobre registra automáticamente una contraparte de tipo mm_return como destino de la devolución; tú no la gestionas.

Se registra una transacción spei_debit. Cuando la devolución se liquida, aparece un spei_debit en el Cobre Balance o Cuenta Connect de origen, compensando el crédito original. El registro de transacción spei_return acompañante se vincula de vuelta a través de su money_movement_id y tracking_key.

Concilia mediante external_id. Dado que el external_id de la respuesta es igual al transaction_id original, puedes hacer coincidir las devoluciones con sus créditos de origen directamente, en tu libro de contabilidad y en Reports.

Rastrea el estado final. La devolución progresa a través de initiated → processing → completed (o returned/rejected/failed, que llevan un code y description).

Procesando Reembolsos en México

Acciones Realizadas en una Devolución#

Combinaciones de Devolución Permitidas#

Cómo Comenzar#

Antes de Usar el API de Devoluciones#

Devolviendo un Crédito SPEI#

Paso 1 — Encuentra la Transacción de Crédito#

Paso 2 — Llama al API de Devolución#

Paso 3 — Inspecciona la Respuesta#

Qué Esperar Después de Enviar una Devolución#