Toggle navigation

Documentación

Version 2.0.0

Conecte su plataforma con el API de Global Payments ViComm en minutos, usando SDK, botones de pago, ligas para pagar, desde su Celular o su página Web.


Ya sea que esté creando un cobro único o guardando los datos de la tarjeta de su cliente para realizar los cobros después, utilizar la información de la tarjeta con Global Payments ViComm es un proceso de dos pasos:

  1. Recopile de forma segura segura información de pago mediante la tokenización de la tarjeta.
  2. Use la información de pago en una solicitud de cargo o guárdela para más adelante.

La tokenización del lado del cliente es el método que Global Payments ViComm usa para recopilar información de la tarjeta directamente de sus clientes de manera segura. Durante este proceso, un token que representa esta información se devuelve a su servidor para su uso en una solicitud de cargo  (o para guardar los detalles de la tarjeta para su uso posterior).

La tokenización  asegura que ningún dato sensible de la tarjeta necesite estar en su servidor para que su integración pueda operar de manera compatible con PCI. Si alguna información de la tarjeta pasara por,  o se llegase a almacenar en su servidor,  usted sería responsable de cualquier penalidad o auditoría que imponga PCI DSS.

Javascript

Github Repository

GpViComm JS es una biblioteca que permite a los desarrolladores conectar fácilmente con el API de TARJETAS DE CRÉDITO de Global Payments ViComm.

Revise el ejemplo funcionando

Instalación

Primero necesitas incluir jQuery y los archivos payment_stable.min.js y payment_stable.min.css dentro de tu página web especificando "UTF-8" como charset.

<script src="https://code.jquery.com/jquery-1.11.3.min.js" charset="UTF-8"></script>

<link href="https://cdn.gpvicomm.com/ccapi/sdk/payment_stable.min.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.gpvicomm.com/ccapi/sdk/payment_stable.min.js" charset="UTF-8"></script>

Uso

Utilizando el Form de GpViComm

Cualquier elemento con la clase payment-form será automáticamente convertido en una entrada de tarjeta de crédito básica con fecha de vencimiento y el check de CVC.

La manera más fácil de comenzar con GpViCommForm es insertando el siguiente pedazo de código:

<div class="payment-form" id="my-card" data-capture-name="true"></div>

Para obtener el objeto Card de la instancia PaymentForm, pregunte al formulario por su tarjeta.

let myCard = $('#my-card');
let cardToSave = myCard.PaymentForm('card');
if(cardToSave == null){
  alert("Invalid Card Data");
}

Si la tarjeta (Card) regresada es null, el estado de error mostrará los campos que necesitan ser arreglados.

Una vez que obtengas un objeto no null de la tarjeta (Card) del widget, podrás llamar addCard.

Biblioteca Init

Siempre debes inicializar la biblioteca.

/**
  * Init library
  *
  * @param env_mode `prod`, `stg`, `local` para cambiar ambiente. Por defecto es `stg`
  * @param client_app_code proporcionado por Global Payments ViComm.
  * @param client_app_key proporcionado por Global Payments ViComm.
  */
Payment.init('stg', 'CLIENT_APP_CODE', 'CLIENT_APP_KEY');

addCard Agregar una Tarjeta

La función addCard convierte los datos confidenciales de una tarjeta, en un token que puede pasar de forma segura a su servidor, para realizar el cobro al usuario.

Esta funcionalidad consume el servicio de nuestro API pero de manera segura para comercios que no cuentan con certificación PCI. Aquí podras encontrar la descripción de cada campo en la respuesta.

/*
 * @param uid Identificador del usuario. Este es el id que usas del lado de tu aplicativo.
 * @param email Email del usuario para iniciar la compra. Usar el formato válido para e-mail.
 * @param card La tarjeta que se desea tokenizar.
 * @param success_callback Funcionalidad a ejecutar cuando el servicio de la pasarela responde correctamente. (Incluso si se recibe un estado diferente a "valid")
 * @param failure_callback Funcionalidad a ejecutar cuando el servicio de la pasarela responde con un error.
 */
Payment.addCard(uid, email, cardToSave, successHandler, errorHandler);

let successHandler = function(cardResponse) {
  console.log(cardResponse.card);
  if(cardResponse.card.status === 'valid'){
    $('#messages').html('Tarjeta correctamente agregada<br>'+
                  'Estado: ' + cardResponse.card.status + '<br>' +
                  "Token: " + cardResponse.card.token + "<br>" +
                  "Referencia de transacción: " + cardResponse.card.transaction_reference
                );
  }else if(cardResponse.card.status === 'review'){
    $('#messages').html('Tarjeta en revisión<br>'+
                  'Estado: ' + cardResponse.card.status + '<br>' +
                  "Token: " + cardResponse.card.token + "<br>" +
                  "Referencia de transacción: " + cardResponse.card.transaction_reference
                );
  }else if(cardResponse.card.status === 'pending'){
    $('#messages').html('Tarjeta pendiente de aprobar<br>'+
                  'Estado: ' + cardResponse.card.status + '<br>' +
                  "Token: " + cardResponse.card.token + "<br>" +
                  "Referencia de transacción: " + cardResponse.card.transaction_reference
                );
  }else{
    $('#messages').html('Error<br>'+
                  'Estado: ' + cardResponse.card.status + '<br>' +
                  "Mensaje: " + cardResponse.card.message + "<br>"
                );
  }
  submitButton.removeAttr("disabled");
  submitButton.text(submitInitialText);
};

let errorHandler = function(err) {
  console.log(err.error);
  $('#messages').html(err.error.type);
  submitButton.removeAttr("disabled");
  submitButton.text(submitInitialText);
};

El tercer argumento para el addCard es un objeto Card que contiene los campos requeridos para realizar la tokenización.

getSessionId

El Session ID es un parámetro que Global Payments ViComm utiliza para fines del antifraude. Llame este método si usted desea recolectar la información del dispositivo del usuario.

let session_id = Payment.getSessionId();

Una vez que tenga el Session ID, puedes pasarlo a tu servidor para realizar el cargo al usuario.

PaymentForm Referencia Completa

Inserción Manual

Si desea alterar manualmente los campos utilizados por PaymentForm para añadir clases adicionales, el placeholder o id. Puedes rellenar previamente los campos del formulario como se muestra a continuación.

Esto podría ser útil en caso de que desees procesar el formulario en otro idioma (de forma predeterminada, el formulario se representa en español), o para hacer referencia a alguna entrada por nombre o id.

Por ejemplo si desea mostrar el formulario en Inglés y añadir una clase personalizada para el card_number

<div class="payment-form">
  <input class="card-number my-custom-class" name="card-number" placeholder="Card number">
  <input class="name" id="the-card-name-id" placeholder="Card Holders Name">
  <input class="expiry-month" name="expiry-month">
  <input class="expiry-year" name="expiry-year">
  <input class="cvc" name="cvc">
</div>

Seleccionar Campos

Puedes determinar los campos que mostrará el formulario.

Field Description
data-capture-name Input para nombre del Tarjetahabiente, requerido para tokenizar
data-capture-email Input para email del usuario
data-capture-cellphone Input para teléfono celular del usuario
data-icon-colour Color de los íconos
data-use-dropdowns Utiliza una lista desplegable para establecer la fecha de expiración de la tarjeta
data-exclusive-types Define los tipos de tarjetas permitidos
data-invalid-card-type-message Define un mensaje personalizado para mostrar cuando se registre una tarjeta no permitida

El campo 'data-use-dropdowns' puede resolver el problema que se presenta con la mascara de expiración en dispositivos móviles antiguos.

Se integra en el form de manera simple, como se muestra a continuación:

<div class="payment-form"
id="my-card"
data-capture-name="true"
data-capture-email="true"
data-capture-cellphone="true"
data-icon-colour="#569B29"
data-use-dropdowns="true">

Tipos de tarjetas específicos

