Mercadopago | Checkout PRO (postman, no library)
Tags: mercadopago, postman, api, spanish
Published: 2021-02-17 15:01:02

Hace unos días tuve la oportunidad de certificarme como Certified Developer para la integración del checkout pro, muy buen producto de mercadopago.

![certificado](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ys7gm3f7q2u9krotmti1.png)

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

[Postman collection](https://drive.google.com/file/d/1GxUZGiydqHzEFGemY0lYn49mSJpskoZe/view?usp=sharing)

Con el enlace anterior podemos bajar el json de una colección de Postman, vamos a utilizar dos secciones para hacer las pruebas.

![entorno](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1f0ei9t9m6wj29ydmkbn.png)

#### 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.

![postman](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/or4fjkd7lxccm3jynbtf.png)

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.

[Integración checkout pro](https://www.mercadopago.com.ar/developers/es/guides/online-payments/checkout-pro/integration)

[Referencia a la API](https://www.mercadopago.com.ar/developers/en/reference)

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](https://kigiri.github.io/fetch) 

---

### 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:

[Credenciales usuario REAL](https://www.mercadopago.com.ar/developers/panel/credentials)

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:

![usuario prueba](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1xtxusn0i8kvvotrvfbl.png)

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)

[Credenciales usuario VENDEDOR](https://www.mercadopago.com.ar/developers/panel/credentials)

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**

![credenciales vendedor](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/byv8pml7mlpntc5mncdi.png)

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.

![seleccionar entorno](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e8qd6449jzbttar86llr.png)

---

### 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.

[Preferencia completa](https://www.mercadopago.com.ar/developers/en/reference/preferences/_checkout_preferences/post)

Veamos un ejemplo de preferencia y analicemos los campos:

```json
{
    "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_urls` luego 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:

![errores](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6g83rzqhytirri260la3.png)

Accediendo al link con nuestro usuario **COMPRADOR** entonces, veremos la siguiente pantalla:

![checkout](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ogtzdx9ecs74ywp00wrk.png)

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:

[Tarjetas de prueba](https://www.mercadopago.com.ar/developers/es/guides/online-payments/checkout-pro/test-integration#bookmark_tarjetas_de_prueba)

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:

![aprobado](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zn5yw8j0ioqi97o33c88.png)

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`:

![sin fondos](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/443naq5kzbn7z7o9e33u.png)

Si vamos a la página principal de los usuarios VENDEDOR y COMPRADOR veremos sus respectivas actividades:

![actividad](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/apo497wfegj5d42jzwzk.png)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1gbwv92y16ngof66qov9.png) 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](https://www.freeformatter.com/url-parser-query-string-splitter.html) 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.

```json
{
    "status": "approved",
    "status_detail": "accredited"
}
```

En caso de que un pago pendiente veremos:

```json
{
    "status": "pending",
    "status_detail": "pending_waiting_payment"
}
```

En caso de un pago rechazado por fondos por ejemplo veremos:

```json
{
    "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"

[Hookbin](https://hookbin.com/)

![hookin](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yqliwrsitapz3j4i1kks.png)

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:

![hook](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/74cebdo7fc09p4cz81f8.png)

De estos datos es importante que tomemos el valor de **id**, pero dentro del objeto **data**
 
```json
{
   "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.

[Documentación webhooks](https://www.mercadopago.com.ar/developers/es/guides/notifications/webhooks)

---

### 7 Pasar a producción

![produccion](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rkq6clmn3t8dg4o0lh04.png)

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"

[Credenciales producción](https://www.mercadopago.com.ar/developers/panel/credentials)

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.

[Configurar webhook](https://www.mercadopago.com/mla/account/webhooks)

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](https://www.youtube.com/playlist?list=PLCazXKuqZp3iixwB2AGaCMhDTCeBtZ3lb)

[Mejora tus pagos](https://www.mercadopago.com.ar/developers/es/guides/manage-account/account/payment-rejections)

### Video demostrativo
{% youtube mlL6RjlUpVM %}

### Github repo
Estoy acomodando algunos archivos cuando termine subo un repositorio que use para probar con vue y node.js