Integración I.V.R.

  1. Introducción
  2. Programación Web
    1. Solicitud de sesión IVR
    2. Comprobación de estado de sesión IVR
    3. Bis Comprobación de estado de sesión IVR HTTP POST
  3. Anexos
    1. Anexo I - Tipos de operaciones
    2. Anexo II – Monedas

Introducción

La finalidad del presente anexo es servir de referencia durante el proceso de integración de un comercio con la pasarela de pagos PAYCOMET, utilizando el sistema de integración general, con captación de datos de tarjeta a través de sistemas de respuesta de voz interactiva IVR.

Salvo algunas excepciones que se detallan en este documento (operaciones permitidas, cálculos de firmas en la integración XML), toda la documentación relativa a la integración general es perfectamente válida para su realización a través de IVR.

Remítete a dicha documentación para obtener una visión general del proceso de compra y de las distintas entradas y salidas.

Programación Web

Las tecnologías disponibles para la operativa con la pasarela de pagos PAYCOMET son SOAP (XML) y REST, basadas en HTTPS para evitar problemas de transporte a través de firewalls y otros dispositivos y a la vez garantizar la seguridad de las operaciones. Existe un soporte muy amplio para la realización de amos tipos de llamadas para los principales lenguajes de programación usados en entornos web.

Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debes asegurarte de que su sistema es capaz de realizar las peticiones correctamente y gestionar los certificados de seguridad devueltos por la plataforma para una correcta utilización.

Existen varias operaciones que se podrán lanzar desde el mismo servicio.
Las operaciones disponibles vienen descritas a continuación:

Solicitud de sesión IVR

Método: get_ivr_session

Para iniciar una conversación con el sistema de IVR es preciso realizar con anterioridad la siguiente llamada en la que se establecerá el inicio de la sesión.

A continuación, selecciona el tipo de integración:

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

Las variables que se requieren para realizar una solicitud de sesión IVR son (en este orden):

Elemento Contenido Descripción
IVR_PROVIDER_ID [0-9]{1,6} Obligatorio. Código de proveedor / integrador IVR
IVR_STATION_ID [A-Za-z0-9]{255} Obligatorio. Identificador del puesto
IVR_MERCHANT_CODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
IVR_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
IVR_MERCHANT_AMOUNT [0-9]{1,8} Obligatorio. Importe de la operación en formato entero. 1,00 EURO = 100, 4,50 EUROS = 450...
IVR_MERCHANT_CURRENCY [EUR][USD][GBP]… Obligatorio. Moneda de la transacción. Ver más información en el apartado MONEDAS
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación. Debe ser única en cada transacción válida.
IMPORTANTE EN CASO DE SUSCRIPCIONES: No incluir los caracteres “[“ o “]”, se utilizarán para reconocer el idUser del comercio.
IVR_MERCHANT_LANGUAGE [a-zA-Z0-9]{2} Obligatorio. Idioma (iso2) en el que se emitirán las locuciones IVR
IVR_TRANSACTION_TYPE [0-9]{3} Obligatorio. Tipos posibles:
107 Alta de usuario Bankstore
1 Autorización
3 Preautorización
9 Suscripción
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
IVR_MERCHANT_CONCEPT [a-zA-Z0-9]{255} Opcional. Concepto de la operación.
IVR_SUBSCRIPTION_STARTDATE [YYYY-MM-DD] Obligatorio en suscripciones. Fecha de inicio de la subscripción. IMPORTANTE: Las suscripciones se cobran en la primera ejecución si este campo tiene valor se tendrá en cuenta para los futuros cargos.
IVR_SUBSCRIPTION_ENDDATE [YYYY-MM-DD] Obligatorio en suscripciones. Fecha final de la subscripción. No podrá ser mayor que la fecha de inicio de la suscripción + 5 años
IVR_SUBSCRIPTION_PERIODICITY [0-9]{3} Obligatorio en suscripciones. Periodicidad del cobro desde la fecha de inicio. El número expresa Días. No podrá ser mayor de 365 días.
IVR_MAX_RETRIES [0-9]{1} Opcional. Número de intentos permitidos
IVR_SESSION_TIMEOUT [0-9]{3} Opcional. Tiempo máximo de sesión. En segundos
IVR_CALLBACK_STATION_TIMEOUT Opcional. Extensión de retorno en caso de timeout (si se indica "same" se retornará a la misma extensión que nos ha llamado).
IVR_CALLBACK_STATION_OK Opcional. Extensión de retorno en caso de operación OK (si se indica "same" se retornará a la misma extensión que nos ha llamado).
IVR_CALLBACK_STATION_KO Opcional. Extensión de retorno en caso de operación KO (si se indica "same" se retornará a la misma extensión que nos ha llamado).
IVR_CALLER_PHONE_NUMBER Opcional. Número de la llamada entrante.
IVR_PROVIDER_DATA_01 Opcional.
IVR_PROVIDER_DATA_02 Opcional.
IVR_PROVIDER_DATA_03 Opcional.
IVR_PROVIDER_DATA_04 Opcional.
IVR_PROVIDER_DATA_05 Opcional.

