Conekta Developer's Hub

Bienvenido al Conekta Developer's Hub. Aquí encontrarás la más robusta documentación del API Conekta y todos los tutoriales que te ayudarán a comenzar a recibir pagos de la manera más rápida, sencilla y segura.

VTEX 1.0

Guía de instalación para plugin Conekta en VTEX.

Primeros pasos

Para instalar el plugin de Conekta es necesario que cuentes con una tienda en VTEX y una cuenta en Conekta. Si aún no tienes alguna de estas, puedes:

Una vez que cuentes con ellas, necesitarás obtener tus API Keys y tenerlas a la mano.

Recuerde mantenerse en contacto con el equipo de Conekta y mencionarles que se trata de un comercio que operará por medio de VTEX como plataforma de eCommerce. Esto le ayudará al equipo de Conekta a enfocar los esfuerzos necesarios segùn las necesidades específicas de la plataforma.

Compatibilidad

  • VTEX

📘

Importante

Recuerda contar con lo siguiente:

  • PHP 7.3
  • Contar con tu llave privada y pública de pruebas

Habilita la afiliación de Conekta

Una vez que cuente con las llaves, podrá iniciar con el proceso de configuración de la afiliación de Conekta como su proveedor de pagos dentro de VTEX. En la pantalla inicial de administración de VTEX (https://{comercio}.myvtex.com/admin) localice la sección referente a pagos.

Debe dirigirse al siguiente menú: Transactions > Payments > Settings > Gateway Affiliations y dentro de ésta pantalla localizar el botón de agregar ( + ).

Dentro de la ventana de conectores localiza y elige el conector de Conekta y da clic en él.

A continuación debe asignarle un nombre único a la nueva afiliación. Sugerimos mantener como nombre Conekta. En el campo de Configure data from Conekta debe ingresar como ApplicationKey el dato de la llave productiva que generó en el momento que la cuenta de Conekta se volvió productiva.

Después de realizar ese paso se debe dar clic en Save.

Activación de pre autorización

Puede elegir activar la preautorización de cobros realizados con tarjetas de crédito y tarjetas de débito. Para activar la preautorización en sus transacciones, solo debe agregar el prefijo preauth_ en el campo ApplicationKey como se muestra a continuación:

Métodos de pago

Los métodos de pago se agrupan existen 3 clasificaciones de pagos:

1. CARD

  • Aquí se consideran todos los pagos por Tarjeta de Crédito y Débito, Visa, MasterCard, American Express.

2. BANK ACCOUNT

  • Son los pagos de referencia tipo SPEI es decir que se realiza con los datos de la cuenta CLABE para mostrar datos de transferencia del comercio.

3. CONEKTA | OXXO Pay

  • Se muestra la orden para realizar el pago en un establecimiento o comercio ejemplo como puede ser una tienda OXXO.

Para configurar las formas de pago, es necesario contar con los nombres del catálogo de VTEX-Conekta como se muestra a continuación:

Método

Tipo

American Express

Tarjeta

Mastercard

Tarjeta

Visa

Tarjeta

Visa Electron

Tarjeta

Maestro

Tarjeta

Mastercard Debit

Tarjeta

SPEI

SPEI

Conekta - OXXO Pay

Pago en efectivo

Adicionalmente el plugin cuenta con un servicio rest, expuesto localmente (solo visible para el administrador TI Conekta, no expuesto al público) el cual permite actualizar un método de pago en caso de que éste cambie.

Puedes mandar una petición a tu admin de VTEX con un cURL así:

curl -H "Content-type: application/json" \
     -X POST \
     -d '{
       "key":"SPEI",
       "value":"CARD",
       "description":"Alguna descripción opcional"
    }' https://{hostname}:{port}/vtex/v1/admin/updatePaymentMethod

Nota: Estas nomenclaturas son un estándar para la traducción de métodos de pago entre VTEX y Conekta por lo que no deben ser modificadas a menos que se acuerde ese cambio con el equipo de VTEX.

Visualización de los métodos de pago en checkout

Para el caso de tarjeta de crédito y débito, se agrupan en las opciones de los radio “Visa”, “MasterCard”, “American Express”. Para el caso de los métodos offline como SPEI y OXXO PAY, se presentarán de manera independiente en el listado de métodos de pago.

