Conekta VTEX v 1.0 configuration guide


Configuration Payment Provider Vtex

Initial account setup.

To configure the VTEX environment and receive payment transactions in the eCommerce site through Conekta, it is necessary to have 2 possible account settings i.e. ** Testing ** and ** Production **, which can be consulted after making the trade register.

You can start the registration process to obtain a Conekta at the following URL Panel Conekta.

Remember to keep in touch with the Conekta team and mention them that it is a business that will operate through VTEX as eCommerce platform. This will help the Conekta team focus the necessary efforts according to the specific needs of the platform.

You can check the keys at the following link Panel Conekta


Enable Conekta affiliation

Once you have the keys, you can start the Conekta membership setup process as your payment provider within VTEX. On the initial VTEX administration screen (https://{commerce}.myvtex.com/admin) locate the section regarding payments.

You should go to the following menu: Transactions> Payments> Settings> Gateway Affiliations and within this screen locate the add button( + ).

Within the connectors window locate and choose the Conekta and cic connector in it.

Then you must assign a unique name to the new affiliation. We suggest keeping Conekta as your name. In the Configure data from Conekta field, you must enter as ApplicationKey the data of the productive key that was generated at the moment the Conekta account became productive.

After performing this step, click on Save.

Payment methods

Payment methods are grouped there are 3 payment classifications:

CARD

  • All payments by Credit and Debit Card, Visa, MasterCard, American Express are considered here.

BANK ACCOUNT

  • They are the reference payments of the SPEI type, that is, it is made with the data of the CLABE account to show transfer data of the trade.

CONEKTA | OXXO Pay

  • The order to make the payment in an establishment or trade example is shown, such as an OXXO store.

To configure the payment methods, it is necessary to have the names of the VTEX-Conekta catalog as shown below:

Method Type
American Express card
Mastercard card
Visa card
Visa Electron card
Maestro card
Mastercard Debit card
SPEI SPEI
Conekta - OXXO Pay cash payment

Additionally, the plugin has a rest service, exposed locally (only visible to the IT Conekta administrator, not exposed to the public) which allows updating a payment method in case it changes.

You can send a request to your VTEX admin as follows:

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

Note: These nomenclatures are a standard for the translation of payment methods between VTEX and Conekta, so they should not be modified unless this change is agreed with the VTEX team.


Display of payment methods at checkout

In the case of credit and debit cards, they are grouped into the radio options "Visa", "MasterCard", "American Express". In the case of offline methods such as SPEI and OXXO PAY, they will be presented independently in the list of payment methods.

Custom payment settings. Within VTEX SPEI and OXXO PAY they will be configured as personalized payment methods. You should go to the following menu: Transactions> Payments> Settings> Custom payments. On this screen you must click on the Config button under the Promissories section.

For more information about custom payment methods, see the following VTEX documentation

Custom Payments Home

Form to capture custom payment methods.

You must enter the following information for each of the offline payment methods:

SPEI

  • Name: SPEI
  • Description: Payment by SPEI via CLABE bank account
  • Promissory's expiration date: 3
  • Automatic authorization: No
  • Change margin: 0

OXXO PAY

  • Name: OXXO
  • Description: Conekta | Cash payment through OXXO Pay
  • Promissory's expiration date: 3
  • Automatic authorization: No
  • Change margin: 0

Note: The NAME field cannot be other than the value specified above. For the other fields, they should only be modified in common agreement with the Conekta team and in consultation with VTEX, as these changes affect the lifetime of the payment methods and may generate errors when processed by Conekta.

Configuration of payment method of credit or debit card.

To register a credit or debit card payment method at checkout, you must go to the following menu Transactions> Payments> Settings> Payment Conditions and select the option (+) as shown in the following screen:

Subsequently, all existing payment methods will be shown for the configuration of credit cards and debit cards. The desired one must be selected:

Next, the payment condition must be configured. In it you can configure the collection conditions as months without interest, minimum amounts, validities, among other conditions. The specifications of the conditions can be reviewed with the implementing agency or directly in the VTEX documentation.

This configuration must be made for each credit card and / or debit card that you wish to register with your business. Remember that the type of cards as well as the commercial conditions (such as months without interest and other promotions) will depend in part on the commercial conditions that you establish with the Conekta team and that these conditions are enabled for your trade.

Payment terms registration screen for credit cards and debit cards.

Note: consider the modification of these conditions directly affect the information provided to Conekta to make the collection. It is recommended to review with the Conekta team all the changes you make in this section as they will affect the level of acceptance or rejection of payments.

Conekta | Oxxo Pay payment method configuration Within the VTEX payment provider administrator, go to the following menu "Transactions> Payments> Settings> Payment Conditions" and select add option as shown in the following screen:

Later all the existing payment methods for configuration will be shown. In our case we will look for the Conekta | OXXO Pay option in the personalized payments section as shown in the following screen:

On the configuration screen you must select the Conekta affiliation, mark the payment method as active and configure the name OXXO

Note: Due to connector configurations, the name and identifier of this payment method must be as is OXXO

Similarly, only click Save.

Payment method configuration "SPEI"

Within the Vtex Payment Provider manager, you must go to the following menu. Transactions> Payments> Settings> Payment Conditions and select option add (+) as shown in the following screen:

Later all the existing payment methods for configuration will be shown. In our case we will look for the “SPEI” option in the Other section as shown in the following screen:

On the configuration screen you must select the Conekta affiliation, mark the payment method as active and configure the name SPEI

Note: Due to connector configurations, the name and identifier of this payment method must be as is: SPEI

Similarly, only click Save.

Conekta Configuration

In the Conekta configurations, it is possible to create a webhoook, to indicate the confirmation of offline payment methods such as OXXO Cash, SPEI or online payment methods that for some reason have been pending.


Arming the callback URL

The URL for the callback of offline operations is made up as follows: https://{URL-BASE}/callbackVtex/{X-VTEX-API-AppKey}/{X-VTEX-API-AppToken}

  • URL-BASE: https://vtex-int.conekta.com
  • X-VTEX-API-AppKey: access key provided by the trade.
  • X-VTEX-API-AppToken: merchant account verification chain.

Both the key and the token must be generated in the VTEX environment of the trade. On the main administration screen, you should go to the following route: Account setting> Account managment> Account. Below the Security section is the button that allows you to generate the appKey and appToken

In the next pop-up window you will be asked to define a name for these keys, we recommend putting a name that allows you to easily identify the purpose of the key, for example, CONEKTA_WEBHOOK.

Note: You will then be presented with the apptoken. You must keep this key in a safe place, as this will be the only time it will be shown.

Once you have the information of the VTEX keys, you must form the complete url of the webhook which will look like this:

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


Webhook creation in Conekta

When entering the main page of the Conekta administration module, the section to configure the webhook can be found in the upper right.

Pop-up menu on the home page Panel Conekta

Webhook administration

Clicking on the Create your first webhook link here will open the following popup:

Once the webhook is configured, it is necessary to validate the configured URL, so you must click on the option "Test Webhook".

If the URL data is correct, you should see the following screen confirming that the connection was successful.


Google Tag Manager

Device fingerprint configuration

To configure the device fingerprint it is necessary to have a Google account with access to the Google Tag Manager of the VTEX site that is being configured.

  • 1.Login in tagmanager for the store that we are going to configure; Enter the tags section to configure the device fingerprint id.

  • 2.Create a "Custom HTML" product as in the following image

  • 3.In the HTML field of the configuration we must paste the HTML code that makes the call to the code that makes:

Note: In the function call you must enter the public key that was previously provided in the Conekta administration screen. Example: Conekta.setPublicKey ('key_llavePublicaABCDE12345');

Below is the HTML code that must be entered during the tag configuration within 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>

Configuration of the thank you page.

Like the device fingerprint, this configuration will be done from the tag creation section of Google Tag Manager. These settings will allow customization of the way information is presented on the thank you page once an order has been placed. This configuration applies to offline or asynchronous means of payment such as SPEI and OXXO PAY.

Below is the HTML code that must be entered during the tag configuration within 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>

Example "Thank you page SPEI"

Example "Thank you page OXXO Pay"

Note: the configuration and final appearance of these pages will be the responsibility of the trade and implementation team. The presented template must be taken as a basis and the branding specifications indicated by Conekta must be complied with at all times.