Enlaces de vinculación

Envía una solicitud a /v1/payment-method-enrollmentsPOST utilizando el APP_ACCESS_TOKENAccess Token de producción de la aplicación del integrador. Disponible en Tus integraciones > Credenciales de producción. de producción para generar el link que compartirás con el comprador.

Parámetros

curl -X POST \
  'https://api.mercadopago.com/v1/payment-method-enrollments' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile_id": "7036b192b541454fa9b9990660dfa1b5",
    "expiration_time": "P7D"
  }'

Si la solicitud es exitosa, recibirás una respuesta 201 Created con el siguiente body:

json
{
  "id": "bea0ffb8-6c94-40a3-bc31-c2e7a0d46ed7",
  "profile_id": "7036b192b541454fa9b9990660dfa1b5",
  "enrollment_link": "https://mpago.la/1alzDGT",
  "state": "created",
  "expiration_time": "P7D",
  "expired_date": "2026-06-05T17:11:41.000-03:00",
  "created_date": "2026-05-29T17:11:41.000-03:00",
  "last_update_date": "2026-05-29T17:11:41.000-03:00"
}

Guarda el valor de id para consultar el estado del link. El valor de enrollment_link es la URL que debes compartir con el comprador.

Errores posibles

Comparte el valor de enrollment_link con el comprador por el canal que prefieras: WhatsApp, email, SMS u otro. El comprador abre la URL en su navegador, completa el formulario de Mercado Pago con los datos de su tarjeta y la tarjeta queda vinculada al perfil. El vendedor no participa de este paso ni accede a los datos de la tarjeta.

En lugar de consultar el estado del link mediante llamados a la API, puedes recibir notificaciones en tiempo real. Cuando el comprador vincula su tarjeta exitosamente, Automatic Payments envía un webhook con el cambio de estado del perfil a READY.

Para configurar las notificaciones:

1. Accede a Tus integraciones en el Panel del Desarrollador y selecciona tu aplicación.
2. Accede a Webhooks y registra la URL HTTPS de tu endpoint receptor. El endpoint debe responder con 200 en menos de 22 segundos.
3. Activa el evento Perfil de Pago (payment_profile).
4. Copia la clave secreta generada para validar la firma x-signature de cada notificación entrante.

Cuando el comprador vincula su tarjeta exitosamente, recibirás un webhook con el siguiente payload:

json
{
  "id": "7036b192b541454fa9b9990660dfa1b5",
  "type": "payment_profile",
  "action": "payment_profile.updated",
  "version": 1,
  "live_mode": true,
  "data": {
    "status": "ready",
    "payment_methods": [{
      "unique_id": "pm_001",
      "type": "credit_card",
      "status": "ready",
      "card_id": 9453094596
    }]
  }
}

El campo version es un contador incremental por perfil. Procesa siempre la notificación con mayor version y descarta las anteriores si llegan fuera de orden.

Para conocer más sobre el formato de las notificaciones y cómo validar la firma, consulta nuestra documentación de Webhooks.

Envía una solicitud a /v1/payment-method-enrollments/{id}GET incluyendo el id del link en el path para verificar si el comprador completó la vinculación.

curl -X GET \
  'https://api.mercadopago.com/v1/payment-method-enrollments/bea0ffb8-6c94-40a3-bc31-c2e7a0d46ed7' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Si el comprador completó la vinculación, recibirás una respuesta 200 OK con el siguiente cuerpo:

json
{
  "id": "bea0ffb8-6c94-40a3-bc31-c2e7a0d46ed7",
  "profile_id": "7036b192b541454fa9b9990660dfa1b5",
  "enrollment_link": "https://mpago.la/1alzDGT",
  "state": "vinculated",
  "expiration_time": "P7D",
  "expired_date": "2026-06-05T17:11:41.000-03:00",
  "created_date": "2026-05-29T17:11:41.000-03:00",
  "last_update_date": "2026-05-29T18:02:14.000-03:00"
}

Cuando state es vinculated, la tarjeta ya está registrada en el perfil y lista para usar en cobros automáticos.

Estados posibles del link

Los estados vinculated, cancelled, expired y error son terminales: una vez alcanzados, el link no puede transicionar a ningún otro estado.

Escenarios del GET

Errores posibles

Envía una solicitud a /v1/payment-method-enrollments/{id}DELETE incluyendo el id del link en el path para desactivarlo antes de que el comprador lo use. Solo pueden cancelarse links en estado created.

curl -X DELETE \
  'https://api.mercadopago.com/v1/payment-method-enrollments/bea0ffb8-6c94-40a3-bc31-c2e7a0d46ed7' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Una respuesta 204 No Content confirma que el link fue cancelado. Verifica el resultado con un GET: state pasará a cancelled.

Errores posibles

Usa las credenciales de pruebaDisponibles en el Panel del Desarrollador, en Tus integraciones > Credenciales de prueba. de tu cuenta de Mercado Pago para validar el flujo sin procesar transacciones reales.

Requisitos previos

• Obtén tu APP_ACCESS_TOKEN de test en Tus integraciones > Credenciales de prueba.
• Obtén tarjetas de prueba para simular escenarios de aprobación y rechazo en nuestra documentación de tarjetas de prueba.
• Crea un cliente de prueba con un email en formato xxxx@testuser.com.
• Crea un Perfil de Pago a partir del customer_id de ese cliente de prueba.

Escenarios — POST /v1/payment-method-enrollments

Escenarios — GET /v1/payment-method-enrollments/{id}

Escenarios — DELETE /v1/payment-method-enrollments/{id}