Configuración de pagos personalizados. Dentro de VTEX SPEI y OXXO PAY se configuraran como métodos de pago personalizado. Debe dirigirse al siguiente menú: Transactions > Payments > Settings > Custom payments. En ésta pantalla debe dar clic en el botón Config bajo la sección Promissories.

Para más información acerca de los métodos de pago personalizados, consulte la siguiente documentación de VTEX.

Página principal de pagos personalizados

Formulario para capturar métodos de pago personalizados.

Debe ingresar la siguiente información para cada uno de los medios de pago offline:

SPEI

  • Name: SPEI
  • Description: Pago por SPEI vía cuenta CLABE bancaria
  • Promissory's expiration date: 3
  • Automatic authorization: No
  • Change margin: 0

OXXO PAY

  • Name: OXXO
  • Description: Conekta | Pago en Efectivo por medio de OXXO Pay
  • Promissory's expiration date: 3
  • Automatic authorization: No
  • Change margin: 0

Nota: el campo NAME no puede ser otro que no sea el valor arriba especificado. Para los demás campos, solo deben ser modificados en común acuerdo con el equipo de Conekta y en asesoría de VTEX, que estos cambios afectan el tiempo de vida de las formas de pago y puede generar errores al ser procesados por Conekta.

Configuración de método de pago de tarjeta de crédito o débito.

Para dar de alta un método de pago de tarjeta de crédito o débito en el checkout, debe dirigirse al siguiente menú Transactions > Payments > Settings > Payment Conditions y seleccionar la opción (+) como se muestra en la siguiente pantalla:

Posteriormente se mostrarán todos los métodos de pago existentes para configuración de tarjetas de crédito y tarjetas de débito. Se debe seleccionar la deseada:

A continuación, se debe realizar la configuración de la condición de pago. En ella se pueden configurar las condiciones de cobro como meses sin interese, montos mínimos, vigencias, entre otras condiciones. Las especificaciones de las condiciones se pueden revisar con la agencia implementadora o directamente en la documentación de VTEX.

Se debe realizar ésta configuración por cada tarjeta de crédito y/o tarjeta de débito que desee dar de alta en su comercio. Recuerde que el tipo de tarjetas así como las condiciones comerciales (como meses sin intereses y otras promociones) dependerá en parte de las condiciones comerciales que establezca con el equipo de Conekta y de que éstas condiciones se encuentren habilitadas para su comercio.

Pantalla de alta de condiciones de pago para tarjetas de crédito y tarjetas de débito.
Nota: considere la las modificación de estas condiciones afectan directamente a la información que se le proporciona a Conekta para realizar el cobro. Se recomienda revisar con el equipo de Conekta todos los cambios que realice en éste apartado ya que afectarán el nivel de aceptación o rechazo de las pagos.

Configuración de método de pago Conekta | Oxxo Pay Dentro del administrador de payment provider de VTEX, hay que dirigirse al siguiente menú "Transactions > Payments > Settings > Payment Conditions" y seleccionar opción agregar como se muestra en la siguiente pantalla:

Posteriormente se mostrarán todos los métodos de pago existentes para configuración. En nuestro caso buscaremos la opción Conekta | OXXO Pay en la sección de pagos personalizados como se muestra en la siguiente pantalla:

En la pantalla de configuración hay que seleccionar la afiliación de Conekta, marcar como activo el método de pago y configurar el nombre OXXO

Nota: Debido a configuraciones del conector, el nombre e identificador de este método de pago deberá de ser tal cual OXXO.

De igual manera, solo se da clic en Save.

Configuración de método de pago “SPEI”

Dentro del administrador de Payment Provider de Vtex, debe dirigirse al siguiente menú: Transactions > Payments > Settings > Payment Conditions y seleccionar opción agregar ( + ) como se muestra en la siguiente pantalla:

Posteriormente se mostrarán todos los métodos de pago existentes para configuración. En nuestro caso buscaremos la opción “SPEI” en la sección de Otro como se muestra en la siguiente pantalla:

En la pantalla de configuración hay que seleccionar la afiliación de Conekta, marcar como activo el método de pago y configurar el nombre SPEI

