Guía de integración de Magento (Adobe Commerce) 🅱️

10 octubre 2023

Acepta pagos para tu e-commerce con Magento (Adobe Commerce)

Magento es una plataforma de comercio electrónico que fue adquirida por Adobe en 2018. Es por esto que existen dos versiones de la plataforma:

• Magento Open Source
• Adobe Commerce

Kushki cuenta con un plugin para ambas versiones, el cual te permitirá recibir pagos seguros con tarjeta de crédito y débito, efectivo y transferencia. El detalle de la instalación y administración del plugin lo encontrarás a continuación.

Requisitos

• Magento 2.4.x para una óptima compatibilidad.

Instalación y configuración

El código fuente del plugin puede ser descargado aquí.

1. Instalación

Requisitos:

• Debes tener descargado el módulo de pagos de Kushki en formato .zip.
• Debes tener Magento instalado y configurado con el tipo de moneda que usarás.
• Debes tener acceso a la sección de administración de Magento.

Sigue estas instrucciones para instalar el plugin de Kushki en tu tienda Magento:

1.1. En el directorio de instalación de Adobe Commerce, ve a app > code (en caso de no existir, debes crear la carpeta code).

1.2. Extrae el contenido del archivo .zip. La ruta final debería ser app > code > Kushki > Payment.

1.3. Actualizar Magento. Desde una terminal SSH, ejecuta el siguiente comando en el directorio raíz de Magento 2: php bin/magento setup:upgrade.

1.4. Compila la configuración corriendo el siguiente comando: php bin/magento setup:di:compile.

1.5. Despliega el contenido estático. Ejecuta el siguiente comando en el directorio raíz de Magento 2: php bin/magento setup:static-content:deploy.

1.6. Finalmente, remueve el caché ejecutando el comando: php bin/magento cache:flush.

2. Configuración

Una vez instalado el plugin, podemos proceder a configurarlo en tu tienda de Magento.

2.1. Obtén tus credenciales para Magento desde la Consola de Kushki

Para obtener tu ID de comercio, credencial pública y credencial privada, las cuales usarás durante la configuración del plugin de Kushki en Magento, sigue estos pasos:

2.1.1. Ingresa a tu Consola
2.1.2. Ve a Configuración y navega hasta la sección Integraciones
2.1.3. Haz clic en Plugins
2.1.4. Selecciona Adobe Commerce
Se abrirá un Formulario de integración
2.1.5. Ingresa la URL de tu tienda de Adobe Commerce y haz clic en Guardar
Verás un mensaje de confirmación
2.1.6. Haz clic en Ir a credenciales
Verás la lista de Credenciales activas en tu comercio, incluyendo las que acabas de crear para Adobe Commerce

Adicionalmente, una vez configurada la URL de tu comercio, siguiendo la ruta Configuración > Integraciones > Plugins > Adobe Commerce, podrás visualizar la Public API Key, así como la Private API Key ahí mismo.

Para volver a la lista de todas tus Credenciales en la Consola, deberás seguir la ruta Desarrolladores > Credenciales.

A continuación, te mostramos en video los pasos para obtener tus credenciales para Magento desde la Consola:

2.2. Habilita Kushki en tu tienda Magento

2.2.1. Ve a Stores > Configuration > Sales > Payment Methods, y busca el módulo de Kushki Payment en la sección de Other Payment Methods.

2.2.2. Haz clic en el botón Configure, ubicado al lado derecho del módulo.

2.2.3. En General Configuration podrás ajustar los datos generales del plugin de Kushki.

• En Country especifica el país de operación.
• Selecciona el ambiente para que las peticiones se envíen al servidor de Kushki con la opcion Environment:
  • Para el ambiente de pruebas selecciona Sandbox
  • Para el ambiente de producción selecciona Production
• El campo de la URL dependerá de si estás usando el ambiente de pruebas o el de producción.
  • Para el ambiente de pruebas usa: https://api-uat.kushkipagos.com
  • Para el ambiente de producción usa: https://api.kushkipagos.com
• Agrega el ID del comercio, así como las llaves públicas y privadas. Estas credenciales son las obtenidas en el paso 2.1 Obtén tus credenciales para Magento desde la Consola de Kushki. Si ya fueron generadas, pueden ser encontradas en la Consola, en Desarrolladores > Credenciales.
  
• Añade tu Webhook Signature y configura un webhook en la consola de Kushki, con el cual recibirás notificaciones de los estados de las transacciones. Este paso es indispensable.

• Selecciona si deseas un tema claro u oscuro.