Si deseas especificar los tipos de tarjetas permitidos en el formulario, como Exito o Alkosto. Puedes configurarlo como en el siguiente ejemplo: Cuando una tarjeta de un tipo no permitido es capturado, el formulario se reinicia, bloqueando las entradas y mostrando un mensaje Tipo de tarjeta invalida para está operación.

<div class="payment-form"
id="my-card"
data-capture-name="true"
data-exclusive-types="ex,ak"
data-invalid-card-type-message="Tarjeta invalida. Por favor ingresa una tarjeta Exito / Alkosto."
>

Revisa todos los tipos de tarjetas permitidos por Global Payments ViComm.

Leyendo los Valores

PaymentForm proporciona funcionalidad que le permite leer los valores del campo de formulario directamente con JavaScript.

Genera un elemento de PaymentForm y asigne un id único (en este ejemplo my-card)

<div class="payment-form" id="my-card" data-capture-name="true"></div>

El siguiente javascript muestra cómo leer cada valor del formulario en variables locales.

let myCard = $('#my-card');

let cardType = myCard.PaymentForm('cardType');
let name = myCard.PaymentForm('name');
let expiryMonth = myCard.PaymentForm('expiryMonth');
let expiryYear = myCard.PaymentForm('expiryYear');
let fiscalNumber = myCard.PaymentForm('fiscalNumber');

Funciones

Para llamar a una función en un elemento PaymentForm, sigue el patrón a continuación. Remplace el texto 'function' con el nombre de la función que desea llamar.

$('#my-card').PaymentForm('function')

Las funciones disponibles se enumeran a continuación

Function Description
card Obtiene la tarjeta del objeto
cardType Obtiene el tipo de tarjeta que se capturó
name Obtiene el nombre capturado
expiryMonth Obtiene el mes de expiración de la tarjeta
expiryYear Obtiene el año de expiración de la tarjeta
fiscalNumber Obtiene el número fiscal del usuario / cédula

Función CardType

La función cardType devolverá una cadena según el número de tarjeta ingresado. Si no se puede determinar el tipo de tarjeta, se le dará una cadena vacía.

Marcas permitidas

Android

Github Repository

Add it in your root build.gradle at the end of repositories:

allprojects {
        repositories {
            ...
            maven { url 'https://jitpack.io' }
        }
    }

Add this line to your app's build.gradle inside the dependencies section:

implementation 'com.github.gpvicomm:gpvicomm-android:1.0'

ProGuard

If you're planning on optimizing your app with ProGuard, make sure that you exclude the GpVicomm bindings. You can do this by adding the following to your app's proguard.cfg file:

-keep class com.gpvicomm.payment.** { *; }

Usage

Using the CardMultilineWidget

global_pay1

You can add a widget to your apps that easily handles the UI states for collecting card data.

First, add the CardMultilineWidget to your layout.


<com.gpvicomm.payment.view.CardMultilineWidget android:id="@+id/card_multiline_widget" android:layout_alignParentTop="true" android:layout_width="match_parent" android:layout_height="wrap_content" />

You can customize the view with this tags:

app:shouldShowPostalCode="true"app:shouldShowLogo="true"app:shouldShowCardHolderName="true"app:shouldShowScanCard="true"

In order to use any of this tags, you'll need to enable the app XML namespace somewhere in the layout.

xmlns:app="http://schemas.android.com/apk/res-auto"

To get a Card object from the CardMultilineWidget, you ask the widget for its card.

Card cardToSave=cardWidget.getCard();
        if(cardToSave==null){
        Alert.show(mContext,
        "Error",
        "Invalid Card Data");
        return;
        }

If the returned Card is null, error states will show on the fields that need to be fixed.

Once you have a non-null Card object from the widget, you can call addCard.

Init library

You should initialize the library on your Application or in your first Activity.

import android.support.v7.app.ActionBarActivity;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;

import com.gpvicomm.payment.Payment;
import com.gpvicomm.payment.demo.utils.Constants;

public class MainActivity extends ActionBarActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        /**
         * Init library
         *
         * @param test_mode false to use production environment
         * @param client_app_code provided by GpVicomm.
         * @param client_app_key provided by GpVicomm.
         */
        Payment.setEnvironment(Constants.IS_TEST_MODE, Constants.CLIENT_APP_CODE, Constants.CLIENT_APP_KEY);


        // In case you have your own Fraud Risk Merchant Id
        //Payment.setRiskMerchantId(1000);
        // Note: for most of the devs, that's not necessary.
    }
}

addCard

addCard converts sensitive card data to a single-use token which you can safely pass to your server to charge the user.

Payment.addCard(mContext,uid,email,cardToSave,new TokenCallback(){

public void onSuccess(Card card){

        if(card!=null){
        if(card.getStatus().equals("valid")){
        Alert.show(mContext,
        "Card Successfully Added",
        "status: "+card.getStatus()+"\n"+
        "Card Token: "+card.getToken()+"\n"+
        "transaction_reference: "+card.getTransactionReference());

        }else if(card.getStatus().equals("review")){
        Alert.show(mContext,
        "Card Under Review",
        "status: "+card.getStatus()+"\n"+
        "Card Token: "+card.getToken()+"\n"+
        "transaction_reference: "+card.getTransactionReference());

        }else{
        Alert.show(mContext,
        "Error",
        "status: "+card.getStatus()+"\n"+
        "message: "+card.getMessage());
        }


        }

        //TODO: Create charge or Save Token to your backend
        }

public void onError(PaymentError error){
        Alert.show(mContext,
        "Error",
        "Type: "+error.getType()+"\n"+
        "Help: "+error.getHelp()+"\n"+
        "Description: "+error.getDescription());

        //TODO: Handle error
        }

        });

The first argument to addCard is mContext (Context).

  • mContext. Context of the Current Activity

The second argument to addCard is uid (String).

  • uid Customer identifier. This is the identifier you use inside your application; you will receive it in notifications.

The third argument to addCard is email (String).

  • email Email of the customer

The fourth argument to addCard is a Card object. A Card contains the following fields:

  • number: card number as a string without any separators, e.g. '4242424242424242'.
  • holderName: cardholder name.
  • expMonth: integer representing the card's expiration month, e.g. 12.
  • expYear: integer representing the card's expiration year, e.g. 2013.
  • cvc: card security code as a string, e.g. '123'.
  • type:

The fifth argument tokenCallback is a callback you provide to handle responses from GpVicomm. It should send the token to your server for processing onSuccess, and notify the user onError.

Here's a sample implementation of the token callback:

Payment.addCard(
        mContext,uid,email,cardToSave,
        new TokenCallback(){
public void onSuccess(Card card){
        // Send token to your own web service
        MyServer.chargeToken(card.getToken());
        }
public void onError(PaymentError error){
        Toast.makeText(getContext(),
        error.getDescription(),
        Toast.LENGTH_LONG).show();
        }
        }
        );

addCard is an asynchronous call – it returns immediately and invokes the callback on the UI thread when it receives a response from GpVicomm's servers.

getSessionId

The Session ID is a parameter GpVicomm use for fraud purposes. Call this method if you want to Collect your user's Device Information.

String session_id=Payment.getSessionId(mContext);

Once you have the Session ID, you can pass it to your server to charge the user.

Client-side validation helpers

The Card object allows you to validate user input before you send the information to GpVicomm.

validateNumber

Checks that the number is formatted correctly and passes the Luhn check.

validateExpiryDate

Checks whether or not the expiration date represents an actual month in the future.

validateCVC

Checks whether or not the supplied number could be a valid verification code.

validateCard

Convenience method to validate card number, expiry date and CVC.

Getting started with the Android example app

Note: the app require an Android SDK and Gradle to build and run.

Building and Running the GpVicommStore