Nota: Debido a configuraciones del conector, el nombre e identificador de este método de pago deberá de ser tal cual: SPEI

De igual manera solo se da clic en Save.

Configuración Conekta

En las configuraciones de Conekta, es posible realizar la creación de un webhoook, para indicar la confirmación de medios de pago offline como OXXO Cash, SPEI o medios de pago en línea que por algún motivo hayan quedado pendientes.

Armado de URL del callback

La URL para el callback de las operaciones offline se compone de la siguiente forma:
https://{URL-BASE}/callbackVtex/{X-VTEX-API-AppKey}/{X-VTEX-API-AppToken}

  • URL-BASE: https://vtex-int.conekta.com.
  • X-VTEX-API-AppKey: llave de acceso proporcionada por el comercio.
  • X-VTEX-API-AppToken: cadena de verificación de la cuenta del comercio.

Tanto el key como el token deben ser generados en el ambiente VTEX del comercio. En la pantalla principal de administración, debe dirigirse a la siguiente ruta: Account setting > Account managment > Account. Debajo de la sección Security se encuentra el botón que permite generar la appKey y appToken .

En la siguiente ventana emergente se le pedirá definir un nombre para éstas llaves, recomendamos poner un nombre que permita identificar fácilmente el propósito de la llave, por ejemplo, CONEKTA_WEBHOOK.

Nota: A continuación se le presentará el apptoken. Debe resguardar ésta clave en un lugar seguro, ya que ésta será la única ocasión en la que se mostrará.

Una vez que tenga la información de las llaves de VTEX, deberá formar la url completa del webhook el cual se verá de la siguiente forma:

https://{urlporconfirmar}/callbackvtex/vtexappkey-comercio-VWUYJH/QERNPRSZPPLSWMQDTJGZIQVPKLGBSNHDLJACCSAVHSUPOMQALD123456789DDLRGCHIGNLOAAJKSQWG123456789PXKQLRHGFCOXCHSHAGDBBFHFBSWCYOAKTAKM

Creación de Webhook en Conekta

Al ingresar a la página principal de módulo de administración de Conekta, se puede localizar en la parte superior derecha el apartado para realizar la configuración del webhook.

Menú emergente en la página principal Panel Conekta

Administración de webhooks

Al dar clic en la liga Crea tu primer webhook aquí se abrirá la siguiente ventana emergente:

Una vez configurado el webhook, es necesario validar la URL configurada, por lo que se deberá dar clic en la opción “Probar Webhook”.

Google Tag Manager

Configuración Device fingerprint

Para realizar la configuración del device fingerprint es necesario contar con una cuenta de Google con acceso al Google Tag Manager del sitio VTEX que se está configurando.

  1. Hacer login en Google Tag Manager para la tienda que vamos a configurar. Ingresar al apartado etiquetas (tags) para configurar el device fingerprint id.

  2. Crear un producto de “HTML Personalizado” como se en la siguiente imagen:

  1. En el campo HTML de la configuración debemos pegar el código HTML que realiza el llamado al código que realiza:

Nota: en el llamado a la función debe ingresar la llave pública que se proporcionó previamente en la pantalla de administración de Conekta.

Ejemplo: Conekta.setPublicKey('key_llavePublicaABCDE12345');

A continuación, se muestra el código HTML que se debe ingresar durante la configuración de la etiqueta dentro de Google Tag Manager.

<script type="text/javascript" src="https://cdn.conekta.io/js/latest/conekta.js"></script>
<script type="text/javascript">
    $(document).ready(function() {
        document.getElementsByClassName("pg-oxxo").item(0).getElementsByTagName('span').item(0).textContent='Conekta - OXXO Pay';
        vtexjs.checkout.getOrderForm().done(function(orderForm){
            Conekta.setPublicKey('key_llavePublicaABCDE12345');
            var sessionId = Conekta._helpers.getSessionId();
            window.vtex.deviceFingerprint = sessionId;
            console.log('Conekta Device Fingerprint', window.vtex.deviceFingerprint);
        });
    });
</script>

Configuración del thank you page

Al igual que el device fingerprint, esta configuración se realizará desde la sección de creación de etiquetas de Google Tag Manager. Esta configuración permitirá realizar la personalización de la forma en que se presenta la información en el thank you page una vez que se ha colocado una orden. Ésta configuración aplica para los medios de pago offline o asíncronos como SPEI y OXXO PAY.

