1. Introducción
2. Requerimientos
3. Instalación
4. Comercio de Prueba
5. Configuración
6. Operación de Autorización
7. Creando una Venta * Parámetros de envío obligatorios * Parámetros de envío opcionales * Parámetros de respuesta
   * Códigos de respuesta
8. Procesando una Venta * Parámetros de envío * Enviando la respuesta a tu servidor * Decrifrando la respuesta * Códigos de respuesta
9. Operación de Consulta de una venta
10. Parámetros de envío obligatorios
11. Parámetros de respuesta
12. Operación de Anulación de una venta
13. Parámetros de envío obligatorios
14. Parámetros de respuesta
15. Códigos de respuesta

##1. Introducción Este documento tiene como intención ser una Guía rápida parvea que el desarrollador pueda integrar rápidamente el Formulario de Pago Web de Culqi.

Para realizar una operación de autorización, se debe realizar 2 pasos:

• Crear un Venta --> se validará los datos del comercio y de la compra.
• Procesar la Venta --> se solicitará los datos de la tarjeta y se procesará con la marca correspondiente.

Adicionalmente, se podrá realizar las siguientes operaciones:

• Consultar una Venta --> obtendrás el estado de la venta y sus datos.
• Anular una Venta --> se procesará la anulación siempre y cuando la venta esté autorizada.

##2. Requerimientos

Para que la aplicación o proyecto que estes desarrollando pueda utilizar el Botón de Pago Web de Culqi, debes instalar lo siguiente:

• PHP 5.3.3 o posterior.
• Mcrypt
• CURL
• Ctype

##3. Instalación

Culqi ha desarrollado una libreria en PHP para simplificar la implementación del Botón de Pago Web en tu aplicación o proyecto. Puedes descargar la última versión de la librería de PHP e importarla a tu proyecto:

require 'culqi.php';

##4. Comercio de prueba

Para facilitarle la implementación a nuestro Entorno de Integración, hemos creado un comercio de prueba denominado "Comercio Demo", el cual considera el logotipo de Culqi, asi como los siguientes datos que deberás utilizar en los próximos pasos.

• Código de comercio: demo
• Llave del comercio: JlhLlpOB5s1aS6upiioJkmdQ0OYZ6HLS2+/o4iYO2MQ=

Te brindamos algunas tarjetas de diferentes marcas que podrás utilizar una vez que te integres mediante del Botón de Pago Web:

##5. Configuración

Para empezar debes de configurar la librería en tu proyecto e iniciar las variables con los datos del "Comercio Demo":

<?php
Culqi::$codigoComercio = "demo";
Culqi::$llaveSecreta = "JlhLlpOB5s1aS6upiioJkmdQ0OYZ6HLS2+/o4iYO2MQ=";
Culqi::$servidorBase = 'https://integ-pago.culqi.com';
?>

Los valores de las variables "llave_secreta" y "codigo_comercio" son los provistos para el "Comercio Demo". Cuando obtengas los valores de esas variables de tu comercio que debes solicitar a Culqi, solo reemplázalos. El valor de la variable "servidorBase", esta apuntando por defecto al Entorno de Integración de Culqi.

Estos son los parámetros de configuración:

##6. Operación de Autorización

###6.1 Creando una venta

Este paso es para pre-registrar y validar los datos de la venta del Comercio en la Pasarela de Pagos de Culqi, antes de solicitar los datos de la tarjeta al cliente. Si la respuesta es satisfactoria se debe proseguir con el siguiente paso, caso contrario, ustede debe revisar el código y mensaje de la respuesta que se le brinde.

Para crear una nueva venta deberá configurar la información de la misma, mediante los valores que establezca en los parámetros obligatorios.

####a. Parámetros de envío obligatorios

AN = Alfanumérico N = Numérico

####b. Parámetros de envío opcionales

N = Numérico El tiempo de la vigencia es por defecto 10 minutos. Si va a usar este campo con otro valor, contáctese con Culqi para su habilitación.

Ejemplo de código para crear la venta:

<?php
require 'culqi.php';

Culqi::$codigoComercio = "demo";
Culqi::$llaveSecreta = "JlhLlpOB5s1aS6upiioJkmdQ0OYZ6HLS2+/o4iYO2MQ=";
Culqi::$servidorBase = 'https://integ-pago.culqi.com';

