Configurar la vinculación
La vinculación es una autorización otorgada por el comprador que permite al vendedor debitar pagos directamente de su billetera de Mercado Pago, sin necesidad de iniciar sesión en cada transacción. Es la primera etapa de la integración con Wallet Connect y es obligatoria antes de procesar cualquier pago.
El flujo está compuesto por tres etapas: crear la vinculación, obtener la aprobación del comprador y generar el token de pago. Al completarlo, tendrás el payer_token, credencial que autoriza los cobros descritos en la sección Procesar pagos.
La creación de la vinculación genera el enlace de autorización que debe presentarse al comprador para que otorgue al vendedor el acceso a su billetera de Mercado Pago. Existen dos flujos disponibles: Estándar, en el que el comprador completa la autorización en el navegador, y Sniffing, que intenta abrir la autorización directamente en la aplicación de Mercado Pago en dispositivos móviles. Compara las opciones a continuación y elige la que mejor se adecue a tu integración.
En el flujo estándar, el comprador autoriza el acceso a su billetera de Mercado Pago en el navegador y puede necesitar iniciar sesión manualmente.
Para crear una vinculación sin redirigir al comprador a la aplicación de Mercado Pago, envía un POST al endpoint /v2/wallet_connect/agreementsAPI, incluyendo tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En Wallet Connect, el Access Token y la Public Key son entregados por el equipo responsable de crear tu aplicación, tanto los de prueba como los de producción. También es posible visualizarlos en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y los parámetros indicados a continuación.
curlcurl -X POST \ 'https://api.mercadopago.com/v2/wallet_connect/agreements' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "return_uri": "https://www.mercadopago.com/", "external_flow_id": "{{EXTERNAL_FLOW_ID}}", "external_user": { "id": "usertest", "description": "Test account" }, "agreement_data": { "validation_amount": 3.14, "description": "Test agreement" } }'
Consulta en la tabla a continuación las descripciones de los parámetros que son obligatorios en la solicitud y aquellos que, aunque son opcionales, tienen alguna particularidad importante que debe destacarse.
| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Se refiere a tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En Wallet Connect, el Access Token y la Public Key son entregados por el equipo responsable de crear tu aplicación, tanto los de prueba como los de producción. También es posible visualizarlos en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`.. | Obligatorio |
return_uri | Body. String | URI a la que será redirigido el comprador al completar el flujo de vinculación. Es en esa dirección donde recibirás el resultado de la autorización como query parameters. El límite máximo es de 2048 caracteres y el valor enviado debe corresponder a una URI previamente registrada para la aplicación. | Obligatorio |
external_flow_id | Body. String | Identificador interno del vendedor para el estado actual del flujo. Utilízalo para correlacionar el retorno de la vinculación con la sesión de compra en tu sistema. El límite máximo es de 64 caracteres. | Obligatorio |
external_user.id | Body. String | Identificador único del comprador en el sistema del vendedor. El límite máximo es de 256 caracteres y el valor no debe contener datos sensibles. | Obligatorio |
external_user.description | Body. String | Identificación del comprador en el sistema del vendedor, como su nombre. El límite máximo es de 256 caracteres. | Opcional |
agreement_data.validation_amount | Body. Number | Monto de referencia de la vinculación. Si el saldo en cuenta del comprador es insuficiente para cubrir este monto, se solicitará una tarjeta como medio de pago secundario durante la autorización. Recomendamos enviar un valor cercano al ticket promedio de tus cobros. | Opcional |
agreement_data.description | Body. String | Descripción de las acciones que el comprador está a punto de autorizar, exhibida durante el flujo de aprobación. El límite máximo es de 256 caracteres. | Opcional |
Si la solicitud es exitosa, la respuesta devolverá el estado 201 con el identificador de la vinculación creada y la URI de autorización que debe presentarse al comprador.
json{ "agreement_id": "22abcd1235ed497f945f755fcaba3c6c", "agreement_uri": "{{wc_agreement_uri_example}}" }
Entre los parámetros devueltos, tenemos los indicados en la tabla a continuación.
| Parámetro | Tipo | Descripción |
agreement_id | String | Identificador único de la vinculación creada. Almacénalo, ya que es necesario para generar el token de pago y para consultar o cancelar la vinculación. |
agreement_uri | String | URI a la que debe redirigirse el comprador para autorizar el acceso a su billetera. Consulta la etapa Obtener aprobación del comprador para saber cómo utilizarla. |
Después de crear la vinculación, redirige al comprador a la agreement_uri devuelta en la respuesta. En esa URL, el comprador otorga la autorización para que el vendedor utilice su billetera de Mercado Pago como medio de pago.
Al finalizar el flujo, Mercado Pago redirige al comprador a la return_uri informada en la creación, agregando el resultado de la operación como query parameters.
- Si la autorización es otorgada, la
return_uriserá llamada en el formato a continuación.
plain`{return_uri}?agreement_id={agreement_id}&code={code}&flow=agreement&external_flow_id={external_flow_id}&code_type=validation_code`
- En caso de rechazo o cancelación por parte del comprador, la
return_uriserá llamada en el formato a continuación, sin el parámetrocodey con el parámetroerror.
plain`{return_uri}?agreement_id={agreement_id}&flow=agreement&external_flow_id={external_flow_id}&error={error}`
Consulta en la tabla a continuación las descripciones de los parámetros devueltos.
| Parámetro | Tipo | Descripción |
agreement_id | String | Identificador único de la vinculación autorizada. |
code | String | Código de autorización utilizado para generar el token de pago. Es un código alfanumérico de 32 caracteres en minúsculas, con una ventana de validez limitada. |
flow | String | Identifica el flujo que originó la redirección. Devuelve siempre el valor fijo agreement. |
external_flow_id | String | Identificador interno del vendedor, devuelto según fue enviado en la creación de la vinculación. |
code_type | String | Indica el tipo de código devuelto. Devuelve siempre el valor fijo validation_code. |
error | String | Motivo por el cual la vinculación no fue concluida. Devuelve el valor fijo access_denied, que indica que el comprador rechazó o canceló la autorización. |
El token de pago (payer_token) es la credencial que representa la autorización del comprador y permite al vendedor ejecutar cobros desde su billetera. Es la última etapa del flujo de vinculación.
El parámetro code necesario para generarlo puede obtenerse de dos formas: como query parameter en la return_uri (recomendado) o a partir del webhook de confirmación de la vinculación.
Para generar el token, envía un POST al endpoint /v2/wallet_connect/agreements/{agreement_id}/payer_tokenAPI, incluyendo tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En Wallet Connect, el Access Token y la Public Key son entregados por el equipo responsable de crear tu aplicación, tanto los de prueba como los de producción. También es posible visualizarlos en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`., el agreement_id de la vinculación obtenido en su creación y el código de autorización.
curlcurl -X POST \ 'https://api.mercadopago.com/v2/wallet_connect/agreements/{{AGREEMENT_ID}}/payer_token' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "code": "{{AUTHORIZATION_CODE}}" }'
Consulta en la tabla a continuación las descripciones de los parámetros que deben enviarse en esta solicitud.
| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Se refiere a tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En Wallet Connect, el Access Token y la Public Key son entregados por el equipo responsable de crear tu aplicación, tanto los de prueba como los de producción. También es posible visualizarlos en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`.. | Obligatorio |
agreement_id | Path. String | Identificador único de la vinculación, obtenido en la respuesta a su creación. | Obligatorio |
code | Body. String | Código de autorización generado durante el flujo de vinculación. Debe ser una string alfanumérica de 32 caracteres en minúsculas y puede utilizarse solo una vez, dentro de la ventana de validez. | Obligatorio |
Si la solicitud es exitosa, la respuesta devolverá el estado 201 con el token de pago asociado a la vinculación.
json{ "payer_token": "abcdef1e23f4567d8e9123eb6591ff68df74c57930551ed980239f4538a7e530" }
| Parámetro | Tipo | Descripción |
payer_token | String | Token que representa la autorización del comprador para que el vendedor procese pagos desde su billetera. Debe enviarse en el campo transactions.payments.payment_method.token en cada cobro. |
payer_token de forma segura, ya que se utilizará en todos los pagos de este comprador mientras la vinculación esté activa. Un mismo code no puede reutilizarse para generar un nuevo token: si la vinculación es cancelada, será necesario repetir todo el flujo de autorización.La cancelación revoca la autorización otorgada por el comprador e invalida el payer_token asociado, impidiendo nuevos cobros desde su billetera.
Para cancelar una vinculación, envía un DELETE al endpoint /v2/wallet_connect/agreements/{agreement_id}API sin enviar el body en la solicitud. Asegúrate de incluir tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En Wallet Connect, el Access Token y la Public Key son entregados por el equipo responsable de crear tu aplicación, tanto los de prueba como los de producción. También es posible visualizarlos en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`. y el agreement_id de la vinculación que deseas cancelar.
curlcurl -X DELETE \ 'https://api.mercadopago.com/v2/wallet_connect/agreements/{{AGREEMENT_ID}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Se refiere a tu Access Token de pruebaClave privada utilizada en el backend para autenticar las solicitudes. En Wallet Connect, el Access Token y la Public Key son entregados por el equipo responsable de crear tu aplicación, tanto los de prueba como los de producción. También es posible visualizarlos en Tus integraciones > Datos de integración > Pruebas > Credenciales de prueba. El Access Token de prueba comienza con el prefijo `APP_USR`.. | Obligatorio |
agreement_id | Path. String | Identificador único de la vinculación que se desea cancelar. | Obligatorio |
Si la solicitud es exitosa, la respuesta devolverá el estado 200 sin cuerpo de respuesta, indicando que la vinculación fue cancelada y que el payer_token asociado dejó de ser válido.