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. Cálculo de la firmas
  4. Tipos de operaciones

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 BankStore, 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), toda la documentación relativa al Bankstore es perfectamente válida para su realización a través de IVR.

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

Programación Web

La tecnología empleada para la operativa con la pasarela de pagos PAYCOMET es SOAP, basada 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 llamadas SOAP para los principales lenguajes de programación usados en entornos web.

Las peticiones se realizan mediante el protocolo de transporte HTTPS, de manera que debe asegurarse 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.

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.
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
IVR_CALLBACK_STATION_OK Opcional. Extensión de retorno en caso de operación OK
IVR_CALLBACK_STATION_KO Opcional. Extensión de retorno en caso de operación KO
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.
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.

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

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 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, se devolverá el tiempo máximo establecido. En el estado 1 se devolverá el tiempo restante. En los estados 2, 3, 4 y 5 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:

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
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 queda descrita en la tabla siguiente:

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, se devolverá el tiempo máximo establecido. En el estado 1 se devolverá el tiempo restante. En los estados 2, 3, 4 y 5 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);
                }
        });
}
                        
                

CÁLCULO DE FIRMAS

La firma que enviará el comercio a la pasarela se calculará de la siguiente forma (en pseudo-código):

FUNCIÓN: get_ivr_session

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)

 

FUNCIÓN: get_ivr_sessionstate

SHA512(IVR_MERCHANT_CODE + IVR_MERCHANT_TERMINAL + IVR_MERCHANT_ORDER + PROVIDERPASSWORD)

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 I – MONEDAS

El ANEXO I – MONEDA E IMPORTE donde se detallan los códigos de las monedas en las que pueden realizarse las operaciones, está en el apartado Monedas