try {

$data = Pago::crearDatospago(array(

//Numero de pedido de la venta, y debe ser único (de no ser así, recibirá como respuesta un error)
Pago::PARAM_NUM_PEDIDO => "tlvh20150727-1",

//Moneda de la venta ("PEN" O "USD")
Pago::PARAM_MONEDA => "PEN",

//Monto de la venta (ejem: 10.25, no se incluye el punto decimal)
Pago::PARAM_MONTO => "1025",

//Descripción de la venta
Pago::PARAM_DESCRIPCION => "Un protector de smartphone y una memoria microSD de 32 GB.",

//Código del país del cliente Ej. PE, US
Pago::PARAM_COD_PAIS => "PE",

//Ciudad del cliente
Pago::PARAM_CIUDAD => "Lima",

//Dirección del cliente
Pago::PARAM_DIRECCION => "Avenida Javier Prado 2132, San Isidro",

//Número de teléfono del cliente
Pago::PARAM_NUM_TEL => "992765900",

//Correo electrónico del cliente
"correo_electronico" => "[email protected]",

//Identificador de usuario del cliente
"id_usuario_comercio" => "ID002",

//Nombres
"nombres" => "William",

//Apellidos
"apellidos" => "Muro",


));

//Respuesta de la creación de la venta. Cadena cifrada.
$informacionVenta = $data[Pago::PARAM_INFO_VENTA];
echo "Información de la venta: $informacionVenta";

echo "Codigo de Comercio: " . $data["codigo_comercio"];
echo "Número de pedido: " . $data["numero_pedido"];
echo "Código de respuesta: " . $data["codigo_respuesta"];
echo "Mensaje de respuesta: " . $data["mensaje_respuesta"];
echo "Ticket de la venta: " . $data["ticket"];

} catch (InvalidParamsException $e) {

echo $e->getMessage()."\n";

}
?>

La respuesta que obtendrás, si la creación fue exitosa, será una cadena cifrada que contiene un JSON.

{"info_venta":"dkladkldlakdmdaaldklakd",
 "codigo_comercio":"testc101",
 "numero_pedido":"testc101",
 "codigo_respuesta":"venta_registrada",
 "mensaje_respuesta":"Venta creada exitosamente.",
 "ticket":"PqHLeGVGBniY7i4XN1N94QIx4MyHHYZhztE"}

####c. Parámetros de respuesta

AN = Alfanumérico

El parámetro "informacion_venta" contenido en la respuesta del servidor de Culqi, debe de ser usado para configurar el Botón de Pago Web en la página del comercio como siguiente paso, ya que asi se inicia la solicitud de los datos de la tarjeta al cliente.

Es importante que almacenes estos datos, ya que el parámetro "Ticket" lo usarás para otras operaciones.

####d. Códigos de respuesta

El parámetro "codigo_respuesta" puede tener los siguientes valores:

El parámetro "mensaje_respuesta" puede tener diferentes contenidos, con el mismo parámetro de "codigo_respuesta".

###6.2 Procesando una Venta

Para empezar, agrega el siguiente código en JavaScript en la página web donde tendrás el Botón de Pago Web:

<script type="text/javascript" src="https://integ-pago.culqi.com/api/v1/culqi.js"></script>

Usar una copia local no está soportado, y puede resultar en errores visibles por el usuario.

Esta integración te permite crear un botón customizado y pasar la respuesta de venta de Culqi a un callback (Función Culqi()) en Javacript. Puedes usar cualquier elemento HTML o evento JavaScript para abrir el formulario de pagos, y es independiente del lenguaje de programación que uses en tu backend.

Puedes usar Culqi.js de la siguiente manera usando Jquery.

//Puedes crear un botón de pago
<button id="btn_pago">Pagar</button>

//Aqui configuramos el botón de pago de Culqi.
<script>

//El código del comercio
checkout.codigo_comercio = "demo";

//La información de la venta: "informacion_venta" es el contenido del parámetro que recibiste en la creación.
checkout.informacion_venta = informacion_venta;


$('#btn_pago').on('click', function(e) {

// Abre el formulario de pago de Culqi.
checkout.abrir();

e.preventDefault();

});