Before you can run the GpVicommStore application, you need to provide it with your GpVicomm Credentials and a Sample Backend.

  1. If you don't have any Credentials yet, please ask your contact on GpVicomm Team for it.
  2. Head to https://github.com/gpvicomm/example-java-backend and click "Deploy to Heroku" ( you may have to sign up for a Heroku account as part of this process). Provide your GpVicomm Server Credentials SERVER_APP_CODE and SERVER_APP_KEY fields under 'Env'. Click "Deploy for Free".
  3. Open the project on Android Studio.
  4. Replace the CLIENT_APP_CODE and CLIENT_APP_KEY constants in Constants.java with your own GpVicomm Client Credentials.
  5. Replace the BACKEND_URL variable in the Constants.java file with the app URL Heroku provides you with (e.g. "https://my-example-app.herokuapp.com")
  6. Run the Project.

Important Note: if you only have one APP_CODE, please asume that it's your SERVER_APP_CODE. So you need to ask your contact on GpVicomm Team for your CLIENT_APP_CODE.

===================

El SDK Android de pagos GpVicomm Global Payments es una biblioteca que permite a los desarrolladores conectarse fácilmente al API de tarjetas de Crédito de GpVicomm.

Instalación

Android Studio (o Gradle)

Add it in your root build.gradle at the end of repositories:

allprojects {
        repositories {
            ...
            maven { url 'https://jitpack.io' }
        }
    }

Add this line to your app's build.gradle inside the dependencies section:

implementation 'com.github.gpvicomm:gpvicomm-android:1.2.9'

ProGuard

Si usted está planeando optimiar su aplicación con ProGuard, asegúrese de excluir los enlaces de gpvicomm. Usted puede realizarlo añadiendo lo siguiente al archivo proguard.cfg de su app:

 -keep class com.gpvicomm.payment.** { *; }

Uso

Utilizando el CardMultilineWidget

Puede agregar un widget a sus aplicaciones que maneje fácilmente los estados de la interfaz de usuario para recopilar datos de la tarjeta.

Primero, añada el CardMultilineWidget a su layout.


<com.gpvicomm.payment.view.CardMultilineWidget android:id="@+id/card_multiline_widget" android:layout_alignParentTop="true" android:layout_width="match_parent" android:layout_height="wrap_content" />

Ustede puede personalizar la vista con las siguientes etiquetas:

app:shouldShowPostalCode="true"app:shouldShowLogo="true"app:shouldShowCardHolderName="true"app:shouldShowScanCard="true"

Para usar cualquiera de estas etiquetas, deberá habilitar el espacio de nombres XML de la aplicación en algún lugar del layout.

xmlns:app="http://schemas.android.com/apk/res-auto"

Para obtener un objeto Card delCardMultilineWidget, pidale al widget su tarjeta.

Card cardToSave=cardWidget.getCard();
        if(cardToSave==null){
        Alert.show(mContext,
        "Error",
        "Invalid Card Data");
        return;
        }

Si la Card devuelta es null , se mostrarán estados de error en los campos que deben corregirse.

Una vez que tenga un objeto Card no null regresado desde el widget, puede llamar a addCard.

Inicializar Biblioteca

Usted debe inicializar la biblioteca en su Aplicación en su primera actividad. You should initialize the library on your Application or in your first Activity.

import android.support.v7.app.ActionBarActivity;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;

import com.gpvicomm.payment.Payment;
import com.gpvicomm.payment.demo.utils.Constants;

public class MainActivity extends ActionBarActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        /**
         * Init library
         *
         * @param test_mode false to use production environment
         * @param client_app_code provided by gpvicomm.
         * @param client_app_key provided by gpvicomm.
         */
        Payment.setEnvironment(Constants.IS_TEST_MODE, Constants.CLIENT_APP_CODE, Constants.CLIENT_APP_KEY);


        // In case you have your own Fraud Risk Merchant Id
        //Payment.setRiskMerchantId(1000);
        // Note: for most of the devs, that's not necessary.
    }
}

addCard

addCard convierte datos confidenciales de la tarjeta en un token de un solo uso que puede pasar de forma segura a su servidor para realizar el cobro al usuario.

Payment.addCard(mContext,uid,email,cardToSave,new TokenCallback(){

public void onSuccess(Card card){

        if(card!=null){
        if(card.getStatus().equals("valid")){
        Alert.show(mContext,
        "Card Successfully Added",
        "status: "+card.getStatus()+"\n"+
        "Card Token: "+card.getToken()+"\n"+
        "transaction_reference: "+card.getTransactionReference());

        }else if(card.getStatus().equals("review")){
        Alert.show(mContext,
        "Card Under Review",
        "status: "+card.getStatus()+"\n"+
        "Card Token: "+card.getToken()+"\n"+
        "transaction_reference: "+card.getTransactionReference());

        }else{
        Alert.show(mContext,
        "Error",
        "status: "+card.getStatus()+"\n"+
        "message: "+card.getMessage());
        }


        }

        //TODO: Create charge or Save Token to your backend
        }

public void onError(PaymentError error){
        Alert.show(mContext,
        "Error",
        "Type: "+error.getType()+"\n"+
        "Help: "+error.getHelp()+"\n"+
        "Description: "+error.getDescription());

        //TODO: Handle error
        }

        });

El primer argumento del addCard es mContext (Context).

  • mContext. Context de la Actividad actual.

El segundo argumento del addCard es uid (Cadena).

  • uid Identificador de comprador. Este es el identificador que usa dentro de su aplicación; lo recibirá en las notificaciones.

El tercer argumento del addCard es el email (Cadena).

  • email Email del comprador

El cuarto argumento del addCard es un objeto de tipo Card. Un objeto Card contiene los siguientes campos:

  • number: número de tarjeta como cadena sin ningún separador, por ejemplo '4242424242424242'.
  • holderName: nombre del tarjehabiente.
  • expMonth: entero que representa el mes de expiración de la tarjeta, por ejemplo 12.
  • expYear: entero que represetna el año de expiración de la tarjeta, por ejemplo 2019.
  • cvc: código de seguridad de la tarjeta, como cadena, por ejemplo '123'.
  • type: el tipo de tarjeta.

El quinto argumento tokenCallBack es un callback que usted provee para manejar las respuestas recibidas de gpvicomm.

The fifth argument tokenCallback is a callback you provide to handle responses from gpvicomm. Deberá enviar el token a su servidor para procesar onSuccess y notificar al usuario onError.

Aquí se muestra un ejemplo de implementación de callback del token:

Payment.addCard(
        mContext,uid,email,cardToSave,
        new TokenCallback(){
public void onSuccess(Card card){
        // Send token to your own web service
        MyServer.chargeToken(card.getToken());
        }
public void onError(PaymentError error){
        Toast.makeText(getContext(),
        error.getDescription(),
        Toast.LENGTH_LONG).show();
        }
        }
        );

addCard es una llamada asíncrona - regresa inmediatamente e invoca el callback en el hilo de la interfaz, cuando recibe una respuesta de los servidores de gpvicomm.

getSessionId

El Session ID es un parámetro que gpvicomm utiliza para fines de antifraude. Llave esté método cuando quiera recabar la información del dispositivo.

String session_id=Payment.getSessionId(mContext);

Una vez que tenga el Session ID, usted podrá pasarlo a su servidor para realizar el cobro a su usuario.

Herramientas de validación del lado del Cliente

El objeto Card permite validar la información capturada por el usuario antes de enviarla a gpvicomm.

validateNumber

Verifica que el número tenga el formato correcto y pase el algoritmo de Luhn.

validateExpiryDate

Comprueba que la fecha de expiración representa una fecha real futura.

validateCVC

Comprueba si el número proporcionado podría ser un código de verificación válido o no.

validateCard

Método que valida el número de tarjeta, la fecha de expiración y el CVC.

Introducción a la aplicación de ejemplo de Android

Nota: la aplicación requiere Android SDK y Gradle para coinstruir y ejecutar.

Construyendo y Ejecutando la PaymentStore