2.2.4. Habilita los métodos de pago deseados seleccionando Yes en la sección Is Active de cada uno.

Una vez que hayas habilitado un método de pago de Kushki, los campos de configuración de cada uno serán visibles.

• Agrega el título del método de pago que será mostrado al cliente en el front-end en Title.
  
• Permite a los clientes pagar desde cualquier país en la sección Payment from Applicable Countries o restringe la lista de países en la sección Payment from Specific Countries.
  

Los impuestos se configuran en tu tienda de Magento, en la ruta Stores > Taxes.

3. Operación del plugin

Ahora que tienes el plugin instalado y configurado, es momento de ver cómo operar con él.

3.1. Estados de las órdenes en Magento

En Magento podemos tener diferentes estados para una orden. A continuación se detallan algunos de los posibles estados de una orden con el plugin de Kushki:

• Pending Payment Es el estado que tienen los nuevos pedidos que aún no han sido procesados. Este estado cambiará cuando el pago se confirme.
• Payment Review El pago del pedido está en revisión por parte de Kushki.
• Suspected Fraud Indica que la transacción es sospechosa de fraude. Cuando esto sucede, no se emite factura para el pedido ni se envía el correo electrónico de confirmación.
• Processing Significa que el pedido ha sido facturado o enviado, pero no ambos.
• Pending No se ha enviado factura ni se ha realizado el envío del pedido.
• On Hold Este estado se asigna de forma manual. Puedes colocar cualquier pedido en estado on hold cuando así lo requieras.
• Complete Los pedidos marcados como completos se han facturado y enviado en su totalidad.
• Closed El pago del pedido ha sido reembolsado.
• Canceled No se ha realizado el pago del pedido.

3.2. Procesa pagos en efectivo

Para procesar pagos en efectivo deberás activar y configurar el método de pago de Kushki Cash In en la configuración del plugin de Kushki Payment, según las instrucciones dadas en Habilita Kushki en tu tienda Magento. Recuerda configurar un webhook y agregar tu webhook signature durante la Configuración general del plugin, para recibir los cambios en los estados de las transacciones.

Una vez configurado, tus compradores podrán seleccionar la opción de pagar con efectivo. Durante el checkout, los compradores deberán llenar un formulario de datos personales para el envío, así como agregar un tipo y número de identificación, y por último, hacer la orden.

Una vez efectúe la orden el comprador, verá en pantalla el número de ticket, el monto total de la compra, así como la fecha de expiración. Además, verá la opción de descargar la orden de pago en efectivo. Esta también será enviada a la dirección de correo electrónico proporcionada en el formulario. Con la orden de pago, el cliente podrá dirigirse a alguno de los puntos de pago indicados en ese documento.

Por el lado de Magento, una vez se genere una nueva orden con Kushki Cash In, podremos ver la transacción en el listado de órdenes (Sales > Orders) con el estatus Payment Review, el cuál nos indica que el pago está en espera de ser procesado. Una vez se haya realizado el pago de manera exitosa, el estado de la orden cambiará a Processing, indicando que la transacción fue correctamente pagada. Si el tiempo venció y no se realizó el pago, el estado de la orden será Canceled.

3.3. Procesa pagos con tarjeta

Para procesar pagos únicos con tarjeta de crédito o débito, deberás activar y configurar el método de pago de Kushki Cards en la configuración del plugin de Kushki Payment, según las instrucciones dadas en Habilita Kushki en tu tienda Magento.

Adicionalmente, tendrás disponibles otros campos en la configuración del método de pago de Kushki Cards, como los tipos de tarjetas aceptadas y los pagos diferidos.

Una vez configurado el método, tus compradores podrán seleccionar la opción de pagar con tarjeta. Durante el checkout, los compradores deberán llenar el formulario de datos personales para el envío, así como agregar un tipo y número de identificación, y por último, agregar los datos de su tarjeta, como se muestra a continuación.

Por el lado de Magento, una vez se genere una nueva orden con Kushki Cards, podremos ver la transacción en el listado de órdenes (Sales > Orders) con el estatus Processing, el cuál nos indica que el pago se ha realizado, y el producto está a la espera de ser enviado. Una vez se haya realizado el envío, el estado de la orden cambiará a Complete, indicando que el pedido se ha facturado y enviado exitosamente.

3.3.1. Pagos con autorización y captura

Durante la Configuración del método de pago de Kushki Cards, tendrás la opción de habilitar pagos en dos pasos.

Al activar pagos con autorización y captura, cuando un cliente realice una compra, la orden quedará con el estado de Payment review.