//Esta función es llamada al terminar el proceso de pago.
//Debe de ser usada siempre, para poder obtener la respuesta.
function culqi (checkout) {

//Aquí recibes la respuesta del formulario de pago.
//Si el usuario cierra el formulario de pago: checkout.respuesta tendrá en valor "checkout_cerrado"
console.log(checkout.respuesta);

// Cierra el formulario de pago de Culqi.
checkout.cerrar();

};

</script>

####a. Parámetros de envío

Es muy importante que entiendas que la variable codigo_comercio se encarga de identificar a tu comercio en la comunicación con los servidores de Culqi, y la variable informacion_venta se encarga de enviar la información de la venta.

En este punto, debes visualizar el formulario de pago de Culqi. Luego que el cliente ingrese los datos de la tarjeta y se procese la venta, obtendrás como respuesta una cadena de texto, que puedes leer usando la variable checkout.respuesta que lo encuentras en el ejemplo de Javascript que se mostró previamente.

La variable checkout.respuesta puede retornar los siguientes códigos:

Es de suma importancia que envíes el contenido de la variable "checkout.respuesta" a tus servidores para decrifrarlo usando la librería "culqi.php", ya que la llave no debe ser usada en el navegador web por tu seguridad como comercio.

####b. Enviando la respuesta a tu servidor

Una vez que obtengas la respuesta de Culqi en tu página web es necesario que la envíes a tu servidor para decifrarla y poder mostrar al usuario el resultado de la transacción. A continuación un ejemplo utilizando Ajax y que invoca a una entrada llamada "/respuesta":

$.ajax({
            url: "/respuesta.php",
            type: "POST",
            contentType: "application/json",
            data: JSON.stringify(
                    {
                        'respuesta' : checkout.respuesta
                    }),
            success: function(data){
                var obj = JSON.parse(data);
                var tipo_respuesta_venta = obj["codigo_respuesta"];
                if (tipo_respuesta_venta == "venta_exitosa") {

                } else if (tipo_respuesta_venta == "venta_expirada") {

                } else if (tipo_respuesta_venta == "error") {

                } else if (tipo_respuesta_venta == "parametro_invalido") {

                } else {
                    // Brindale un mensaje amigable al cliente (Puedes usar el mensaje que Culqi recomienda o usar uno tuyo) e invitalo a reintentar la compra.
                    checkout.cerrar();
                }
            },
            error:function( ){
            }
        });

####c. Descrifrando la respuesta

Una vez recibida la respuesta, puedes decifrarla utilizando la librería PHP.

<?php
Culqi::$codigoComercio = "demo";
Culqi::$llaveSecreta = "JlhLlpOB5s1aS6upiioJkmdQ0OYZ6HLS2+/o4iYO2MQ=";

//Retorna el JSON Descifrado
$respuesta = json_decode(Culqi::decifrar($respuestaCliente));

//Codigo del comercio
echo "Código Comercio" . $respuesta["codigo_comercio"];

//Número de pedido
echo "Número de pedido" . $respuesta["numero_pedido"];

//Código de respuesta
echo "Ticket" . $respuesta["codigo_respuesta"];

//Mensaje de respuesta
echo "Mensaje Respuesta" . $respuesta["mensaje_respuesta"];

//Mensaje de respuesta al usuario
echo "Mensaje Respuesta Usuario" . $respuesta["mensaje_respuesta_usuario"];

//ID de la Transacción
echo "ID Transacción" . $respuesta["id_transaccion"];

//Ticket de la venta
echo "Código Referencia" . $respuesta["ticket"];

//Código de referencia
echo "Código Referencia" . $respuesta["referencia_transaccion"];

//Código de autorización
echo "Código Autorización" . $respuesta["codigo_autorizacion"];

//Marca de la tarjeta
echo "Marca" . $respuesta["marca"];

//Emisor de la tarjeta (dato referencial)
echo "Emisor" . $respuesta["nombre_emisor"];

//País de la tarjeta (dato referencial)
echo "País Tarjeta" . $respuesta["pais_emisor"];

//Número de la tarjeta enmascarado
echo "Número Tarjeta" . $respuesta["numero_tarjeta"];

//Nombres del tarjetahabiente
echo "Apellido del Tarjetahabiente" . $respuesta["apellido_tarjeta_habiente"];

