Links de vinculação

Envie uma requisição para /v1/payment-method-enrollmentsPOST utilizando o APP_ACCESS_TOKENAccess Token de produção da aplicação do integrador. Disponível em Suas integrações > Credenciais de produção. de produção para gerar o link que você compartilhará com o 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"
  }'

Se a requisição for bem-sucedida, você receberá uma resposta 201 Created com o seguinte 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"
}

Salve o valor de id para consultar o estado do link posteriormente. O valor de enrollment_link é a URL que você deve compartilhar com o comprador.

Erros possíveis

Compartilhe o valor de enrollment_link com o comprador pelo canal que preferir: WhatsApp, e-mail, SMS ou outro. O comprador abre a URL no navegador, preenche o formulário do Mercado Pago com os dados do cartão e o cartão fica vinculado ao perfil. O vendedor não participa desta etapa nem acessa os dados do cartão.

Em vez de consultar o estado do link por chamadas à API, você pode receber notificações em tempo real. Quando o comprador vincula o cartão com sucesso, o Automatic Payments envia um webhook com a mudança de estado do perfil para READY.

Para configurar as notificações:

1. Acesse Suas integrações no Painel do Desenvolvedor e selecione sua aplicação.
2. Acesse Webhooks e registre a URL HTTPS do seu endpoint receptor. O endpoint deve responder com 200 em menos de 22 segundos.
3. Ative o evento Perfil de Pagamento (payment_profile).
4. Copie a chave secreta gerada para validar a assinatura x-signature de cada notificação recebida.

Quando o comprador vincula o cartão com sucesso, você receberá um webhook com o seguinte 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
    }]
  }
}

O campo version é um contador incremental por perfil. Processe sempre a notificação com maior version e descarte as anteriores caso cheguem fora de ordem.

Para saber mais sobre o formato das notificações e como validar a assinatura, consulte a documentação de Webhooks.

Envie uma requisição para /v1/payment-method-enrollments/{id}GET incluindo o id do link no path para verificar se o comprador concluiu a vinculação.

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

Se o comprador concluiu a vinculação, você receberá uma resposta 200 OK com o seguinte corpo:

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

Quando state é vinculated, o cartão já está registrado no perfil e pronto para uso em cobranças automáticas.

Estados possíveis do link

Os estados vinculated, cancelled, expired e error são terminais: uma vez atingidos, o link não pode transicionar para nenhum outro estado.

Cenários do GET

Erros possíveis

Envie uma requisição para /v1/payment-method-enrollments/{id}DELETE incluindo o id do link no path para desativá-lo antes de o comprador utilizá-lo. Somente links no estado created podem ser cancelados.

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

Uma resposta 204 No Content confirma que o link foi cancelado. Verifique o resultado com um GET: state passará para cancelled.

Erros possíveis

Use as credenciais de testeDisponíveis no Painel do Desenvolvedor, em Suas integrações > Credenciais de teste. da sua conta do Mercado Pago para validar o fluxo sem processar transações reais.

Pré-requisitos

• Obtenha seu APP_ACCESS_TOKEN de teste em Suas integrações > Credenciais de teste.
• Obtenha cartões de teste para simular cenários de aprovação e rejeição na documentação de cartões de teste.
• Crie um cliente de teste com um e-mail no formato xxxx@testuser.com.
• Crie um Perfil de Pagamento a partir do customer_id desse cliente de teste.

Cenários — POST /v1/payment-method-enrollments

Cenários — GET /v1/payment-method-enrollments/{id}

Cenários — DELETE /v1/payment-method-enrollments/{id}