Cálculo de firma:

Para IVR_TRANSACTION_TYPE = 1, 3, 9

SHA512(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_TRANSACTION_TYPE + IVR_MERCHANT_ORDER + IVR_MERCHANT_AMOUNT + IVR_MERCHANT_CURRENCY + PROVIDERPASSWORD)

 

Para IVR_TRANSACTION_TYPE = 107

SHA512(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_TRANSACTION_TYPE + IVR_MERCHANT_ORDER + PROVIDERPASSWORD)

 

La descripción de la columna “Contenido” se refiere a la expresión regular que debe cumplir la información presente en el elemento correspondiente. De esta manera “[A-Z]” indica cualquier carácter de la “A” a la “Z” y los corchetes indican el número de caracteres. Por ejemplo “1{2,4}” valida los números “11”, “111” y “1111”.

La respuesta del servicio queda descrita en la tabla siguiente:

IVR_RESPONSE [0-1]{1} Resultado de la solicitud de sesión:
0: Indicará que la sesión IVR no ha podido establecerse.
1: La sesión IVR se estableció correctamente.
IVR_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Si no existe error, el campo contendrá un 0. Los códigos de error vienen especificados en el apartado: CÓDIGOS DE ERROR.

Comprobación de estado de sesión IVR

Método: get_ivr_sessionstate

Este método permite recabar información acerca del estado de una sesión IVR.

A continuación, selecciona el tipo de integración:

La integración de esta función en REST está detallado en su documentación completa, disponible en este enlace

Las variables que se requieren para realizar la consulta son (en este orden):

Elemento Contenido Descripción
IVR_PROVIDER_ID [0-9]{1,6} Obligatorio. Código de proveedor / integrador IVR
IVR_MERCHANT_CODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
IVR_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación.
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS

Cálculo de firma:

SHA512(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_MERCHANT_ORDER + PROVIDERPASSWORD)

La respuesta del servicio queda descrita en la tabla siguiente:

IVR_RESPONSE [0-1]{1} Resultado de la consulta de sesión:
0: Indicará que la sesión IVR no ha podido localizarse.
1: Los datos de sesión se han encontrado y se devuelven a continuación.
IVR_SESSION_STATE [0-7]{1} Los posibles valores son los siguientes:
0: A la espera
1: En proceso
2: Finalizada. OK
3: Finalizada. KO
4: Tiempo de comunicación excedido
5: Referencia no encontrada
6: Operación cancelada por el agente
7: Llamada finalizada. Esperando siguiente llamada
IVR_SESSION_RESULT [0-5]{1} Los posibles valores son los siguientes:
0: Sin error
1: Error en la operación de cobro
2: Error introduciendo los datos de tarjeta
3: Error introduciendo el mes de caducidad
4: Error introduciendo el año de caducidad
5: Error introduciendo el CVV
IVR_TIME_LEFT [0-9]{1,3} Tiempo restante expresado en segundos para que termine la sesión IVR. En el estado 0, 1 y 7 se devolverá el tiempo restante. En los estados 2, 3, 4, 5 y 6 se devolverá 0.
IVR_DIGIT_PAN [0-9]{1,16} Cuando la sesión IVR esté en marcha, se devolverán el número de dígitos de la tarjeta de crédito que el cliente ha introducido. Se devolverá 0 si no se dispone de esa información.
IVR_DIGIT_EXP [0-9]{1,4} Cuando la sesión IVR esté en marcha, se devolverán el número de dígitos de la fecha de caducidad que el cliente ha introducido. Se devolverá 0 si no se dispone de esa información.
IVR_DIGIT_CVC [0-9]{1,4} Cuando la sesión IVR esté en marcha, se devolverán el número de dígitos del CVC2 que el cliente ha introducido. Se devolverá 0 si no se dispone de esa información.
IVR_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Los errores podrán ser de entrada/validación o bien, los correspondientes al estado IVR_SESSION_STATE = 3. Si no existe error, el campo contendrá un 0. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Bis Comprobación de estado de sesión IVR HTTP POST

