Tarjeta de Crédito

Integración por webservices

La integración a través de webservices consiste en que desde el sitio web del comercio se realiza un llamado directo a los webservices de procesamiento de Place to Pay sin tener que redireccionar a nuestra plataforma.

Esta integración implica que el sitio web del comercio debe tener altas medidas de seguridad, pues desde allí se hará la captura de los datos sensibles de la transacción.

¿Cómo empezar?

El método de integración avanzado o AIM contempla las operaciones básicas para el procesamiento de tarjetas no presenciales: autorización, captura, reverso, asiento y anulación. A continuación, describimos cada uno de los usos y los datos requeridos en la trama para para cada operación. La respuesta para cada una está unificada en un solo tipo de trama resultante. 

Esta integración permite minimizar el ancho de banda requerido para la comunicación, así como facilitar su implementación en cualquier lenguaje de programación capaz de establecer una comunicación por sockets a través del protocolo HTTPS.

¿Cómo funciona la implementación?

1. Se compilan los datos enviados a la plataforma, incluyendo los datos sensibles de la tarjeta (número, fecha de expiración, CVV2).

2. Se prepara la petición POST a nivel de servidor, ten en cuenta que el servicio espera los datos en codificación ISO-8859-1. Los datos a ser remitidos a Place to Pay dependerán de la operación que desea realizar.

3. Se hace el POST a Place to Pay y se espera por la respuesta. Normalmente, los tiempos de respuesta son de 2 a 3 segundos, sin embargo, dependiendo de congestión de la red u otros factores, el tiempo puede incrementarse. Verifica que el script de tu implementación espera al menos 15 o 20 segundos antes de dar un timeout.

