Configurar transferencias de dinero

Crea un lote (payout) con una o varias transacciones de salida de dinero desde una cuenta Mercado Pago hacia uno o varios destinatarios, ya sean otras cuentas Mercado Pago o cuentas externas. El payout puede contener hasta 1000 transacciones, creadas y procesadas en una única solicitud, siempre que la cuenta de origen tenga saldo disponible.

Para hacerlo, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y utilizada en el backend. Puedes acceder a ella desde Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payoutsPOST. Envía los parámetros correspondientes siguiendo los respectivos cURLs de ejemplo y los campos indicados en las tablas de las pestañas a continuación, según el tipo de transacción que desees realizar.

curl
curl --location 'https://api.mercadopago.com/v1/payouts' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-enforce-signature: false' \
--header 'X-test-token: true' \
--header 'X-signature: true' \
--data-raw '{
    "external_reference": "000197",
    "config": {
        "notification_url": "https://link-your-webhook-notification.com"
    },
    "description": "Payout for seller commissions",
    "transactions": [
        {
            "type": "account",
            "description": "Payment to seller Beltrano",
            "account": {
                "email": "test@testuser.com"
            },
            "amount": {
                "currency": "MXN",
                "value": 1
            },
            "external_reference": "000197"
        }
    ]
}'

Si la ejecución se realiza correctamente, la solicitud devuelve un status code 202, lo que indica que el payout fue aceptado para su procesamiento. El siguiente ejemplo muestra un payout con dos transacciones:

json
{
    "id": "POP01KV681P6SJ38NQHWX3XK162SS",
    "external_reference": "0001234",
    "description": "description_root",
    "idempotency_key": "021957ca-7271-4f5e-8b8d-70ed87ce1a61",
    "created_date": "2026-06-15T14:17:36-06:00",
    "status": "created",
    "config": {
        "notification_url": "https://notification_url.com"
    },
    "transactions": [
        {
            "id": "TOP01KV681P6SJ38NQHWX3SF2WM22",
            "amount": {
                "currency": "MXN",
                "value": 11
            },
            "external_reference": "0001234"
        },
        {
            "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M",
            "amount": {
                "currency": "MXN",
                "value": 12
            },
            "external_reference": "0001235"
        }
    ]
}

Consulta el status y el resumen consolidado de un lote de transacciones (payout). Usa este endpoint para verificar cuántas transacciones se completaron con éxito, cuántas están pendientes o presentaron error.

Para ello, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago que se utiliza en el backend. Puedes acceder a ella en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. al endpoint /v1/payouts/{payout_id}GET, enviando el ID del payout (payout_id) obtenido en la respuesta al crear el lote.

curl
curl --location 'https://api.mercadopago.com/v1/payouts/{payout_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-test-token: true'

Si los datos enviados en la llamada son correctos, recibirás una respuesta como la siguiente:

json
{
    "id": "POP01KV681P6SJ38NQHWX3XK162SS",
    "status": "completed",
    "external_reference": "payout_external_reference",
    "config": {
        "notification_url": "https://notification_url.com"
    },
    "summary": {
        "pending": {
            "items": 0
        },
        "canceled": {
            "items": 0
        },
        "success": {
            "items": 0
        },
        "error": {
            "items": 2
        }
    }
}

Obtén información sobre todas las transacciones de un lote para confirmar que se crearon correctamente, consultar su status o verificar la información recibida en tus notificaciones.

Para ello, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payouts/{payout_id}/transactionsGET, reemplazando payout_id por el ID del payout obtenido en la respuesta al crear el lote.

curl
curl --location 'https://api.mercadopago.com/v1/payouts/{payout_id}/transactions?limit=10&offset=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-test-token: true'

Si los datos enviados en el llamado son correctos, recibirás una respuesta como la siguiente:

json
{
    "external_reference": "0001234",
    "config": {
        "notification_url": "https://notification_url.com"
    },
    "paging": {
        "limit": 50,
        "offset": 0,
        "total": 2
    },
    "transactions": [
        {
            "id": "TOP01KV681P6SJ38NQHWX3T9PHH3M",
            "created_date": "2026-06-15T14:17:38.606-06:00",
            "last_update_date": "2026-06-15T14:17:38.606-06:00",
            "external_reference": "0001234",
            "description": "description_transaction_01",
            "status": "success",
            "status_detail": "accredited",
            "amount": {
                "currency": "MXN",
                "value": 11
            }
        },
        {
            "id": "TOP01KV681P6SJ38NQHWX3SF2WM22",
            "created_date": "2026-06-15T14:17:38.606-06:00",
            "last_update_date": "2026-06-15T14:17:38.606-06:00",
            "external_reference": "0001235",
            "description": "description_transaction_02",
            "status": "success",
            "status_detail": "accredited",
            "amount": {
                "currency": "MXN",
                "value": 12
            }
        }
    ]
}

Obtén información sobre una transacción específica dentro de un lote para confirmar que se creó correctamente, consultar su status o verificar la información recibida en tus notificaciones.

Para ello, envía una solicitud con tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago y que se utiliza en el backend. Puedes acceder a ella a través de Tus integraciones > Datos de la integración > Pruebas > Credenciales de prueba. al endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}GET, reemplazando payout_id por el ID del payout y transaction_id por el ID de la transacción obtenidos previamente.

curl
curl --location 'https://api.mercadopago.com/v1/payouts/{payout_id}/transactions/{transaction_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-test-token: true'

Si los datos enviados en el llamado son correctos, recibirás una respuesta como la siguiente:

json
{
    "id": "TOP01KV681P6SJ38NQHWX3SF2WM22",
    "created_date": "2026-06-15T14:17:38.606-06:00",
    "last_update_date": "2026-06-15T14:17:38.606-06:00",
    "external_reference": "0001234",
    "description": "description_transaction_01",
    "status": "success",
    "status_detail": "accredited",
    "amount": {
        "currency": "MXN",
        "value": 11
    }
}

Programa transferencias utilizando el Scheduler, un recurso que automatiza la ejecución de las transacciones programadas y garantiza que cada transferencia ocurra exactamente en la fecha y hora definidas, de forma segura y sin duplicaciones, registrando todos los pasos para facilitar el seguimiento y la auditoría.

Para programar transferencias, envía una solicitud con tu Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales y nunca debe exponerse en el frontend. al endpoint /v1/payoutsPOST incluyendo el campo schedule_date en el body. Además, incluye los campos necesarios según el tipo de transacción que desees realizar siguiendo las indicaciones de la pestaña correspondiente.

curl
curl --location 'https://api.mercadopago.com/v1/payouts' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-enforce-signature: false' \
--header 'X-test-token: true' \
--header 'X-signature: true' \
--data-raw '{
    "external_reference": "000197",
    "config": {
        "notification_url": "https://link-your-webhook-notification.com"
    },
    "description": "Payout for seller commissions",
    "schedule_date": "2026-12-31T14:30:00",
    "transactions": [
        {
            "type": "account",
            "description": "Payment to seller Beltrano",
            "account": {
                "email": "test@testuser.com"
            },
            "amount": {
                "currency": "MXN",
                "value": 1
            },
            "external_reference": "000197"
        }
    ]
}'

Si la ejecución se realiza correctamente, la solicitud devuelve un status code 202, lo que indica que el payout fue aceptado para su procesamiento.

Cancela una transacción programada para interrumpir una operación de transferencia incorrecta o no deseada antes de la liquidación financiera. Este procedimiento es irreversible y preserva la integridad operativa y la trazabilidad para auditoría.

Para cancelar una transacción, envía una solicitud con tu Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales y nunca debe exponerse en el frontend. al endpoint /v1/payouts/{payout_id}/transactions/{transaction_id}/cancelPUT, utilizando el ID del payout (payout_id) y el ID de la transacción (transaction_id).

curl
curl --location --request PUT 'https://api.mercadopago.com/v1/payouts/{payout_id}/transactions/{transaction_id}/cancel' \
--header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-enforce-signature: false' \
--header 'X-test-token: true' \
--header 'X-signature: true' \
--data '{
  "comments": "delete because the payment was canceled",
  "deleted_by": "user_123"
}'

Si la ejecución fue exitosa, recibirás como respuesta un status code 204, indicando que la transacción fue cancelada.