A continuación se muestra el código HTML que se debe ingresar durante la configuración de la etiqueta dentro de Google Tag Manager.

<script type="text/javascript">
  var orderNumber;
    var params = window.location.search.split('&');
    for (var i = 0; i < params.length; i++) {
      if (params[i].indexOf('og=') != -1) {
        orderNumber = params[i].split('=')[1];
      }
    }
    $.get('/api/checkout/pub/orders/order-group/' + orderNumber, function(data) {
      var acquirer = data[0].paymentData.transactions[0].payments[0].connectorResponses.acquirer;
      var nsu = data[0].paymentData.transactions[0].payments[0].connectorResponses.nsu;
      var paymentSystemName = data[0].paymentData.transactions[0].payments[0].paymentSystemName;
      if (acquirer.indexOf('Conekta') != -1) {
        if (paymentSystemName.indexOf('oxxo') != -1) {
          nsu = nsu.split('|');
          $('.cf.br2.pa4.cconf-alert.ba.b--light-silver.bg-washed-green').prepend('<div style="text-align: center; margin-bottom: 16px"><img src="https://conektamx.vtexcommercestable.com.br//arquivos/oxxopay-brand.png"" /></div>');
          $('.cf.br2.pa4.cconf-alert.ba.b--light-silver.bg-washed-green div div').append('<div style="margin-top: 16px;text-align: center"><h4>REFERENCIA</h4><div style="display:inline-block; padding: 8px 48px; border: 1px solid #AAA"><h4>' + nsu[0].match(/.{1,4}/g).join('-') + '</h4><img style="width: 150px" src="' + (nsu.length > 1 ? nsu[1] : '') + '" /></div></div><div style="margin-top: 16px"><h5>INSTRUCCIONES</h5><ol><li>Acude a la tienda OXXO más cercana.</li><li>Indica en caja que quieres realizar un pago de <b>OXXOPay.</b></li><li>Dicta al cajero el número de referencia de esta ficha para que la tecleé directamente en la pantalla de venta.</li><li>Realiza el pago correspondiente con dinero en efectivo.</li><li>Al confirmar tu pago, el cajero te entregará un comprobante impreso. <b>En él podrás verificar que se haya realizado correctamente. </b> Conserva este comprobante de pago.</li></ol></div>');

        }
        if (paymentSystemName.indexOf('spei') != -1) {
          $('.cf.br2.pa4.cconf-alert.ba.b--light-silver.bg-washed-green').prepend('<div style="text-align: center; margin-bottom: 16px"><img src="https://conektamx.vtexcommercestable.com.br//arquivos/spei-brand.png"" /></div>');
          $('.cf.br2.pa4.cconf-alert.ba.b--light-silver.bg-washed-green div div').append('<div style="margin-top: 16px;text-align: center"><h4>CLABE</h4><div style="display:inline-block; padding: 8px 48px; border: 1px solid #AAA"><h4>' + nsu + '</h4></div></div><div style="margin-top: 16px"><h5>INSTRUCCIONES</h5><ol><li>Accede a tu banca en línea.</li><li>Da de alta la CLABE en esta ficha. <strong>El banco deberá de ser STP</strong>.</li><li>Realiza la transferencia correspondiente por la cantidad exacta en esta ficha, <strong>de lo contrario se rechazará el cargo</strong>.</li><li>Al confirmar tu pago, el portal de tu banco generará un comprobante digital.</li></ol></div>');
        }
      }
    });
</script>

Ejemplo "Thank you page SPEI"

Ejemplo "Thank you page SPEI"

Ejemplo "Thank you page OXXO Pay"

Nota: la configuración y aspecto final de éstas páginas serán responsabilidad del comercio y equipo implementación. Se debe tomar como base el template presentado y cumplir en todo momento las especificaciones de branding que indique Conekta.

🚧

Límites

  • El módulo no genera suscripciones (puedes generarlo con tu programador).
  • El módulo no genera customers (puedes generarlo con tu programador).

Updated 11 days ago

VTEX 1.0


Guía de instalación para plugin Conekta en VTEX.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.