Para capturar el pago dirígete a Sales > Orders, abre la orden que deseas capturar y en el menú de la izquierda dirígete a Invoces. Luego, haz clic en “view” y en el menú superior en Capture. Verás un mensaje de confirmación de la captura. El estado de la orden cambiará a Processing. Puedes ver el proceso en el siguiente GIF:

3.3.2. Pagos diferidos

Durante la Configuración del método de pago de Kushki Cards, tendrás la opción de habilitar pagos diferidos con ciertas características:

Es importante que selecciones los meses disponibles, así como el monto mínimo para el cuál se activará la opción de pago diferido.

Durante el checkout cuando un cliente haga una compra de un monto mayor al que colocaste para activar el pago diferido, así como una tarjeta que aplique, verá la opción de pagar en cuotas y podrá seleccionar los meses:

3.3.3. Anulaciones y Reembolsos

Existen dos tipos de devoluciones dependiendo del tipo de captura. Si se desea devolver un pago ya capturado, entonces se realizará un reembolso o refund. Si se desea cancelar una preutorización, entonces se realizará una anulación o void.

Para realizar una anulación de una autorización de un pago, sigue estos pasos:

1. En tu Consola de Administración de Magento, dirígete a Sales > Orders.
2. Selecciona la orden realizada con autorización que quieres anular.
3. Selecciona Invoices > View.
4. Selecciona Credit Memo en el menú superior izquierdo.
5. Marca la casilla Return to stock para que esos productos regresen a tu stock.
6. Haz clic en el botón de Cancel localizado en la parte inferior.

Para realizar un reembolso de un pago capturado, sigue estos pasos:

1. En tu Consola de Administración de Magento, dirígete a Sales > Orders.
2. Selecciona la orden que deseas reembolsar.
3. Selecciona Invoices > View.
4. Selecciona Credit Memo en el menú superior izquierdo.
5. Marca la casilla Return to stock para que esos productos regresen a tu stock.
6. Haz clic en el botón de Refund localizado en la parte inferior.

Verás un mensaje de confirmación, y la orden cambiará de estado a Closed. Puedes ver el proceso en el siguiente GIF:

3.4. Procesa pagos con transferencia

Para procesar pagos únicos por transferencia bancaria, deberás activar y configurar el método de pago de Kushki Transfer In en la configuración del plugin de Kushki Payment, según las instrucciones dadas en Habilita Kushki en tu tienda Magento.

Tendrás disponibles otros campos en la configuración del método de pago de Kushki Transfer In, relacionados al correo electrónico que se le enviará al comprador como confirmación de la orden:

Adicionalmente, podrás personalizar la apariencia del correo electrónico que se mandará en tu tienda Magento, siguiendo la ruta Marketing > Email templates > Kushki > Configuración de orden.

Una vez configurado el método, tus compradores podrán seleccionar la opción de pagar por transferencia. Durante el checkout, los compradores deberán llenar el formulario de datos personales para el envío, así como seleccionar su banco, un tipo de identificación y colocar el número de identificación.

Al efectuar una orden, el comprador verá en pantalla la opción de descargar la información de la compra, en donde aparecen los datos necesarios para realizar la transferencia. Esta información también será enviada a la dirección de correo electrónico proporcionada en el formulario.

Por el lado de Magento, una vez se genere una nueva orden con Kushki Transfer In, podremos ver la transacción en el listado de órdenes (Sales > Orders) con el estatus Payment Review, el cuál nos indica que el pago está en espera de ser procesado. Cuando se haya realizado el pago de manera exitosa, el estado de la orden cambiará a Processing, indicando que la transacción fue correctamente pagada. Si el tiempo venció y no se realizó el pago, el estado de la orden será Canceled.

4. Desinstalación

4.1. En el directorio de instalación de Magento, ve a app > code y remueve la carpeta que contiene el código fuente de Kushki.

4.2. Busca el módulo llamado Kushki_Payment y remueve la entrada del módulo de la tabla de la base de datos setup_module.

4.3. El módulo Kushki_Payment también debe ser removido de app > etc > config.php.

4.4. Actualiza Magento. Desde una terminal SSH, ejecuta el siguiente comando en la raíz del directorio Magento2: php bin/magento setup:upgrade.

4.5. Realiza la compilación de la instalación ejecutando el siguiente comando: php bin/magento setup:di:compile

4.6. Despliega el contenido estático. Ejecuta el siguiente comando en el directorio raíz de Magento2: php bin/magento setup:static-content:deploy.

4.7. Finalmente, remueve el caché ejecutando el comando: php bin/magento cache:flush.