//Apellidos del tarjetahabiente
echo "Nombre del Tarjetahabiente" . $respuesta["nombre_tarjeta_habiente"];

}
?>

Obtendrás un JSON que contendrá los siguientes parámetros:

Almacena estos datos por cada petición que realices, y considera que los reintentos esta relacionado al mismo número de pedido, por ello usamos el parámetro de código de referencia.

####d. Códigos de respuesta

El parámetro "codigo_respuesta" puede tener los siguientes valores:

Los parámetros "mensaje_respuesta" y "mensaje_respuesta_usuario" pueden tener diferentes contenidos, con el mismo parámetro de "codigo_respuesta".

##7. Operación de Consulta de una venta

Para consultar una venta debes de enviar el ticket de la transacción (que debes haber guardado) usando la librería de Culqi.

<?php
require 'culqi.php';

Culqi::$llaveSecreta = "JlhLlpOB5s1aS6upiioJkmdQ0OYZ6HLS2+/o4iYO2MQ=";
Culqi::$codigoComercio = "demo";
Culqi::$servidorBase = 'https://integ-pago.culqi.com';

try {

// Ticket de la venta
$data = Pago::consultar("0MXpbwlGjRU9Sr0IwIOqHh1aVJICjGh9KIq");

//Código del comercio
echo "Código Comercio" . $data['codigo_comercio'];

//Número de Pedido
echo "Número de pedido" . $data['numero_pedido'];

//Ticket de la venta
echo "Ticket" . $data['ticket'];

//Estado de la transacción
echo "Estado de la transacción" . $data['estado_transaccion'];

//Código de respuesta
echo "Código Respuesta" . $respuesta["codigo_respuesta"];

//Mensaje de respuesta
echo "Mensaje Respuesta al desarrollador" . $respuesta["mensaje_respuesta"];

//Nombres del tarjetahabiente
echo "Apellido del Tarjeta habiente" . $respuesta["apellido_tarjeta_habiente"];

//Apellidos del tarjetahabiente
echo "Nombre del Tarjeta habiente" . $respuesta["nombre_tarjeta_habiente"];


} catch (InvalidParamsException $e) {

echo $e->getMessage()."\n";

}
?>

###a. Parámetros de envío

###b. Parámetros de respuesta

El parámetro "estado_transaccion" puede tener los siguientes valores:

##8. Operación de Anulación de una venta

Para anular una venta debes de enviar el ticket de la transacción usando la librería de Culqi.

<?php
require 'culqi.php';

Culqi::$llaveSecreta = "JlhLlpOB5s1aS6upiioJkmdQ0OYZ6HLS2+/o4iYO2MQ=";
Culqi::$codigoComercio = "demo";
Culqi::$servidorBase = 'https://integ-pago.culqi.com';

try {

// Ticket de la venta
$data = Pago::anular("0MXpbwlGjRU9Sr0IwIOqHh1aVJICjGh9KIq");

//Codigo del comercio
echo "Código Comercio" . $data['codigo_comercio'];

//Número de Pedido
echo "Número de pedido" . $data['numero_pedido'];

//Ticket de la transacción
echo "Ticket" . $data['ticket'];

//Código de respuesta
echo "Código Respuesta" . $respuesta["codigo_respuesta"];

//Mensaje de respuesta
echo "Mensaje Respuesta al desarrollador" . $respuesta["mensaje_respuesta"];

//Mensaje de respuesta al usuario
echo "Mensaje Respuesta al usuario" . $respuesta["mensaje_respuesta_usuario"];

//Nombres del tarjetahabiente
echo "Apellido del Tarjeta habiente" . $respuesta["apellido_tarjeta_habiente"];

//Apellidos del tarjetahabiente
echo "Nombre del Tarjeta habiente" . $respuesta["nombre_tarjeta_habiente"];

} catch (InvalidParamsException $e) {

echo $e->getMessage()."\n";

}
?>

###a. Parámetros de envío

###b. Parámetros de respuesta

####c. Códigos de respuesta

El parámetro "codigo_respuesta" puede tener los siguientes valores:

El parámetro "mensaje_respuesta" puede tener diferentes contenidos, con el mismo parámetro de "codigo_respuesta".