4. Si obtuviste una respuesta de la plataforma, entonces desglósala (la respuesta se entrega como una cadena de caracteres separados por coma e identifica los datos relevantes para tu sistema, como: estado de la transacción, motivo asociado al estado, franquicia, banco emisor, autorización, recibo e identificación de la transacción en Place to Pay.

5. Si no obtuviste una respuesta válida o un timeout, consulta de la transacción para determinar el estado de la misma.

6. Presenta el resultado de la transacción y activa las otras rutas de flujo en tu sistema.

¿En qué casos es mejor usar este tipo de integración?

La integración AIM se recomienda únicamente en los casos que no sea factible que el usuario realice la transacción ingresando los datos sensibles en Place to Pay o en donde se requiere un control particular de la operación. Algunos ejemplos son:

• Cobros recurrentes desde una base de datos propietaria.
• Integración con un sistema de audiorespuesta.
• Múltiples transacciones a diferentes recaudadores con la misma información del tarjetahabiente.
• Interfaz móvil propietaria, no basada en HTML. 
• Integración con sistemas cuya entrada de los datos sensibles no la realice directamente el tarjetahabiente.

¿Qué obligaciones tengo al usar esta integración?

Ten en cuenta que al usar este tipo de integración, estás suministrando todos los datos del comprador incluyendo los datos sensibles de la tarjeta, este hecho requiere que la captura de la información sea por un mecanismo seguro que no ponga en peligro los datos del tarjeta habiente. Si la información se captura por una página web, el punto debe estar sobre protocolo seguro HTTPS, usando certificados de seguridad expedidos por una entidad acreditada

Si la captura la realiza por un Call Center, quien obtiene los datos sensibles debe ser un mecanismo de IVR (Interactive Voice Response) o audiorespuesta; esto implicaría un rompimiento en el proceso entre el proceso que realiza el operador con su CRM y el IVR quien captura los datos sensibles. Finalmente el CRM consolida los dos conjuntos de datos y los remite a Place to Pay.

Si la captura proviene de una base de datos de tarjetas previamente inscritas, asegúrate que esta información está encriptada por un mecanismo seguro de encriptación como AES o 3DES, desencripta solo en el momento en que construye la trama a ser enviada a Place to Pay. Nuestra pasarela ofrece servicios de tokenización que pueden ser usados.

Ten en cuenta que como regla general no debe almacenar el número de tarjeta, fecha de vencimiento y CVV2. Estos solo pueden tener persistencia durante la solicitud de la autorización, una vez procesada no deben ser almacenados.

Como cualquier proceso de integración, este requerirá una certificación del personal de soporte de Place to Pay para revisar temas de funcionamiento, mejores prácticas y usabilidad.

Datos para la operación

Describimos las tramas que deben ser enviadas a Place to Pay para procesar una operación, de igual forma la trama de respuesta entregada por la plataforma.

Descripción de los campos

A continuación, describimos cada uno de los campos que son usados en las diferentes tramas. Se han categorizado acorde al tipo de información que representan; la columna valor posible determina, en algunos casos, el único valor permitido para el campo:

Matriz de campos por tipo de operación

A continuación, se muestra una matriz de los campos que van en la trama por tipo de operación. Las convenciones son R (requerido), O (opcional), C (condicionado a otro campo), – (no aplica).  Cuando se especifica condicionado a otro campo, por favor ve el detalle de la descripción de campos para entender de cual depende.

Trama de respuesta

A continuación se detalla la trama de respuesta para cualquiera de las operaciones definidas por el servicio AIM. La trama de respuesta consiste en una cadena de caracteres separados por coma en el siguiente orden posicional.

Consumo del webservice de sonda

Para aquellas transacciones que presentan una falla en los tiempos de respuesta, o que no puede ser verificado el x_md5_hash, deberá consumirse un Webservice para obtener de primera mano la información de la transacción.

En los casos que la transacción tiene respuesta pendiente, la regla general es que debe consumirse el servicio cada 12 minutos para las operaciones que tengan al menos 7 minutos de antigüedad. Esto implica que debe existir un proceso automático solicitando al webservice las operaciones que llevan más de 7 minutos pendientes y que el barrido debe hacerse cada 12 minutos.

Ten presente que en el proceso de certificación revisaremos de los consumos de sonda para que concuerden con los tiempos definidos.

// generation of MD5Hash to validate the response of Place to Pay

// when use AIM to request the transaction

$hashString = md5(PLACETOPAY_MD5HASH
   . PLACETOPAY_LOGIN
   . $x_transaction_id
   . $x_amount, false);

// creation of the Authentication object

// when consume the Webservice

$auth = new stdClass();

$auth->login = PLACETOPAY_LOGIN;

$auth->seed = date('c');

$auth->tranKey = sha1($auth->seed . PLACETOPAY_TRANKEY);

using System.Text;
using System.Security.Cryptography;
using System.Globalization;

private string GetMD5(string text)
{

	MD5 md5 = System.Security.Cryptography.MD5.Create();

	byte[] inputBytes = System.Text.Encoding.ASCII.GetBytes(text);

	byte[] hash = md5.ComputeHash(inputBytes);

	StringBuilder sb = new StringBuilder();

	for (int i = 0; i < hash.Length; i++)
	{
		sb.Append(hash[i].ToString("x2"));
	}

	return sb.ToString();
}

private string GetSHA1(string text)
{

	ASCIIEncoding UE = new ASCIIEncoding();

	byte[] hashValue;

	byte[] message = UE.GetBytes(text);

	SHA1 hashString = new SHA1CryptoServiceProvider();

	string hex = "";

	hashValue = hashString.ComputeHash(message);

	foreach (byte x in hashValue)
	{
		hex += String.Format("{0:x2}", x);
	}

	return hex;
}

// generation of MD5Hash to validate the response of Place to Pay
// when use AIM to request the transaction
string hashString = GetMD5(PLACETOPAY_MD5HASH 
						+ PLACETOPAY_LOGIN 	
						+ x_transaction_id
						+ x_amount);

// creation of the Authentication object
// when consume the Webservice
PlacetoPayWS.Authentication auth = new PlacetoPayWS.Authentication();

auth.login = PLACETOPAY_LOGIN;
auth.seed = DateTime.UtcNow.ToString("s", System.Globalization.CultureInfo.InvariantCulture);

auth.tranKey = GetSHA1(auth.seed + PLACETOPAY_TRANKEY);

import java.security.MessageDigest;
import java.util.Formatter;
import java.util.Date;
import java.text.SimpleDateFormat;

private static String byteToHex(final byte[] hash)
{

	Formatter formatter = new Formatter();

	for (byte b : hash)
	{
		formatter.format("%02x", b);
	}

	String result = formatter.toString();

	formatter.close();

	return result;
}

private static String GetHash(String algo, String text)
{

	String hash = "";

	try
	{
		MessageDigest crypt = MessageDigest.getInstance(algo);

		crypt.reset();

		crypt.update(text.getBytes("UTF-8"));

		hash = byteToHex(crypt.digest());
	}
	catch(UnsupportedEncodingException e)
	{
		e.printStackTrace();
	}

	return hash;
}

// generation of MD5Hash to validate the response of Place to Pay
// when use AIM to request the transaction
string hashString = GetHash("MD5", PLACETOPAY_MD5HASH
								+ PLACETOPAY_LOGIN
								+ x_transaction_id
								+ x_amount);

// creation of the Authentication object
// when consume the Webservice
Date now = new Date();

SimpleDateFormat isoDate = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ");

PlacetoPayWS.Authentication auth = new PlacetoPayWS.Authentication();

auth.setLogin(PLACETOPAY_LOGIN);

auth.setSeed(isoDate.format(now));

auth.setTranKey(GetHash("SHA-1", auth.getSeed() + PLACETOPAY_TRANKEY));