Antes de que pueda pueda correr la aplicación PaymentStore, ested necesita proveerla con las credenciales de gpvicomm y un backend de muestra.

  1. Si aún no cuenta con credenciales, pídalas a su contancto en el equipo de gpvicomm.
  2. Dirígase a https://github.com/gpvicomm/example-java-backend y haga click en "Deploy to Heroku" (es posible que tengas que registrarte para obtener una cuenta de Heroku como parte de este proceso). Proporcione sus credenciales de servidor de gpvicomm SERVER_APP_CODE y SERVER_APP_KEYen los campos "Env". Haga click en "Deploy for Free".
  3. Abra el proyecto en Android Studio.
  4. Reemplace las constantes CLIENT_APP_CODE y CLIENT_APP_KEY en Constants.java con sus propias credenciales de gpvicomm.
  5. Reemplace la variable BACKEND_URL en el archivo Constants.java con la URL de la aplicación que Heroku le proporciona (por ejemplo," https://my-example-app.herokuapp.com ")
  6. Ejecute el proyecto.

Nota importante: si solo tiene un APP_CODE, suponga que es su SERVER_APP_CODE. Por lo tanto, debe solicitar a su contacto en el equipo de gpvicomm su CLIENT_APP_CODE.

iOS

Github Repository

Requirements

Version <= 1.4.x - iOS 9.0 or Later - Xcode 9

Version >= 1.5.x - iOS 9.0 or Later - Xcode 10

Framework Dependencies:

Accelerate AudioToolbox AVFoundation CoreGraphics CoreMedia CoreVideo Foundation MobileCoreServices OpenGLES QuartzCore Security UIKit CommonCrypto (Just for version 1.4)

Project Configuration - ObjC in other linker flags in target - lc++ in target other linker flags - Disable Bitcode


INSTALLATION

Carthage

If you haven't already, install the latest version of Carthage

Add this to the Cartfile:

git "https://github.com/gpvicomm/gpvicomm-ios"

For Beta Versions:

git "https://github.com/agpvicomm/gpvicomm-ios" "master"

ObjC configuration

Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES

In Build Phases -> Embed Frameworks Uncheck "Copy Only When Installing"

Manual Installation(Recommended)

SDK is a dynamic framework (More Info) so you have to build each version for the desire target (simulator and device). To make the integration easy, you can follow these instructions in order to have just one Universal .framework file.

  1. Build the SDK and create .framework files

This will create a /build folder where there are all the necesary .framework (simulator, iphoneos and universal)

  • With Target PaymentSDK selected, build the project for any iOS Simulator.
  • With Target PaymentSDK selected, build the project for a physical device.

After

  • With the Target PaymentSDK-Universal, build the project for any iOS device.
  • Inside the group Products -> PaymentSDK.framework -> Show in finder
  • Inside the the directory of PaymentSDK.framework, CMD+up
  • You can see three groups, inside the group Release-iosuniversal, you'll find the PaymentSDK.framework

  • Or if you prefer you can download pre-compilled .framework files from Releases

  1. Drag the PaymentSDK.framework To your project and check "Copy Files if needed".

In Target->General : Add PaymentSDK.framework to Frameworks, Libraries, and Embedded Content

In Target->Build Settings : Validate Workspace should be YES

  1. Update the Build Settings with

Set ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = YES

In Build Phases -> Embed Frameworks Uncheck "Copy Only When Installing"

  1. If you use the Universal version and you want to upload to the appstore. Add Run Script Phase: Target->Build Phases -> + ->New Run Script Phase. And paste the following. Make sure that this build phase is added after Embed Frameworks phase.
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/PaymentSDK.framework/install_dynamic.sh"

Usage

Importing Swift

import PaymentSDK

Setting up your app inside AppDelegate->didFinishLaunchingWithOptions. You should use the Payment Client Credentials (Just ADD enabled)

PaymentSDKClient.setEnvironment("AbiColApp", secretKey: "2PmoFfjZJzjKTnuSYCFySMfHlOIBz7", testMode: true)

Types of implementation

There are 3 ways to present the Add Card Form:

  1. As a Widget in a Custom View
  2. As a Viewcontroller Pushed to your UINavigationController
  3. As a ViewController presented in Modal

The AddCard Form includes: Card io scan, and card validation.

Show AddCard Widget

In order to create a widget you should create a PaymentAddNativeController from the PaymentSDKClient. Then add it to the UIView that will be the container of the Payment Form. The min height should be 300 px, and whole screen as width (270px without payment logo)

Note: When you are using the Payment Form as Widget. The Client custom ViewController will be responsible for the layout and synchronization (aka Spinner or loading)

The widget can scan with your phones camera the credit card data using card.io.

let paymentAddVC = self.addPaymentWidget(toView: self.addView, delegate: nil, uid:UserModel.uid, email:UserModel.email)

Objc



[self addPaymentWidgetToView:self. addView delegate:self uid:@"myuid" email:@"myemail"];

Retrive the valid credit card from the PaymentAddNativeController (Widget):

if let validCard = paymentAddVC.getValidCard() // CHECK IF THE CARD IS VALID, IF THERE IS A VALIDATION ERROR NIL VALUE WILL BE RETURNED
{
sender?.isEnabled = false
PaymentSDKClient.createToken(validCard, uid: UserModel.uid, email: UserModel.email, callback: { (error, cardAdded) in

if cardAdded != nil // handle the card status
{
}
else if error != nil //handle the error
{
}
})
}

Objc

PaymentCard *validCard = [self.paymentAddVC getValidCard];
if (validCard != nil) // Check if it is avalid card
{

[PaymentSDKClient add:validCard uid:USERMODEL_UID email:USERMODEL_EMAIL callback:^(PaymentSDKError *error, PaymentCard *cardAdded) {
[sender setEnabled:YES];
if(cardAdded != nil) // handle the card status
{

}
else  //handle the error
{

}
}];
}

Pushed to your NavigationController

self.navigationController?.pushPaymentViewController(delegate: self, uid: UserModel.uid, email: UserModel.email)

Objc



