Integración I.V.R.

  1. Introducción
  2. Seguimiento del proceso de compra
    1. Correo electrónico
    2. Llamada a URL
  3. Configuración del TPV
  4. 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
  5. Cálculo de la firmas
  6. 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 PAYTPV, 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.

Seguimiento del proceso de compra

El proceso de compra es llevado a cabo por la pasarela de pagos y el sistema de IVR. La resolución de la operación es devuelta directamente al agente en la comunicación con el sistema IVR. No obstante es posible configurar a través del panel de cliente de PAYTPV métodos de notificación adicionales para mantener el conocimiento de la operación a usuarios o lanzar mecanismos adicionales.

Estas notificaciones son idénticas a las enviadas por otro tipo de productos de pasarela de pagos, tales como pasarela WEB o Venta Telefónica. De esta manera es posible para el cliente mantener un control unificado de las ventas realizadas por el comercio.

Para una correcta notificación del proceso de pago es posible configurar el sistema de notificaciones para que le informe del estado de la operación llevada a cabo por la pasarela, bien por correo electrónico, llamada a una URL en segundo plano (independiente del proceso de respuesta al servicio) o ambas y de forma global mediante SMS.

Correo electrónico

La información contenida en un correo de notificación tipo es la siguiente:


Se ha producido una venta según los siguientes parámetros:
Identificador de cuenta: 0gs265nc
Tipo de transacción: Autorización (1)
País de expedición de la tarjeta: ES
Fecha y hora de la transacción (yyyymmddhhmmss): 20101027110536
Orden: 2010102711053676
Respuesta: OK
ID de error: 0
Descripción del error:
Código de autenticación: 802335/120098123810102711053606007000
Moneda: EUR
Cantidad (euros): 10.00
Cantidad (origen): 1000
Idioma: es
ID de producto: 25
Firma:
Concepto: Concepto de la operación
[IDUSER]
[TOKENUSER]
Firma Extendida: 94f487ad8b57141d91fbc8fcda9e346cf17254bc
Pago Seguro: 0
Scoring: 0
Marca Tarjeta: VISA
Código BIC: BSABESBBXXX

Llamada a URL

A la URL de destino se le pasan los parámetros de la notificación con el método POST según la siguiente tabla:

TransactionType Numérico Tipo de operación Ver TIPOS DE OPERACIONES.
TransactionName Alfanumérico Tipo de operación
CardCountry Alfanumérico País de emisión de la tarjeta. Puede ser un valor vacío
BankDateTime Alfanumérico Fecha de la operación
Signature Alfanumérico Firma de la notificación
Order Alfanumérico Referencia pasada por el comercio
Response Alfanumérico Estado final de la operación
ErrorID Numérico Código de error. Ver apéndice
ErrorDescription Alfanumérico Descripción textual del error (opcional)
AuthCode Alfanumérico Código de autorización devuelto por el banco (opcional)
Currency Alfanumérico Moneda en la que realizó la operación
Amount Numérico Importe pasado por el comercio
AmountEur Numérico Importe en euros
Language Alfanumérico Idioma en que se presentó la plataforma
AccountCode Alfanumérico Código de cliente
TpvID Numérico Número de terminal
Concept Alfanumérico Concepto de la operación
ExtendedSignature Alfanumérico Firma extendida de la notificación
SecurePayment Numérico Tomará valor 1 si la operación se procesó en modo seguro. Valor 0 cuando la operación se procesó en modo no seguro.
[IdUser] Numérico Opcional. Aparecerá en las operaciones en las que esté involucrado un IdUser
[TokenUser] Alfanumérico Opcional. Aparecerá en las operaciones en las que esté involucrado un TokenUser
CardBrand Alfanumérico Marca de la tarjeta, si se pudo determinar.
BicCode Alfanumérico Código de la entidad bancaria por la que se realizó la operación, si se pudo determinar.
Scoring Numérico Scoring calculado en la operación.

CONFIGURACIÓN DEL TPV

Para poder utilizar la pasarela de pago PAYTPV en su comercio deberá estar en posesión de los parámetros de configuración necesarios. Éstos pueden obtenerse a través de la plataforma de gestión de cliente de PAYTPV, en https://secure.paytpv.com/cp_control/

Una vez dentro de la plataforma, puede revisar la configuración del producto contratado mediante el menú Mis productos->Configurar producto.

Tras pulsar en el botón “Editar” () del producto elegido, aparecerá un panel con la información básica del producto bajo el apartado “Configuración técnica del XML SOAP RECURRENTE”. En concreto los datos necesarios durante el proceso de integración son:

  • Contraseña. Atención: Esta contraseña es necesaria para operaciones del producto actuando a través de Bankstore. Para la integración IVR, la contraseña que debe utilizarse para las firmas será la de su proveedor / integrador de la solución IVR.
  • Número de terminal
  • Código de cliente
  • URL del servicio (https://secure.paytpv.com/gateway/xml_ivr.php)
  • URL del archivo de descripción del servicio web (WSDL) a modo de referencia (https://secure.paytpv.com/gateway/xml_ivr.php?wsdl)

Programación Web

La tecnología empleada para la operativa con la pasarela de pagos PAYTPV 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]{40} 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]{40} 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-1]{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
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://secure.paytpv.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]{40} 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-1]{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
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://secure.paytpv.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

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

Para IVR_TRANSACTION_TYPE = 107

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

FUNCIÓN: get_ivr_sessionstate

SHA1(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