Adicionalmente, para facilitar la operativa de rescatar la información de una sesión IVR, por ejemplo a través de ajax, es posible realizar la llamada directamente a través de POST.

La url es la siguiente: https://api.paycomet.com/gateway/post_ivr.php

Los parámetros que deberán enviarse son los siguientes:

La respuesta queda descrita en la tabla siguiente:

Elemento Contenido Descripción
getIVRData {Obj} Obligatorio. Este parámetro será un objeto codificado JSON que contendrá los campos que se detallan a continuación
OPERATION [0-9]{1,9} Obligatorio. Operación requerida en la llamada. Valores posibles:
1: get_ivr_sessionstate
IVR_PROVIDER_ID [0-9]{1,6} Obligatorio. Código de proveedor / integrador IVR
IVR_MERCHANT_CODE [A-Za-z0-9]{1,8} Obligatorio. Código de cliente
IVR_MERCHANT_TERMINAL [0-9]{1,4} Obligatorio. Número de terminal
IVR_MERCHANT_ORDER [A-Za-z0-9]{1,20} Obligatorio. Referencia de la operación.
IVR_PROVIDER_SIGNATURE [a-zA-Z0-9] Obligatorio. Ver CALCULO DE FIRMAS
returnData {Obj} La respuesta será un objeto codificado JSON que contendrá los campos que se detallan a continuación:
IVR_RESPONSE [0-1]{1} Resultado de la consulta de sesión:
0: Indicará que la sesión IVR no ha podido localizarse.
1: Los datos de sesión se han encontrado y se devuelven a continuación.
IVR_SESSION_STATE [0-7]{1} Los posibles valores son los siguientes:
0: A la espera
1: En proceso
2: Finalizada. OK
3: Finalizada. KO
4: Tiempo de comunicación excedido
5: Referencia no encontrada
6: Operación cancelada por el agente
7: Llamada finalizada. Esperando siguiente llamada
IVR_TIME_LEFT [0-9]{1,3} Tiempo restante expresado en segundos para que termine la sesión IVR. En el estado 0, 1 y 7 se devolverá el tiempo restante. En los estados 2, 3, 4, 5 y 6 se devolverá 0.
IVR_DIGIT_PAN [0-9]{1,16} Cuando la sesión IVR esté en marcha, se devolverán el número de dígitos de la tarjeta de crédito que el cliente ha introducido. Se devolverá 0 si no se dispone de esa información.
IVR_DIGIT_EXP [0-9]{1,4} Cuando la sesión IVR esté en marcha, se devolverán el número de dígitos de la fecha de caducidad que el cliente ha introducido. Se devolverá 0 si no se dispone de esa información.
IVR_DIGIT_CVC [0-9]{1,4} Cuando la sesión IVR esté en marcha, se devolverán el número de dígitos del CVC2 que el cliente ha introducido. Se devolverá 0 si no se dispone de esa información.
IVR_ERROR_ID [0-9]{1,5} En caso de error, aquí vendrá el código de error generado. Los errores podrán ser de entrada/validación o bien, los correspondientes al estado IVR_SESSION_STATE = 3. Si no existe error, el campo contendrá un 0. Los códigos de error vienen especificados en el apartado CÓDIGOS DE ERROR.

Ejemplo de llamada javascript:



function get_ivr_sessionstate() {
        var obj = {};
        obj.OPERATION= '1';
        obj.IVR_PROVIDER_ID= '**Identificador del proveedor/integrador IVR**';
        obj.IVR_MERCHANT_CODE= '**Código de cliente**';
        obj.IVR_MERCHANT_TERMINAL= '**Número de terminal**';
        obj.IVR_MERCHANT_ORDER= '**Referencia**';
        obj.IVR_PROVIDER_SIGNATURE= 'c292caae75bc62aaaaaaaaaaaaa655ead726471f';


        $.ajax({
                        type: "POST",
                        async: false,
                        url: "https://api.paycomet.com/gateway/post_ivr.php",
                        data: "getIVRData="+JSON.stringify(obj),
                        success: function(returnData){
                        var objR = JSON.parse(returnData);
                        console.log(objR);
                }
        });
}
                        
                

Anexo I - Tipos de operaciones

Los tipos de operaciones permitidos en la integración IVR son los siguientes:

ID Operación
1 Autorización
3 Preautorización
9 Suscripción
107 Alta de usuario Bankstore

Anexo II – Monedas

El lugar donde se detallan los códigos de las monedas en las que pueden realizarse las operaciones, está en el apartado Monedas