[self.navigationController pushPaymentViewControllerWithDelegate:self uid:@"myuid" email:@"mymail@mail.com"]`;

Present as Modal

self.presentPaymentViewController(delegate: self, uid: "myuid", email: "myemail@email.com")

Objc


[self presentPaymentViewControllerWithDelegate:self uid:@"myuid" email:@"myemail@email.com"];

PaymentCardAddedDelegate Protocol

If you present the Form as a viewcontroller (push and modal) you must implement the PaymentCardAddedDelegate Protocol in order to handle the states or actions inside the Viewcontroller. If you are using Widget implementation you can handle the actions as described above.

protocol PaymentCardAddedDelegate
{
func cardAdded(_ error:PaymentSDKError?, _ cardAdded:PaymentCard?)
func viewClosed()
}

func cardAdded(_ error:PaymentSDKError?, _ cardAdded:PaymentCard?) is called whenever there is an error or a card is added.

func viewClosed() Whenever the modal is closed

Scan Card

If you want to do the scan yourself, using card.io

PaymentSDKClient.scanCard(self) { (closed, number, expiry, cvv, card) in
if !closed // user did not closed the scan card dialog
{
if card != nil  // paymentcard object to handle the data
{

}
})

-ObjC

[PaymentSDKClient scanCard:self callback:^(BOOL userClosed, NSString *cardNumber, NSString *expiryDate, NSString *cvv, PaymentCard *card) {

if (!userClosed) //user did not close the scan card dialog
{
if (card != nil) // Handle card
{

}

}
}];

Add Card (Only PCI Integrations)

For custom form integrations Fields required + cardNumber: card number as a string without any separators, e.g. 4111111111111111. + cardHolder: cardholder name. + expuryMonth: integer representing the card's expiration month, 01-12. + expiryYear: integer representing the card's expiration year, e.g. 2020. + cvc: card security code as a string, e.g. '123'.

let card = PaymentCard.createCard(cardHolder:"Gustavo Sotelo", cardNumber:"4111111111111111", expiryMonth:10, expiryYear:2020, cvc:"123")

if card != nil  // A valid card was created
{
PaymentSDKClient.add(card, uid: "69123", email: "dev@gpvicomm.mx", callback: { (error, cardAdded) in

if cardAdded != nil
{
//the request was succesfully sent, you should check the cardAdded status
}

})
}
else
{
//handle invalid card
}

ObjC

PaymentCard *validCard = [PaymentCard createCardWithCardHolder:@"Gustavo Sotelo" cardNumber:@"4111111111111111" expiryMonth:10 expiryYear:2020 cvc:@"123"];
if (validCard != nil) // Check if it is avalid card
{

[PaymentSDKClient add:validCard uid:USERMODEL_UID email:USERMODEL_EMAIL callback:^(PaymentSDKError *error, PaymentCard *cardAdded) {
[sender setEnabled:YES];
if(cardAdded != nil) // handle the card status
{

}
else  //handle the error
{

}
}];
}

Secure Session Id

Debit actions should be implemented in your own backend. For security reasons we provide a secure session id generation, for kount fraud systems. This will collect the device information in background

let sessionId = PaymentSDKClient.getSecureSessionId()

Objc

NSString *sessionId = [PaymentSDKClient getSecureSessionId];

Utils

Get Card Assets

let card = PaymentCard.createCard(cardHolder:"Gustavo Sotelo", cardNumber:"4111111111111111", expiryMonth:10, expiryYear:2020, cvc:"123")
if card != nil  // A valid card was created
{
let image = card.getCardTypeAsset()

}

Get Card Type (Just Amex, Mastercard, Visa, Diners)

let card = PaymentCard.createCard(cardHolder:"Gustavo Sotelo", cardNumber:"4111111111111111", expiryMonth:10, expiryYear:2020, cvc:"123")
if card != nil  // A valid card was created
{
switch(card.cardType)
{
case .amex:
case .masterCard:
case .visa:
case .diners:
default:
//not supported action
}

}

Customize Look & Feel

You can customize widget colors sample

paymentAddVC.baseFontColor = .white
paymentAddVC.baseColor = .green
paymentAddVC.backgroundColor = .white
paymentAddVC.showLogo = false
paymentAddVC.baseFont = UIFont(name: "Your Font", size: 12) ?? UIFont.systemFont(ofSize: 12)

The customizable elements of the form are the following:

  • baseFontColor : The color of the font of the fields
  • baseColor: Color of the lines and titles of the fields
  • backgroundColor: Background color of the widget
  • showLogo: Enable or disable Payment Logo
  • baseFont: Font of the entire form
  • nameTitle: String for the custom placeholder for the Name Field
  • cardTitle: String for the custom placeholder for the Card Field
  • invalidCardTitle String for the error message when a card number is invalid

Building and Running the PaymentSwift

Before you can run the PaymentStore application, you need to provide it with your APP_CODE, APP_SECRET_KEY and a sample backend.

  1. If you haven't already and APP_CODE and APP_SECRET_KEY, please ask your contact on Payment Team for it.
  2. Replace the PAYMENT_APP_CODE and PAYMENT_APP_SECRET_KEY in your AppDelegate as shown in Usage section
  3. Head to https://github.com/gpvicomm/example-java-backend and click "Deploy to Heroku" (you may have to sign up for a Heroku account as part of this process). Provide your Payment Server Credentials APP_CODE and APP_SECRET_KEY fields under 'Env'. Click "Deploy for Free".
  4. Replace the BACKEND_URL variable in the MyBackendLib.swift (inside the variable myBackendUrl) with the app URL Heroku provides you with (e.g. "https://my-example-app.herokuapp.com")
  5. Replace the variables (uid and email) in UserModel.swift with your own user id reference


La forma más fácil de integrar Global Payments ViComm es a través de Checkout, una herramienta integrada que se encarga de crear un formulario HTML, validar la entrada del usuario y proteger los datos de la tarjeta de sus clientes. Al usar Checkout, la información confidencial de la tarjeta de crédito se envía directamente a Global Payments ViComm y no toca tu servidor. Global Payments ViComm devuelve a tu sitio un objeto de transacción con el resultado de la operación.

Para ver el Checkout en acción, haz clic en el botón de arriba y completa el formulario con:

  • Cualquier dirección de correo electrónico aleatoria y sintácticamente válida (cuanto más aleatoria, mejor)
  • Cualquier número de teléfono, como 777777777
  • Nombre de cualquier titular de tarjeta
  • Uno de los números de tarjeta de prueba, como 4111111111111111
  • Cualquier código CVC de tres dígitos
  • Cualquier fecha de vencimiento a futuro

Ver ejemplo de trabajo

Integración

La integración personalizada requiere habilidades sólidas de JavaScript.

Cuando se carga su página, debe crear un objeto controlador utilizando paymentCheckout.modal(). Luego puede llamar la función open() en el controlador en respuesta a cualquier evento. Si necesita abortar el proceso de pago, por ejemplo, cuando la navegación ocurre en una aplicación de una sola página, llame la función close() en el controlador.

<script src="https://cdn.gpvicomm.com/ccapi/sdk/payment_checkout_stable.min.js" charset="UTF-8"></script>

<button class="js-payment-checkout">Compra</button>


<script>    
  let paymentCheckout = new PaymentCheckout.modal({
      client_app_code: 'PAYMENT_CLIENT_APP_CODE', // Application Code de las credenciales CLIENT
      client_app_key: 'PAYMENT_CLIENT_APP_KEY', // Application Key de las credenciales CLIENT
      locale: 'es', // Idioma preferido del usuario (es, en, pt). El inglés se usará por defecto
      env_mode: 'stg', // `prod`, `stg`, `local` para cambiar de ambiente. Por defecto es `stg`
      onOpen: function() {
          console.log('Modal abierto');
      },
      onClose: function() {
          console.log('Modal cerrado');
      },
      onResponse: function(response) { // Funcionalidad a invocar cuando se completa el proceso de pago

          /*
            En caso de error, esta será la respuesta.
            response = {
              "error": {
                "type": "Server Error",
                "help": "Try Again Later",
                "description": "Sorry, there was a problem loading Checkout."
              }
            }

            Cual el usuario completa el flujo en el Checkout, esta será la respuesta
            response = {  
              "transaction":{  
                  "status":"success", // Estado de la transacción
                  "id":"PR-81011", // Id de la transacción de lado de la pasarela
                  "status_detail":3 // Para más detalles de los detalles de estado: https://developers.gpvicomm.com/api/#detalle-de-los-estados
              }
            }
          */
          console.log('Respuesta de modal');
          document.getElementById('response').innerHTML = JSON.stringify(response);            
      }
  });

  let btnOpenCheckout = document.querySelector('.js-payment-checkout');
  btnOpenCheckout.addEventListener('click', function(){
    // Open Checkout with further options:
    paymentCheckout.open({
      user_id: '1234',
      user_email: 'dev@gpvicomm.com', // Opcional        
      user_phone: '7777777777', // Opcional
      order_description: '1 Green Salad',
      order_amount: 1500,
      order_vat: 0,
      order_reference: '#234323411',
      //order_installments_type: 2, // Opcional: 0 para permitir cuotas, -1 en caso contrario.
      //conf_exclusive_types: 'ak,ex', // Opcional: Tipos de tarjeta permitidos para esta operación. Opciones: https://developers.gpvicomm.com/api/#metodos-de-pago-tarjetas-marcas-de-tarjetas
      //conf_invalid_card_type_message: 'Tarjeta invalida para esta operación' // Opcional: Define un mensaje personalizado para mostrar para los tipos de tarjeta no válidos.
    });
  });

  // Cerrar el Checkout en la navegación de la página:
  window.addEventListener('popstate', function() {
    paymentCheckout.close();
  });
</script>

Opciones de configuración

Cambia la apariencia y el comportamiento de Checkout con las siguientes opciones de configuración.

PaymentCheckout.modal

Parámetro Requerido Descripción
client_app_code Application Code de las credenciales CLIENT
client_app_key Application KEY de las credenciales CLIENT
env_mode prod, stg, local para cambiar de ambiente. Por defecto es stg
locale no Idioma preferido del usuario (es, en, pt). El inglés se usará por defecto
onOpen no function() Callback a invocar cuando el Checkout es abierto
onClose no function() Callback a invocar cuando el Checkout es cerrado
onResponse function(responseObject) Callback a invocar cuando el proceso del Checkout es completado

Objeto de respuesta

Cuando el usuario complete todo el flujo en el proceso de pago, esta será la respuesta.

{  
  "transaction": {  
    "status": "success", // Estado de la transacción
    "id": "PR-81011", // Id de la transacción de lado de la pasarela
    "status_detail": 3 // Para más detalles de los detalles de estado: https://developers.gpvicomm.com/api/#detalle-de-los-estados
  }
}

En caso de error, esta será la respuesta.

{
  "error": {
    "type": "Server Error",
    "help": "Try Again Later",
    "description": "Sorry, there was a problem loading Checkout."
  }
}

PaymentCheckout.open

Parámetro Requerido Descripción
user_id Identificador del cliente Este es el identificador que usa dentro de su aplicación.
user_email no Si ya conoces la dirección de correo electrónico de tu usuario, puedes proporcionarla al Checkout para que se complete previamente.
user_phone no Si ya conoces el teléfono de tu usuario, puedes proporcionarlo al Checkout para que se complete previamente.
order_description Una descripción del producto o servicio que se compra.
order_amount La cantidad que se muestra al usuario. Formato: decimal con dos dígitos de fracción.
order_vat Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order_reference Referencia de pedido de comerciante. Identificarás esta compra utilizando esta referencia.
order_installments_type no -1 para no permitir cuotas, 2 cuotas con intereses, 3 cuotas sin intereses (MSI).
conf_exclusive_types no Tipos de tarjeta permitidos para esta operación. Opciones: https://developers.gpvicomm.com/api/#metodos-de-pago-tarjetas-marcas-de-tarjetas
conf_invalid_card_type_message no Define un mensaje personalizado para mostrar para los tipos de tarjeta no válidos.

Requisitos HTTPS

Todos los envíos de información de pago mediante Checkout se realizan a través de una conexión HTTPS segura. Sin embargo, para protegerse de ciertas formas de ataques man-in-the-middle, también debe servir la página que contiene el formulario de pago a través de HTTPS. En resumen, la dirección de la página que contiene Checkout debe comenzar con https: // en lugar de solo http: //.

Navegadores compatibles

Checkout se esfuerza por admitir todas las versiones recientes de los principales navegadores. Por razones de seguridad y para proporcionar la mejor experiencia a la mayoría de los clientes, no admitimos navegadores que ya no reciben actualizaciones de seguridad y representan una pequeña minoría de tráfico.

Evitar que se bloquee Checkout

Puede evitar que se bloquee la ventana emergente de Checkout llamando a paymentCheckout.open cuando el usuario hace clic en un elemento de la página. No llames a paymentCheckout.open dentro de un callback. Este diseño indica al navegador que el usuario está solicitando explícitamente la ventana emergente. De lo contrario, los dispositivos móviles y algunas versiones de Internet Explorer bloquearán la ventana emergente y evitarán que el uso adecuado por el cliente.

Qué es 3DS2 y cómo funciona

3D Secure 2 es la nueva generación de tecnología de autenticación introducida por EMVCo, una compañía  de American Express, Discover, JCB, MasterCard, UnionPay y Visa  en propiedad colectiva. Esta tecnología permite a los titulares de tarjetas autenticarse con el emisor de su tarjeta mientras realizan compras en línea sin tarjeta presente.

La nueva especificación incluye:

  • Admite compras de manera nativa  en  aplicaciones móviles  y otros dispositivos
  • Mejora la experiencia del consumidor al permitir decisiones inteligentes basadas en el riesgo que fomentan la autenticación del consumidor sin fricción
  • Ofrece características de seguridad líderes en la industria.
  • Especifica el uso de múltiples opciones para la autenticación progresiva, incluidas las contraseñas de un solo uso (OTP), así como los datos biométricos a través de la autenticación fuera de banda
  • Mejora la funcionalidad que permite a los comercios integrar el proceso de autenticación en sus experiencias de pago, tanto para aplicaciones móviles como implementaciones basadas en navegador
  • Ofrece mejoras de rendimiento para el procesamiento de mensajes de extremo a extremo
  • Agrega una categoría de mensaje sin pago para proporcionar detalles de verificación del titular de la tarjeta, para admitir diversas actividades que no conllevan pagos, como agregar una tarjeta  a una billetera digital.

A diferencia de la versión anterior donde los compradores son redirigidos a otro sitio, en 3D Secure 2 el emisor de la tarjeta realiza la autenticación dentro de su aplicación o formulario de pago. El banco emisor puede verificar la identidad del comprador utilizando enfoques de autenticación pasiva, biométrica y de dos factores.

Una transacción puede pasar por un flujo de autenticación pasiva sin fricción o un flujo de autenticación con  desafío donde el emisor requiere una mayor interacción con un comprador.

Flujo sin fricción

En un flujo sin fricción, el adquirente,  el emisor y la franquicia de la tarjeta intercambian toda la información necesaria en segundo plano, a través de una autenticación pasiva, utilizando la huella digital del dispositivo device fingerprint del comprador.

En su integración, necesitará obtener la huella digital del dispositivo 3D Secure 2 y, sí el emisor lo valida y lo aprueba, la transacción será completada  sin más interacción por parte del comprador. (Pasos 1-4 en la siguiente figura).

Flujo con desafío

En el flujo con desafío, el emisor requiere interacción adicional del comprador para la verificación, ya sea a través de autenticación de dos factores, bromearía o métodos similares.

En 3DS 2.0, el resultado del desafío se comunica a través del DS. (Paso 6 en la figura a continuación) Por lo tanto, el comercio  es informado sobre los resultados de autenticación a través de un canal separado, que es más seguro.

Integración de solo autenticación

Admitimos la autenticación de 3DS 2 para transacciones web y dentro de su integración de pagos en línea.

Es posible usar solo la autenticación.

En el caso de dispositivos móviles, tenemos SDK (Android e iOS) certificados por EMVCo, ambos SDK realizarán el flujo de desafío si es necesario:

Para más información vea la Documentación de API para este caso..

Cobro con autenticación 3DS2

En este tipo de integración, realizaremos la autenticación e inmediatamente después se procede con el cobro.

El cobro puede llevarse a cabo a través de los distintos servicios que proveemos, dependiendo del país y del tipo de integración. Las posibilidades son: Agregar una Tarjeta, Cobro con Token, Cobro con Tarjeta Crédito y Autorizar.

Para el flujo de Agregar una Tarjeta, la autenticación será llevada a cabo antes de añadir la tarjeta en nuestra bóveda.

Para la integración SDKs en Android o iOS, el flujo es el siguiente:

Para una integración Web, el flujo es el siguiente:

El flujo de autenticación 3DS 2 comienza con una solicitud de cobro. Envíe una solicitud de cobro desde su servidor con los objetos requeridos para 3D Secure2.

Maneje la transacción de acuerdo al Status and Status detail que haya obtenido. Por ejemplo, si recibe un Status Pending y un Status detail 35 proceda a renderizar  y después solicite la verificación (endpoint Verificar).

Las posibles respuestas de la verificación son:

  • Success: Esto significa que la autenticación fue sin fricción y el cobro ha sido autorizado.
  • Pending: El emisor requiere interacción adicional con el comprador. Prosiga con el flujo de desafío.
  • Failure:  La autenticación fue fallida o algo salió mal. En la respuesta se incluye el motivo de rechazo.

 

 

VTEX

Tenemos implementada la solución eCommerce VTEX + ViComm

Cómo configurar Global Payments ViComm

Para estas instrucciones se dará por hecho que el encargado de VTEX por parte del comercio, conoce bien el panel de administración.

Se deben de seguir los siguientes pasos:

  1. Entrar a la configuración del apartado de pagos.
  2. Seleccionar la pestaña de Gateway Affiliations y agregar una pulsando sobre el botón de más.

  3. Dentro de lista ordenada alfabéticamente de OTHERS, se debe buscar el conector con nombre ViComm.
  4. Una vez seleccionado el conector, se debe configurar, donde Application Key es el Application Code proporcionado por Global Payments ViComm y el Application Token es el Application Key proporcionado por Global Payments ViComm. Se puede especificar ahí mismo, el ambiente al cual se desea apuntar, quedando Live/Production para ambiente de producción y Test para el ambiente de staging. Quedando de la siguiente manera:
  5. Una vez configurada la afiliación. Esta se puede asignar para el medio de pago que seleccione el administrador.

Cómo configurar Global Payments ViComm para una franquicia ya establecida

Tomar en cuenta que al asignar la afiliación a una franquicia ya establecida, TODAS las transacciones con esa franquicia se procesarán con Global Payments ViComm.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Payment Conditions, agregar una nueva condición dando clic al botón de más.

  3. Seleccionar la franquicia que se desea procesar con Global Payments ViComm

  4. Una vez seleccionada la franquicia, se debe asignar un nombre a la condición y seleccionar la afiliación de Global Payments ViComm.
  5. Sobre seleccionar pago completo o pago en cuotas, esto queda a decisión y conocimiento del administrador VTEX del comercio.

Cómo configurar Global Payments ViComm para Cash

Tomar en cuenta que al asignar la afiliación a una franquicia ya establecida, TODAS las transacciones con esa franquicia se procesarán con ViComm.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Payment Conditions, agregar una nueva condición dando clic al botón de más.

  3. Dentro de OTHER existe la opción Cash, seleccionar esta:
  4. Seleccionar la afiliación configurada de Global Payments ViComm.
  5. Sobre asignar condiciones especiales para el pago queda a decisión y conocimiento del administrador VTEX del comercio.

Cómo configurar Global Payments ViComm para LinkToPay

LinkToPay es un medio de pago que no aparece dentro de las opciones existentes de VTEX, por esto es necesario crearlo a través de un Promissories.

  1. Entrar a la configuración del apartado de pagos.

  2. En la pestaña de Custom Payments, agregar una nueva condición dando clic a una casilla de Config.

  3. Dentro de la configuración, se debe asignar el nombre LinkToPay (este nombre es completamente requerido ya que se usa para identificar el medio de pago por parte del conector). En tiempo de expiración, es requerido el 2, ya que de lado de ViComm se dan dos días para que el cliente final pueda pagar. Los datos deben quedar como se muestra en la imagen.

  4. Seleccionar la afiliación configurada de Global Payments ViComm.
  5. Sobre asignar condiciones especiales para el pago queda a decisión y conocimiento del administrador VTEX del comercio.

Magento 2

Si ya tiene su plataforma de comercio electrónico en Magento 2, tenemos el módulo para usar nuestras soluciones de pago.

Cómo instalar el módulo Global Payments ViComm para Magento 2:

Este modulo permite a los usuarios de magento procesar pagos de manera fácil y rápida con GpVicomm.

Descarga e Instalación

1. Ejecuta el siguiente comando para instalar nuestro paquete :

Para instalar la ultima versión. composer require vicomm/payment-gateway

Para instalar una version específica. composer require vicomm/payment-gateway:2.4.0

Una vez que finalice la instalación, Continúe con el siguiente comando en su terminal.

2. Actualizar dependencias:

php bin/magento setup:di:compile

3. Actualizar modulos de registro:

php bin/magento setup:upgrade

Opcional.- Este comando es opcional para ambientes de producción:

php bin/magento setup:static-content:deploy

Ahora Debería ver los settings de GpViComm en Stores > Configuration > Sales > Payment Methods en el Dashboard Admin de Magento.

Mantenimiento y Actualización

Si necesita actualizar la última versión del plugin use: composer update vicomm/payment-gateway o si requiere un versión especifica composer require vicomm/payment-gateway:2.4.0 .

Notificaciones Webhook y Actualizacion de Transacciones

Cada que una transacción cambie su estado, GpViComm enviara una notificación HTTP POST a su webhook.

La URL que se debe usar para actualizar via webhook es:

https://magentodomain.com/rest/V2/webhook/vicomm

Esta URL estara configurada en GpViComm.

La configuración del módulo en el panel de administración se ve así:

WooCommerce

Global Payments ViComm Gateway Plugin for WooCommerce

Este es un plugin de Wordpress preparado para funcionar como pasarela de pago para otro plugin llamado WooCommerce.

1.- Prerrequisitos

1.1.- XAMPP, LAMPP, MAMPP, Bitnami o cualquier entorno de desarrollo PHP

  • XAMPP: https://www.apachefriends.org/download.html
  • LAMPP: https://www.apachefriends.org/download.html
  • MAMPP: https://www.mamp.info/en/mac/
  • Bitnami: https://bitnami.com/stack/wordpress

1.2.- Wordpress

Si ya instaló la opción Bitnami, este paso se puede omitir.

La documentación necesaria para instalar y configurar Wordpress se encuentra en el siguiente enlace:

https://wordpress.org/support/article/how-to-install-wordpress/

Se deben cumplir todos los requisitos mínimos (PHP y MySQL) para que el plugin desarrollado funcione correctamente.

1.3.- WooCommerce

La documentación necesaria para instalar WooCommerce se encuentra en el siguiente enlace:

https://docs.woocommerce.com/document/installing-uninstalling-woocommerce/

Allí también encontrará la información necesaria para solucionar problemas relacionados con la instalación.

1.4.- WooCommerce Admin

La documentación necesaria para instalar WooCommerce se encuentra en el siguiente enlace:

https://wordpress.org/plugins/woocommerce-admin/

Allí también encontrará la información necesaria para solucionar problemas relacionados con la instalación.

2.- Repositorio de Git

Puede descargar la versión estable actual desde: https://github.com/gpvicomm/gp-woocommerce-plugin/releases

3.- Instalación del Plugin

El desarrollo funciona como un complemento de Wordpress que se conecta a otro complemento de Wordpress, WooCommerce.

Entonces, cuando está instalado y activado, se utilizan los hooks y actions de WooCommerce y Wordpress.

3.1 Instalación y Activación a Través del Wordpress Admin

Cuando tengamos el proyecto comprimido en formato .zip, procedemos a la instalación a través de Wordpress Admin.

  1. El primer paso será iniciar sesión en Wordpress Admin como administrador.

  2. Estando en la pantalla principal del administrador hacemos clic en la pestaña Plugins.

  3. Dentro de la pantalla de Plugins hacemos clic en Agregar nuevo.

  4. Dentro de la pantalla Agregar Plugins, hacemos clic en Cargar Plugin.

  5. Se mostrará la opción de cargar nuestro plugin en formato .zip. Lo subimos y hacemos clic en el botón Instalar ahora.

  6. Seremos redirigidos a la pantalla de instalación del plugin. Esperamos que el mensaje "Plugin se ha instalado correctamente" y hacemos clic en el botón Activar plugin.

7.Seremos redirigidos a la pantalla de Plugins dónde veremos nuestro plugin instalado y activado.

3.2.- Idiomas

El idioma del plugin se selecciona dinámicamente de acuerdo con el idioma configurado en Wordpress. Los idiomas disponibles son: - Español - Español MX - Inglés (Default)

4. Activación y Configuración del Complemento en WooCommerce

Luego de haber instalado nuestro plugin en Wordpress debemos proceder a configurarlo en el administrador de WooCommerce.

Esto se encuentra en la pestaña WooCommerce del administrador principal de WordPress. Luego hacemos clic en la opción Configuración y luego en la pestaña Pagos.

4.1 Payment Gateway Activation

Para activar nuestra pasarela de pago dentro de WooCommerce debemos estar dentro de WooCommerce -> Configuración -> Pagos y veremos nuestro complemento detectado e instalado.

Para habilitarlo debemos activar el botón Habilitado. Esta habilitación es diferente a la de Wordpress que hicimos anteriormente.

4.2 Configuración de la Pasarela en el WooCommerce Admin

Al habilitar nuestro plugin en el administrador de WooCommerce, tendremos algunas opciones para configurar. Para ello hacemos clic en el botón Gestionar que aparecerá al costado de nuestro plugin.

Las opciones a configurar son las siguientes:

Entorno de pruebas: Cuando está habilitado, el plugin apuntará al servidor de pruebas de Global Payments ViComm.

Habilitar LinkToPay: Si se selecciona, LinkToPay (transferencia bancaria, efectivo) se puede utilizar para pagar.

Título: Esta opción configura el texto que verá el cliente en la ventana de pago junto al logo de Global Payments ViComm.

Mensaje del cliente: Esta opción configura el mensaje que verá el cliente en la ventana de pago cuando seleccione Global Payments ViComm como método de pago.

Idioma de pago: Esta opción selecciona el idioma que se mostrará en la ventana de pago. Las opciones disponibles son español, portugués e inglés (por defecto).

Tipo de cuotas: Seleccione el tipo de cuotas que se habilitarán en la pantalla de pago (Solo en pago con tarjeta).

App Code Client: Identificador único en Global Payments ViComm.

App Key Client: Clave utilizada para cifrar la comunicación con Global Payments ViComm.

App Code Server: Identificador único en el servidor Global Payments ViComm.

App Key Server: Clave utilizada para la comunicación con el servidor Global Payments ViComm.

5.- Seleccionar el Plugin en el Checkout de la Tienda

Cuando tengamos nuestro plugin activado y configurado en WooCommerce, lo veremos disponible para ser seleccionado por los clientes en la página de Checkout de nuestra tienda.

Simplemente selecciónelo, complete los Detalles de facturación y haga clic en el botón Realizar pedido.

Al hacer clic llegaremos a la ventana Order-Pay o Pay For Order en la que veremos un resumen de nuestro pedido. Se mostrará el botón Pagar con Tarjeta y/o Pagar con Efectivo/Transferencia Bancaria, que abrirá el proceso de pago.

6.Proceso para Hacer un Reembolso

El proceso de reembolso comenzará en la ventana principal de administración de Wordpress.

Seleccionamos la pestaña WooCommerce y hacemos clic en la opción Pedidos.

Seleccionamos el pedido que queremos reembolsar y se abrirá la ventana Editar pedido.

En el detalle del artículo encontraremos el botón Reembolso, hacemos clic y se mostrarán las opciones de reembolso.

Tecleamos la cantidad a reembolsar y hacemos clic en el botón Reembolso vía Global Payments ViComm. El estado dentro de WooCommerce cambiará y también lo hará el estado en la puerta de enlace.

7. Configuración del Webhook

El complemento incluye la funcionalidad de un webhook para recibir las actualizaciones de transacciones que se realizan. Este webhook recibe notificaciones de transacciones y las actualiza en el administrador y la base de datos de WooCommerce.

Para configurarlo, el comercio debe proporcionar a su asesor comercial de Global Payments ViComm la dirección donde está instalado el webhook, la url estará en el siguiente formato: https://{{URL-COMMERCE}}/wp-json/gpvicomm/webhook/v1/params.

Prestashop

Global Payments ViComm Plugin para Prestashop

1.- Prerrequisitos

1.1.- XAMPP, LAMPP, MAMPP, Bitnami o cualquier entorno de desarrollo PHP

  • XAMPP: https://www.apachefriends.org/download.html
  • LAMPP: https://www.apachefriends.org/download.html
  • MAMPP: https://www.mamp.info/en/mac/
  • Bitnami: https://bitnami.com/stack/prestashop

1.2.- Prestashop

Si ya instaló la opción Bitnami, estos pasos se pueden omitir.

Prestashop es una solución de comercio electrónico desarrollada en PHP. La última versión estable es la 1.7.X. - Descarga: https://www.prestashop.com/en/download - Guia de Instalación: https://www.prestashop.com/es/blog/como-instalar-prestashop-la-guia-completa

2.- Git Repository

Puede descargar la versión estable actual desde: https://github.com/gpvicomm/pg_prestashop_plugin/releases

3.- Instalación del Plugin en Prestashop

  1. Primero, necesitamos descargar la versión estable actual del Plugin de Global Payments ViComm del paso anterior.

  2. Prestashop necesita que la carpeta se llame pg_prestashop_plugin, por lo que necesitamos extraer la carpeta pg_prestashop_plugin_1.0.0 del archivo zip y cambiarle el nombre a pg_prestashop_plugin.

  3. Con nuestra carpeta correctamente nombrada, comprimimos la carpeta nuevamente para tener pg_prestashop_plugin.zip

  4. Necesitamos iniciar sesión en nuestra página de administración de Prestashop.

  5. Ahora hacemos clic en Mejoras -> Módulos -> Administrador de módulos

  6. En el administrador de módulos hacemos clic en el botón Subir un módulo

  7. Hacemos clic en seleccionar archivo o podemos Arrastrar la carpeta del Plugin de Global Payments ViComm en formato .zip o .rar.

  8. Esperaremos hasta que la pantalla Instalando módulo cambie a Módulo instalado!.

  9. Ahora podemos hacer clic en el botón Configurar que se muestra en la pantalla o en el botón Configurar que se muestra en la sección Pago en el Administrador de módulos.

  10. Dentro de las Configuraciones de la pasarela de pago necesitamos configurar o las credenciales de CLIENT/SERVER proporcionadas por Global Payments ViComm, podemos seleccionar el Idioma de pago que se mostrará al usuario, también debemos seleccionar un Entorno, de forma predeterminada, Pruebas (Staging) está configurado.

  11. ¡Felicitaciones! Ahora tenemos el Plugin de Global Payments ViComm configurado correctamente.

4.- Considerations and Comments

4.1.- Reembolsos

  • La versión del plugin 2.0.0 no soporta Reembolsos parciales de Prestashop. Sin embargo, el complemento admite Reembolsos estándar de Prestashop.
  • El Reembolso estándar se puede interpretar como un reembolso parcial por parte de Global Payments ViComm, el éxito de la operación depende de que la red de pago configurada acepte reembolsos parciales.

4.2. Webhook

El Plugin de Global Payments ViComm tiene un webhook interno para mantener actualizados los estados de las transacciones entre Prestashop y Global Payments ViComm. Debe seguir los siguientes pasos para configurar el webhook:

  1. Inicie sesión en el Back-office de Prestashop.

  2. Vaya a Parámetros avanzados -> Opciones del menú Servicios web para abrir la página Servicios web.

  3. Redirigirá a la página de Servicios Web que tiene la lista de servicios Web disponibles y el formulario de configuración para configurar el servicio.

  4. Necesitamos habilitar el campo llamado Habilitar el servicio web Prestashop.

  5. Haga clic en el botón Guardar.

  6. Haga clic en el botón Agregar nueva clave de servicio web para agregar una nueva clave de servicio web para acceder solo a ciertos recursos de la tienda Prestashop.

  7. Necesitamos configurar la Clave, esta es una clave única. Puede ingresarlo manualmente o hacer clic en el botón Generar para generar una clave aleatoria para el servicio web.

  8. También configuramos la Descripción de la clave, puede proporcionar la descripción con respecto a la clave para una mejor comprensión.

  9. Estableceremos Estado en Habilitar para proporcionar una concesión para acceder a los datos utilizando la clave.

  10. Finalmente, necesitamos configurar el campo Permiso para proporcionar el permiso para acceder a los datos usando la clave determinada. Aquí tenemos que buscar el recurso llamado gpvicommwebhook y seleccionar la casilla de verificación Agregar (POST).

  11. El webhook está ubicado en https://{mystoreurl}/api/gpvicommwebhook?ws_key=KEY_GENERATED_ON_STEP_6.

  12. Debe proporcionar esta URL a su agente de Global Payments ViComm.