Hace unos días tuve la oportunidad de certificarme como Certified Developer para la integración del checkout pro, muy buen producto de mercadopago.
En este post quiero dejarles el paso a paso para probar el funcionamiento de la API ya que, a pesar de la documentación y los ejemplos, hay cosas que no quedan del todo claras.
Para realizar este proyecto no vamos a utilizar ninguna librería externa o tecnología en particular, sino que vamos a hacer las consultas HTTP utilizando postman, y luego podremos exportarlas en formato de código.
Para quienes no conocen postman es una herramienta que permite crear solicitudes HTTP con todos los datos necesarios, utilizar diferentes entornos, y que luego se pueden exportar a una variedad de códigos para usar en los desarrollos.
A continuación les dejo un link a la colección de requests pública que cree para este ejercicio, y explico cómo usarla para que todo funcione correctamente.
Postman
Con el enlace anterior podemos bajar el json de una colección de Postman, vamos a utilizar dos secciones para hacer las pruebas.
Environments
Variables de entorno. Utilizaremos 3 tipos:
- Globals: variables que están siempre disponibles, como por ejemplo la url base que es 'https://api.mercadopago.com'
- DEV_ENVIRONMENT: variables para realizar pruebas con dinero ficticio.
- PROD_ENVIRONMENT: variables para realizar operaciones en producción con dinero real.
Es mandatorio que seleccionemos el entorno correspondiente en cada consulta, de lo contrario las solicitudes no van a funcionar.
Para utilizar estas variables, podemos escribirlas donde queramos con la sintaxis {{variable}}
Collections
Colección de solicitudes GET, POST, que vamos a necesitar para ir probando la integración. Estas ya están preparadas con las variables de entorno, por lo que luego de configurarlas ya se las puede ejecutar.
Pueden observar en cada una de las peticiones los valores de url, headers, body.
Exportar código
La parte más útil de esto, es que cambiando las variables de entorno y seleccionando el entorno adecuado, puedan hacer sus propias pruebas y también exportar las consultas al lenguaje con el que trabajen.
Para esto, deben presionar el botón </> que se encuentra en la barra lateral derecha, seleccionar el lenguaje y copiar el código.
En este ejemplo se puede ver el código generado para utilizar fetch en javascript para el navegador, lo cual no podríamos hacer porque este código debe ser ejecutado del lado del servidor, pero yo utilizo node.js y la librería node-fetch con lo cual el código es muy parecido.
Documentación oficial
A lo largo del tutorial voy a ir dejando los links a la documentación oficial.
En la referencia a la API, los ejemplos de consulta estan escritos en cURL, les dejo una web app que parsea cURL a fetch, para poder copiar mejor los datos si quieren agregar consultas a postman luego.
Web app para parsear peticiones cURL a feth
Comencemos
En este proceso vamos a utilizar 3 cuentas diferentes de mercadopago, por lo que debemos tener en claro cual estamos usando en cada momento, voy a indicarlo pero hay que prestar especial atención.
Las 3 cuentas son las siguiente:
- Cuenta REAL: es nuestra propia cuenta de MP, donde vamos a recibir los pagos una vez que pongamos la aplicación en producción.
- Cuenta VENDEDOR, es una cuenta de prueba, de la cual vamos a tomar las credenciales para testear la API.
- Cuenta COMPRADOR, es una cuenta de prueba, con la que vamos a estar logueados para efectuar la compra a la cuenta vendedor.
Para utilizar los diferentes usuarios podemos tener varios navegadores como chrome, edge, firefox, o utilizar los modos incógnitos, de manera de no tener que entrar y salir de las cuentas constantemente.
1 Crear usuarios de prueba
Lo primero que tenemos que hacer es crear el usuario VENDEDOR y COMPRADOR.
Para esto, debemos acceder a las credenciales de nuestra cuenta REAL.
En todas las cuentas vamos a encontrar que tenemos dos tipos de credenciales, de PRUEBA y de PRODUCCIÓN.
Vamos a ingresar a las credenciales de PRUEBA de la cuenta REAL, y tomar el valor de Access Token.
Para esto, debemos estar logueados con nuestro usuario real a la hora de ir al siguiente enlace:
En postman, asignamos este string a la variable de entorno devAccessToken en la sección Globals
Con esto ya podemos crear los usuarios de prueba ejecutando la solicitud "Generar usuarios de prueba" en la lista de la colección, vamos a obtener un resultado como este:
Debemos ejecutar la consulta dos veces para obtener el usuario VENDEDOR y COMPRADOR.
Anotamos bien los datos en algún lugar ya que no lo podremos consultar luego.
Mercadopago permite crear hasta 10 usuarios de prueba, y estos caducan después de 60 días de inactividad.
Cualquiera de los 2 usuarios creados puede ser el vendedor o comprador, lo importante es que ambas partes sean de prueba.
2 Obtener credenciales del usuario VENDEDOR
Para continuar vamos a tomar las credenciales de PRODUCCIÓN del usuario VENDEDOR.
Para esto, debemos loguearnos con el usuario de prueba que hayamos elegido como vendedor, podemos hacerlo en otro explorador, o en una pestaña de incógnito (para no desloguearnos con nuestro usuario real)
Siguiendo el link anterior, podrán acceder a las credenciales de producción, tomamos el valor de Access Token y lo asignamos a la variable de entorno accessToken en DEV_ENVIRONMENT
Ya podemos probar la API ejecutando la consulta "Tipos de documento" del listado en postman, seleccionando primero como entorno DEV_ENVIRONMENT y ver el resultado.
3 Crear una preferencia de pago
Una preferencia de pago es un documento en formato JSON que representa todas las partes de una operación, como ser datos del comprador, vendedor, ítems, cantidades, precios, urls de estado, etc.
Si bien se puede crear una preferencia con unos pocos campos obligatorios, es mejor proveer la mayor información posible en este paso, ya que mercadopago tiene un motor antifraude, el cual realiza comprobaciones internas cruzando algunos de los datos que le brindamos.
Veamos un ejemplo de preferencia y analicemos los campos:
{
"items": [
{
"id": "1234",
"title": "Smartphone",
"currency_id": "ARS",
"picture_url": "pics.com/sf.jpg",
"description": "Dispositivo móvil",
"category_id": "art",
"quantity": 1,
"unit_price": 30000
}
],
"payer": {
"name": "Ricardo",
"surname": "Alvarez",
"email": "ralvarez@email.com",
"phone": {
"area_code": "11",
"number": "22223333"
},
"identification": {
"type": "DNI",
"number": "12345678"
},
"address": {
"street_name": "Calle",
"street_number": 123,
"zip_code": "1111"
}
},
"back_urls": {
"success": "myapp.com/success",
"failure": "myapp.com/failure",
"pending": "myapp.com/pending"
},
"auto_return": "approved",
"payment_methods": {
"excluded_payment_methods": [
{
"id": "amex"
}
],
"excluded_payment_types": [
{
"id": "atm"
}
],
"installments": 6
},
"notification_url": "myapp.com/webhook",
"statement_descriptor": "Tienda eCommerce",
"external_reference": "mlplesoj9b"
}
Veamos las partes:
- items: array de productos en nuestro carro de compras.
- payer: información del pagador, si tienen registrado al usuario en su sitio seguramente tengan ya algunos datos para completar.
- back_urls: muy importante, urls a las que será redirigido tu usuario luego de haber completado una operación (sin cerrar el checkout) cualquiera sea el resultado, "success" si el pago fue aprobado, "failure" si rechazado, y "pending" si se utiliza medios de pagos físicos u otro que requiera una comprobación luego.
-
auto_return: si se deja en approved, el usuario es redirigido automáticamente al sitio de success que figura en las
back_urlsluego de 5 segundos (sin necesidad de que presione ningún botón). También puede tener el valor all, para que cualquiera sea el resultado se redirija automáticamente. - payment_methods: configuración de métodos de pago, se pueden excluir tipos y medios, y configurar la cantidad de cuotas para las tarjetas de crédito (installments). Para ver la información sobre los métodos de pago se puede ejecutar la consulta "Metodos de pago" en la colección de postman.
- notification_url (webhook): muy importante, url a la que mercadopago hará una POST request informándonos de la creación o actualización de un pago, es necesario que tomemos estos datos, más abajo veremos cómo.
- statement_descriptor: texto que aparecerá en el resumen de tarjeta de tu comprador.
- external_reference: string interno de tu aplicación para corroborar la operación con información de tu base de datos.
Una vez completado nuestro JSON para crear la preferencia, podemos ejecutar la consulta "Crear preferencia" de postman (el ejemplo anterior se encuentra en el body de dicha solicitud)
Obtendremos como resultado un JSON bastante extenso, del cual vamos a utilizar la propiedad init_point, que es la url a la cual deberemos dirigir a nuestro usuario.
Se ve como este ejemplo:
"init_point": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=716087195-bcec52a0-1cae-4650-aa12-ae316f2f2674"
4 Iniciar flujo de pago
Una vez que hayamos obtenido nuestra url para comenzar el flujo de pago, deberemos redirigir a nuestro usuario a esta.
Para probar el flujo, debemos iniciar sesión con los datos de nuestro usuario de prueba COMPRADOR, y acceder al link.
Si por error accedemos al link con nuestro usuario REAL, o VENDEDOR, podemos obtener estos errores respectivamente:
Accediendo al link con nuestro usuario COMPRADOR entonces, veremos la siguiente pantalla:
Si elegimos pagar con efectivo, el resultado de la operación siempre será "pending".
Para probar los resultados "success" y "failure", podemos usar los datos de unas tarjetas de prueba que MP dispone para tal fin. Estas son las tarjetas:
Como pueden observar dependiendo del "nombre" que completen, será el resultado y la razón de la operación.
En los campos de código de seguridad y DNI podemos poner cualquier número.
Por ejemplo, usando la Visa 4509 9535 6623 3704 y el nombre APRO, obtenemos como resultado un pago aprobado, y la redirección automática en 5 segundos:
O si ponemos por ejemplo FUND, nos rechaza por falta de fondos, y no redirige a menos que hagamos clic en "volver al sitio" o hayamos configurado auto_return: all:
Si vamos a la página principal de los usuarios VENDEDOR y COMPRADOR veremos sus respectivas actividades:
A continuación veremos como utilizar las back_urls
5 Hacer uso de las back_urls
Si nuestro usuario finaliza el flujo del checkout pro, es decir, si no cierra la página o pestaña antes de que termine, dependiendo del valor que hayamos pasado en la propiedad auto_return de la preferencia, sera redirigido automaticamente a la back_url que corresponda en base al resultado de la operación, o, al hacer clic en el botón "Volver al sitio".
Cualquiera sea el caso debemos redirigir al usuario a la dirección que corresponda y capturar los parámetros que mercadopago nos pasa en el query string de la url.
Tiene este formato:
https://myapp.com/?merchant_order_id=2334717960&merchant_account_id=null&processing_mode=aggregator&status=approved&collection_status=approved&payment_id=13710864554&payment_type=credit_card&site_id=MLA&external_reference=mlplesoj9b&collection_id=13710864554&preference_id=716087195-e9128a3b-f93e-40eb-8326-048cebbb1b1f
Podemos usar la herramienta query string splitter para parsear los parámetros de esta url, obteniendo los siguientes datos:
merchant_order_id: 2334717960
merchant_account_id: null
processing_mode: aggregator
status: approved
collection_status: approved
payment_id: 13710864554
payment_type: credit_card
site_id: MLA
external_reference: mlplesoj9b
collection_id: 13710864554
preference_id: 716087195-e9128a3b-f93e-40eb-8326-048cebbb1b1f
Con el valor de payment_id podremos consultar el estado del pago mediante la API, completando el valor paymentId en "DEV_ENVIRONMENT" y ejecutando la request "Consultar pago" de la colección de postman.
Obtendremos un JSON con toda la información del pago.
Los campos importantes a mirar acá son status y status_detail, si tienen los valores "approved" y "accredited" respectivamente, tenemos la seguridad de que el dinero ya se encuentra en nuestra cuenta.
{
"status": "approved",
"status_detail": "accredited"
}
En caso de que un pago pendiente veremos:
{
"status": "pending",
"status_detail": "pending_waiting_payment"
}
En caso de un pago rechazado por fondos por ejemplo veremos:
{
"status": "rejected",
"status_detail": "cc_rejected_insufficient_amount"
}
Ahora vamos a ver cómo obtener información de las operaciones sin depender de que el usuario vuelva a nuestro sitio o tener que consultar el payment desde los parámetros de las back urls.
6 Crear endpoint para el webhook o url de notificación
Cuando un pago se crea o actualiza, mercadopago hace un POST request a la dirección que hayamos configurado en la propiedad notification_url de nuestra preferencia.
Para informar a mercadopago que hemos recibido correctamente la información, debemos responderle con un STATUS 200 o 201 desde nuestro servidor.
En caso de que aún no hayamos creado el código para ejecutar del lado del servidor, podemos usar una herramienta muy útil para capturar estas solicitudes.
Se trata de Hookbin, esta web app nos permite crear una url a la que podemos apuntar, y se encarga de capturar todas las peticiones.
Ingresamos y presionamos "Create new endpoint"
Una vez generada nuestra nueva url, vamos a usarla para recibir el webhook.
Cambiemos la variable de entorno webHook en "DEV_ENVIRONMENT" por la url de hookin, y ejecutemos la request "Crear preferencia", no olvidemos de chequear que este seleccionado el entorno correcto.
Con esto obtendremos una nueva preferencia de pago, que tendrá como url de notificación la dirección de hookbin que le pasamos, y obtendremos el nuevo init_point para hacer nuestra prueba.
Accedemos al init_point con nuestro usuario COMPRADOR, y realizamos el proceso.
En este caso voy a mostrar una operación aprobada o "success".
Para ver la información recibida, nos vamos a la pestaña de hookbin y le damos actualizar o F5.
Podemos ver que hay un par de solicitudes recibidas, nos interesa la que tiene la propiedad "action": "payment.created", lo que la identifica como la creación de un pago, veremos que en el body trae algunos valores:
De estos datos es importante que tomemos el valor de id, pero dentro del objeto data
{
"data":{
"id": 13711992133
}
}
Con este id podremos consultar el estado del pago cambiando la variable de entorno paymentId y ejecutando "Consultar pago" como habíamos hecho anteriormente.
Si se trata de un pago en efectivo, podemos guardar este id en nuestra base de datos para consultarlo luego.
Si al consultar un pago nos encontramos con que esta pendiente, y el usuario realiza el pago luego (por ejemplo en pagofacil o rapipago), recibiremos otro hook con un action distinto "action": "payment.updated", lo que significa que la información del pago se actualizo, y podemos consultar nuevamente para ver si se aprobó o cual es su estado.
Recuerden que en la creación de la preferencia siempre podemos pasar un valor en external_reference para corroborar la operación con nuestra base de datos.
7 Pasar a producción
Una vez realizadas todas estas pruebas con éxito podemos efectuar los pasos para pasar a producción.
Lo primero que debemos hacer es loguearnos con nuestro usuario REAL, y tomar el Acces Token de las credenciales de PRODUCCIÓN.
Mercadopago puede pedir algunas cosas adicionales al intentar activar las credenciales de producción, como verificación de DNI por ejemplo, solo seguir los pasos.
Colocamos este valor en la variable de entorno accessToken, pero esta vez en el entorno "PROD_ENVIRONMENT"
Una vez tengamos la dirección que finalmente vamos a usar para obtener los hooks deberemos asignarla a la variable de entorno webHook del "PROD_ENVIRONMENT".
Si queremos que todas nuestras preferencias tengan la misma url de notificación o webhook, podemos configurarlos y excluir la propiedad notificaion_url de la preferencia de pago.
Eso es todo, ahora podemos crear una referencia de pago utilizando el entorno "PROD_ENVIRONMENT" con un monto bajo, por ejemplo ARS 50, y pasarle el init_point a un compañero para que efectúe la compra, luego podemos hacerle la devolución desde la app de MP.
Conclusión
Hemos visto cómo probar la API para recibir pagos, sin embargo hay muchas otas funcionalidades que mercadopago ofrece y están todas asentadas en la documentación de la API, es cuestion de agregarlas a postman y probar.
Solo queda que pasen las consultas al código que usen para el backend, y subir la app a plataformas como heroku, vercel o su propio servidor.
Espero les sea de utilidad.
Saludos.
Recursos
Lista reproducción de mercadopago | Youtube
Video demostrativo
Github repo
Estoy acomodando algunos archivos cuando termine subo un repositorio que use para probar con vue y node.js
Top comments (10)
hola! quería compartirles algo que me sucedió al momento de consultar el estado del pago con el payment_id. Obtenía un error 2000 "Payment not found". Luego de probar varias alternativas, lo solucioné agregando el access token de prueba ( no el de producción) en la petición GET . Aclaro que esto lo hice con cuentas de prueba pero al momento de crear la preferencia agregué el access token de producción de la cuenta de prueba.
Buenas, una consulta, hay alguna forma de borrar una preferencia ya creada?.
Pregunto por el siguiente caso: Un cliente tiene objetos en un carrito, llega al checkout de mercadopago y se guarda el link generado, luego vuelve atras, agrega mas cosas al carrito y pega en el navegador el link anterior y sigue funcionando.
Hay alguna forma de hacer que ese init point ya no funcione?
Hola, desde hace unos días los links ya no abren la App de MP sino que abren la página en el navegador. Alguien tiene alguna data al respecto ?
Hola lybce, esta es una consulta que hice en un meet con gente de MP y me comentaron que estan trabajando para que al abrir un link desde el navegador, lance la applicación en andoird o iOS, pero que por el momento ese es el comportamiento.
Saludos
Gracias Jorge.
Lo raro es que hace un par de semanas los links enviados por whatsapp lanzaban la App (al menos en Android) si tenias la App instalada.
Me encanta como , teniendo un canal para comunicar novedades, los de MP/ML no lo hacen y despues deben contestar miles de consultas.
Pais de locos
Abrazo
Hola, antes que nada, excelente todo lo descrito y muy completo! No terminé de entender algo. Cómo hago para en la preferencia pasarle los datos de quien compró si ya está creada? Porque payer es quien paga, pero si recién estoy o están creando la preferencia, no hay nadie pagando... O es a quien debo pagarle? Leyendo la documentación termino con mas dudas incluso jaja
Hola, entonces con los webHooks en el frontend no tengo que configurar nada? Entendí que si tengo una back_url: mi-sitio.com/success entonces en el front tengo que crear la ruta /success y enviarle ahí la notificación no? Muy bueno el artículo! De lo más completo que encontré en la web y aún es válido jaja
hola @jarraga muy bueno el articulo, completo y util.
una consulta, no tenes por esas casualidades un link
a una collection de postman con todos los endpoints de la API?
hola, una consulta, puede implementar una venta pero en el dashboard de los usuarios no me figuran actividades, sabrás porque?
hola como podría hacer que me registre el pago sin la necesidad que me redirija a la web de mercado pago. con mi propia UI de pasarela de pago