CIMA - Manual de Integración Boton de Pago CredibanCo #- V1.3 - Oct2013

CONFIDENCIALIDAD DE LA INFORMACION

La información contenida en el presente manual tiene el carácter confidencial y ha sido elaborada por CREDIBANCO, por lo tanto EL COMERCIO deberá guardar la más absoluta reserva sobre toda la información. EL COMERCIO se obliga a informar y extender las obligaciones de reserva aquí acordadas a sus funcionarios y contratistas. El COMERCIO utilizará la información confidencial solamente para los propósitos aquí contenidos, y tomará todas las precauciones razonables para prevenir el acceso o el uso no autorizado de la misma. El COMERCIO no hará ninguna publicación o revelación al público o a terceros de la información confidencial, salvo autorización expresa o escrita por parte de CREDIBANCO.

Maunal de Integración API Credibanco– Julio de 2013 P 0/ 43

MANUAL DE INTEGRACION BOTON DE PAGO .NET C# ECOMMERCE CREDIBANCO VERSIÓN 1.1


HISTORIA DE REVISIONES Fecha

Versión

<17/05/2012>

1.0

Generación del documento

Descripción

Credibanco

<05/12/2012>

1.1

Ajustes de Alignet

Credibanco

<30/07/2013> <10/09/2013>

1.2 1.3

Ajustes inclusion nuevos campos Aclaración campos

Credibanco Credibanco


Autor

TABLA DE CONTENIDO HISTORIA DE REVISIONES ............................................................................................................................................................. 2 TABLA DE CONTENIDO ................................................................................................................................................................. 3 INTRODUCCIÓN ........................................................................................................................................................................... 4 OBJETIVOS........................................................................................................................................................................................... 4 GLOSARIO ........................................................................................................................................................................................... 4 FLUJO DE COMPRA ................................................................................................................................................................................ 4 EXPERIENCIA DE COMPRA ....................................................................................................................................................................... 6 ¿QUÉ ES EL V-POS?....................................................................................................................................................................... 9 DESCRIPCIÓN ....................................................................................................................................................................................... 9 ARQUITECTURA .................................................................................................................................................................................... 9 SOLICITUD Y RESPUESTA DEL FLUJO DE PAGO ........................................................................................................................................... 10 INTEGRACIÓN AL V-POS ............................................................................................................................................................. 11 PROCEDIMIENTO DE INTEGRACIÓN AL V-POS ........................................................................................................................................... 11 ADMINISTRACIÓN DE LLAVES CRIPTOGRÁFICAS .......................................................................................................................................... 12 SOLICITUD DE PAGO............................................................................................................................................................................. 13 RESPUESTA DE PAGO ........................................................................................................................................................................... 24 INTEGRACIÓN CON EL PLUG-IN .................................................................................................................................................. 30 PREGUNTAS Y RESPUESTAS FRECUENTES ................................................................................................................................... 31 DATOS ADICIONALES ................................................................................................................................................................. 32 ANEXO 1: INTEGRACIÓN CON EL PLUG-IN PARA .NET C#............................................................................................................ 33 INSTALACIÓN DEL PLUG-IN C# ............................................................................................................................................................... 33 USO DEL PLUG-IN C# PARA ENVIAR INFORMACIÓN AL V-POS ...................................................................................................................... 34 USO DEL PLUG-IN C# PARA RECIBIR INFORMACIÓN DEL V-POS .................................................................................................................... 35 USO DEL PLUG-IN C# PARA ENVIAR INFORMACIÓN AL V-POS Y CONSUMO DE WEB SERVICE ............................................................................. 37


INTRODUCCIÓN Para realizar transacciones electrónicas los comercios requieren de una plataforma que les permita conectarse con el mundo transaccional de pagos virtuales. Para ello el flujo de pago, actualmente, está compuesto por el proceso de autorización, que permite realizar la solicitud de pago de una compra electrónica. Este proceso será atendido por el V-POS, un servicio centralizado que permitirá al comercio integrarse fácilmente con el proceso de pago.

Objetivos Este documento tiene como objetivos lo siguiente:  

Describir las funcionalidades que brinda el V-POS. Describir los pasos necesarios para la integración con el V-POS.

Glosario A lo largo del presente documento se utilizan los siguientes términos bajo la conceptualización que se señala a continuación:    

Proceso de Autorización: Servicio de autorización del pago V-POS: Virtual Point Of Sale. Interfaz del mundo transaccional de pagos virtuales Tarjeta habiente: Titular de la tarjeta V-Admin: Interfaz Administrativa del V-Payment.

Flujo de Compra El flujo de compra se inicia cuando el tarjeta habiente desea realizar una compra en un comercio electrónico. El tarjeta habiente escoge los productos que desea comprar agregándolos al carrito de compras del comercio. A continuación se listan los pasos del flujo de compra (Ver Maunal de Integración API Credibanco– Julio de 2013 P 4/ 43

Figura 1. Flujo de Compra): 1. El Comercio desde un formulario envía al V-POS los datos de compras haciendo uso del plug-in proporcionado por Credibanco, exceptuando el número de Tarjeta de Crédito, la fecha de Vencimiento y el CVV2, entre otros datos. 2. El V-POS luego de validar los datos enviados por el comercio, muestra en el navegador del tarjeta habiente una página donde se ingresa el número de tarjeta de crédito, la fecha de vencimiento, el valor CVV2 y algunos datos complementarios. 3. El usuario ingresa en la pantalla anterior, los valores solicitados. 4. El V-POS valida los datos ingresados por el tarjeta habiente, seguidamente envía al sistema V-Payment una solicitud de pago que inicia el proceso de autorización. 5. El V-Payment luego de realizar el proceso de autorización devuelve los valores al V-POS para su posterior análisis del proceso de compra. 6. El V-POS devuelve el resultado de la compra al comercio. El comercio haciendo uso del plug-in (ver Anexos) obtiene los valores de respuesta; quien finalmente le mostrará al tarjeta habiente como resultado final de su compra.

Figura 1: Flujo de Compra


Experiencia de Compra A continuación se mostrará la experiencia de compra electrónica del tarjeta habiente aprovechando la plataforma: 1. El tarjeta habiente ingresa al sitio Web del Comercio electrónico.

Figura 2: Página de Inicio del Comercio

2. El tarjeta habiente llena el carrito de compras, luego ingresa sus datos de compra, dando inicio al flujo de compra.

Figura 3: Página de Carrito de compras del Comercio


3. Luego al tarjeta habiente se le mostrará la página centralizada del V-POS y le solicitará el ingreso de los datos de su tarjeta.

Figura 4: Página centralizada V-POS para el ingreso de datos de la tarjeta

4. Finalmente al tarjeta habiente le aparecerá la página resultado del Comercio.


Figura 5: Página de resultado del comercio


¿QUÉ ES EL V-POS? El V-POS es el sistema que atiende la solicitud de pago enviado desde los comercios virtuales, cuya funciones principales son concentrar y preprocesar las solicitudes de Pago. Concentrar, porque centraliza el proceso principal de compra (autorización); Pre procesar, porque procesa la validación de los datos de la tarjeta antes de iniciar el proceso de autorización.

Descripción Su función principal es concentrar las transacciones de compra por comercio electrónico para validar datos generales de la compra, así como centralizar la obtención y seguridad de los datos sensibles del tarjeta habiente (número de tarjeta, fecha de expiración y CVV2), iniciar el proceso de pago – Proceso de Autorización para que finalmente se le entregue la respuesta de la transacción al comercio que lo solicitó.

Arquitectura El comercio se comunicará vía Internet, a través de un canal seguro (HTTPS) con el V-POS para enviarle los datos de la compra desde un formulario a través del navegador del tarjeta habiente; luego el V-POS le presentará al tarjeta habiente una página de ingreso de datos sensibles para luego iniciar el proceso de pago: Autorización. Finalmente el V-POS le enviará desde un formulario, el resultado de la transacción al comercio vía Internet, a través de un canal seguro (HTTPS). En el siguiente gráfico se muestra la arquitectura general del V-POS:

Figura 6: Arquitectura con el V-POS


Solicitud y Respuesta del Flujo de Pago El comercio enviará una solicitud o petición de pago al V-POS quien se encargará de realizar el proceso autorización y recibirá una respuesta del proceso como se muestra en la figura anterior.

Tarjeta Habiente

Sitio Web Comercio

V-POS

V-Payment Autorización

1: Ingresa Datos de Compra

2: Envía Datos de Compra

3: Muestra Página Centralizada

4: Ingresar Datos de Tarjeta

5: Solicita Autorización de Pago

6: Envía Resultado de Autorización

7: Envía Resultado a la Página de Respuesta

8: Muestra Resultado de Pago

Figura 7: Diagrama de Secuencia de la Solicitud y Respuesta del Flujo de Pago


INTEGRACIÓN AL V-POS Procedimiento de Integración al V-POS La integración se hace inicialmente en un ambiente de Pruebas y luego se traslada a un ambiente de Producción. Para el Ambiente de Pruebas: Los principales pasos para la integración del comercio al V-POS en el ambiente de Pruebas son: 1. Se le hace entrega al comercio del documento de plataforma de sitio Web, el cual debe ser devuelto con todos los datos llenos 2. Se aprobará el documento y se entregará el KIT de seguridad compuesto por un Componente de seguridad (plug-in), el cual será utilizado durante el proceso de compra. 3. El comercio revisará y evaluará los pasos para los desarrollos necesarios según la Guía de integración de comercios, utilizando el Componente de seguridad (plug-in), así como las llaves de criptografía y de firma digital. 4. El comercio confirmará la fecha de término de su desarrollo y solicitará la habilitación del ambiente de prueba. 5. El comercio deberá ser registrado en el sistema de autorización antes de iniciar un proceso de compra de prueba. En esta fase de registro del comercio, se le solicitarán los datos necesarios para su integración en los diferentes sistemas involucrados en el VPayment. 6. Se enviarán las referencias o personas de contacto del comercio, que serán responsables de las pruebas. Se hará entrega al comercio de los valores de configuración (IDACQUIRER, IDECOMMERCE) requeridos por el Componente de seguridad (plug-in). 7. El comercio hará uso del V-Admin para generar las llaves de criptografía y de firma digital. Las llaves públicas de pruebas así como el vector de inicialización generadas por el comercio deberán ser registradas en el sistema, para su posterior uso en el V-POS. 8. El comercio tendrá que confirmar por correo a Credibanco que sus llaves se encuentran registradas en el ambiente de pruebas. 9. Se envía al comercio los datos de prueba y la ruta de acceso al VPOS en el ambiente de prueba. 10. El comercio acuerda una fecha y hora para realizar las pruebas. Se definen los responsables de las pruebas tanto por el lado de Credibanco como del comercio. 11. Se realizan las pruebas. 12. Credibanco informa al comercio el término y el resultado de las pruebas en el Ambiente de Pruebas.


Para el Ambiente de Producción: Los principales pasos para la integración del comercio al V-POS en el ambiente de Producción son: 1. Se solicita al Comercio los datos de producción requeridos para la integración al V-POS. El formato será proporcionado por Credibanco. Se registrará al Comercio en el sistema de Autorización en Producción. 2. Se enviarán las referencias o personas de contacto del comercio para iniciar la generación y registro de llaves de criptografía y de firma digital en el V-Payment, así como la entrega de los valores de configuración (IDACQUIRER, IDECOMMERCE) al comercio. 3. El comercio hará uso del V-Admin para generar las llaves de criptografía y de firma digital. Las llaves públicas de pruebas así como el vector de inicialización generadas por el comercio deberán ser registradas en el sistema, para su posterior uso en el V-POS. 4. El comercio tendrá que confirmar por correo a Credibanco que sus llaves se encuentran registradas en el ambiente de pruebas. 5. Se envía al comercio los datos de prueba y la ruta de acceso al VPOS en el ambiente de producción. 6. El comercio acuerda una fecha y hora para realizar las pruebas. Se definen los responsables de las pruebas tanto por parte de Credibanco como por el lado del comercio. 7. Se realizan las pruebas correspondientes. 8. Credibanco informa al comercio el término de las pruebas en el ambiente de producción.

Administración de llaves criptográficas Con la finalidad de que la transmisión de información entre el comercio y el V-POS se realice de manera segura, guardando los tres principios de seguridad: Protección, Integridad y Autenticidad de datos, el comercio generará a través del V-Admin un par de llaves (pública y privada) para cifrar la información y un par de llaves (pública y privada) para la generación de la firma digital de la solicitud de pago. Las llaves públicas serán registradas en el sistema a través del V-Admin en la etapa de integración del comercio (ver Integración al V-POS). De la misma manera se generará, para el V-POS, un par de llaves para el cifrado y un par de llaves para la generación de la firma digital de la respuesta de pago. Las llaves públicas del V-POS podrán ser descargadas por el comercio desde el aplicativo V-Admin durante la etapa de integración del comercio (ver Integración al V-POS). De forma adicional el comercio generará un valor para el vector de inicialización que se utilizará para la criptografía y también registrado en el sistema. Este será un valor hexadecimal de 16 caracteres. Por ejemplo: d412589745df36fa. Es responsabilidad del comercio el almacenamiento de las llaves generadas, en un entorno seguro. Maunal de Integración API Credibanco– Julio de 2013 P 12/ 43

A continuación se muestra el gráfico resume de la generación de llaves del comercio y descarga de llaves públicas del V-POS.

Figura 9: Generación y descarga de llaves del comercio y V-POS

Solicitud de pago La solicitud de pago se define como el conjunto de datos que necesita el V-POS para generar la solicitud de autorización. Para iniciar la solicitud de pago, el comercio deberá preparar una petición POST HTTP, en la que utilizará el Componente de seguridad (plug-in) para enviar la petición de manera segura al V-POS. Parámetros de Envío Los parámetros que enviará el comercio al V-POS para iniciar la solicitud de pago son los siguientes:

Campo

Descripción


IDACQUIRER

Identificador fijo del Adquirente que permite al V-POS reconocer a la entidad adquirente del comercio. Este valor es generado por CREDIBANCO.

IDCOMMERC E

Identificador fijo del comercio o tienda virtual que permite al VPOS reconocer al comercio que está enviando la solicitud de pago.

XMLREQ

Mensaje de solicitud de pago que contiene los datos de la compra. Este mensaje es generado por el plug-in, quien se encarga de cifrarlo para su envío al V-POS.

DIGITALSIGN

Firma digital del mensaje XMLREQ que asegura tanto la autenticidad del emisor y receptor, como la integridad de la información. Esta firma digital es generada por el plug-in.

SESSIONKEY

Llave de sesión con la cual se cifrará el mensaje XMLREQ. Esta llave es generada por el plug-in.

Para el envío de la solicitud de pago se deberá de generar una solicitud POST, usando un formulario HTML, implementado en el lenguaje de programación del comercio o tienda virtual. A continuación un ejemplo del formulario el cual deberá tener la forma siguiente:

Nota: Los valores que se encuentran en IDACQUIRER e IDCOMMERCE deben modificarse de acuerdo a los datos del comercio respectivo. Así mismo los valores del XMLRES, SESSIONKEY y DIGITALSIGN deben ser capturados desde la clase de envío. Parámetros necesarios para el Componente de seguridad Para que el Componente de seguridad (plug-in) pueda generar el mensaje del parámetro XMLREQ, el comercio deberá llenar los siguientes parámetros con sus respectivos valores:


Campo Plug-in

Tipo

Ancho Máximo

Observaciones

acquirerId

NUMERICO

4

Código de adquirente asignado por Credibanco. Valor fijo e igual al parámetro IDACQUIRER (1)

commerceId

NUMERICO

12

Código único de Comercio asignado por Credibanco. Valor fijo e igual al parámetro IDCOMMERCE (1)

purchaseOperationNumber

ALFANUMERICO

9

Identificador único por cada transacción, generado por el comercio (1)

purchaseAmount

NUMERICO

10

Valor total de la compra, dado por el Comercio. el monto debe ir sin separador decimal (Si el monto es 100.00 dólares entonces la cantidad a enviar es 10000) (1)

purchaseCurrencyCode

NUMERICO

12

Moneda Según Estándar numérico ISO, longitud de 3 caracteres (Pesos Colombianos:170, Dólares: 840) (1)

purchaseTerminalCode

ALFANUMERICO

8

Código de terminal de la compra. Se obtiene del registro del terminal asociado al usuario del comercio.

purchasePlanId

NUMERICO

2

Identificación del plan de cobranza, este valor es dado por el adquirente al comercio (Valor fijo=01) (1)

purchaseQuotaId

NUMERICO

3

Numero de cuotas si se paga con tarjeta crédito (Ejemplo: 001, 015, 045)(1). Enviar 001

purchaseShippingCharges

ALFANUMERICO

12

Monto de compra relativo al embarque de los bienes y productos, este dato es opcional y antes de usarlo debe coordinarse con el adquirente. Maunal de Integración API Credibanco– Julio de 2013 P 15/ 43

purchaseShipperCode

NUMERICO

10

Código de entidad de Embarque, este código es opcional y los posibles valores son enviados por el Adquirente al comercio

purchaseIva

ALFANUMERICO

10

Monto del valor IVA, relativo al impuesto asociado a la compra. El formato es igual al del campo purchaseAmount

purchaseIvaReturn

ALFANUMERICO

10

Monto del valor IVA de retorno, relativo al impuesto asociado a la compra. El formato es igual al del campo purchaseAmount

purchaseIPAddress

ALFANUMERICO

15

Dirección IP del comprador

purchaseLanguage

ALFANUMERICO

2

Lenguaje de la compra: Valor fijo: SP (Español) (1)

billingFirstName

ALFANUMERICO

30

Nombre del titular de la tarjeta (1)

billingLastName

ALFANUEMRICO

50

Apellidos del titular de la tarjeta (1)

billingCountry

ALFANUMERICO

2

Código ISO del País del tarjetahabiente. Obligatorio para modulo antifraude.

billingCity

ALFANUMERICO

50

Nombre de la Ciudad del tarjetahabiente. Obligatorio para modulo antifraude.

billingState

ALFANUMERICO

15

Nombre del Estado del tarjetahabiente.Codigo ISO para el estado y es obligatorio si el país es EEUU o Canada cuando se tiene modulo antifraude.

billingPostalCode

ALFANUMERICO

5

Código Postal del tarjetahabiente. Es obligatorio si el país es EEUU o Canada caundos e tiene moudlo antifraude. Maunal de Integración API Credibanco– Julio de 2013 P 16/ 43

billingAddress

ALFANUMERICO

50

Dirección del tarjetahabiente. Obligatorio para modulo antifraude.

billingPhonePhone

ALFANUMERICO

15

Teléfono del tarjetahabiente. (1). Mínimo 10 digitos.

billingCelPhoneNumber

ALFANUMERICO

20

Celular del tarjetahabiente. (1)

billingGender

ALFANUMERICO

1

Género del tarjetahabiente (Formato: M ó F). Obligatorio para modulo antifraude.

billingEmail

ALFANUMERICO

50

E-mail del tarjetahabiente. (1)

billingBirthday

ALFANUMERICO

12

Fecha de nacimiento del tarjetahabiente (Formato: AAAA-MM-DD)

billingOutIdentifierCity

ALFANUMERICO

30

Ciudad donde obtuvo el documento de identificación el tarjetahabiente

billingDateIdentifierDate

ALFANUMERICO

12

Fecha de la obtención del documento de identificación del tarjetahabiente (Formato: AAAA-MM-DD)

billingNationality

ALFANUMERICO

2

Nacionalidad del tarjetahabiente (Código ISO). Obligatorio para modulo antifraude.

shippingReceiverName

ALFANUMERICO

30

Nombre de la persona que recibirá los bienes

shippingReceiverLastName

ALFANUMERICO

50

Apellido de la persona que recibirá los bienes

shippingReceiverIdentifier

ALFANUMERICO

20

Identificación de la persona que recibirá el producto

shippingReceptionMethod

ALFANUMERICO

100

Método de Recepción del producto


shippingCountry

ALFANUMERICO

2

Código ISO del País de entrega. Obligatorio para modulo antifraude.

shippingCity

ALFANUMERICO

50

Nombre de la Ciudad de entrega. Obligatorio para modulo antifraude.

shippingAddress

ALFANUMERICO

50

Dirección de entrega del pedido del tarjetahabiente Obligatorio para modulo antifraude.

flightAirlineCode

ALFANUMERICO

2

Código de la aerolínea, generado por Credibanco al momento de su registro en el sistema

flightDepartureAirport

ALFANUMERICO

50

Campo tipo Airport, que hace referencia a los datos propios del Aeropuerto de salida

flightArriveAirport

ALFANUMERICO

50

Campo tipo Airport, que hace referencia a los datos propios del Aeropuerto de llegada

flightDepartureDate

ALFANUMERICO

20

Campo que hace referencia a la fecha de salida del vuelo (Formato: AAAA-MM-DD)

flightDepartureTime

ALFANUMERICO

20

Campo tipo texto que hace referencia a la hora de salida del vuelo (Formato: HH:mm pm z) HH = hour in 24-hour format hh = hour in 12-hour format a = am or pm (case insensitive) z = time zone of the departing flight, for example: If the airline is based in city A, but the flight departs from city B, z is the time zone of city B at the time of departure. Ejemplo: 11:30pm GMT-05:00 11:30pm GMT


flightArriveDate

ALFANUMERICO

20

Campo tipo texto que hace referencia a la fecha de llegada del vuelo (Formato: AAAA-MM-DD)

flightArriveTime

ALFANUMERICO

20

Campo tipo texto que hace referencia a la hora de llegada del vuelo (Formato: HH:mm pm)

flightPassegerList

ALFANUMERICO

50

Campo tipo Passenger, que hace referencia a los datos propios del pasajero

flightReservation

ALFANUMERICO

20

Observación adicional del vuelo

AirportCodeDeparture

ALFANUMERICO

3

Código IATA del aeropuerto de salida

AirportCityDeparture

ALFANUMERICO

50

Ciudad donde está ubicado el aeropuerto de salida

AirportCountryDeparture

ALFANUMERICO

2

Código ISO del País donde está ubicado el aeropuerto de salida

AirportCodeArrive

ALFANUMERICO

3

Código IATA del aeropuerto de llegada

AirportCityArrive

ALFANUMERICO

50

Ciudad donde está ubicado el aeropuerto de llegada

AirportCountryArrive

ALFANUMERICO

2

Código ISO del País donde está ubicado el aeropuerto de llegada

passengerFirstName

ALFANUMERICO

50

Nombres del pasajero

passengerLastName

ALFANUMERICO

50

Apellidos del pasajero


passengerDocumentType

ALFANUMERICO

15

Tipo de documento de identidad del pasajero

passengerDocumentNumber

ALFANUMERICO

50

Número del documento de identidad del pasajero

passengerAgencyCode

ALFANUMERICO

10

Código de agencia (ID comercio tipo Agencia)

goodName

ALFANUMERICO

50

Nombre del bien adquirido

goodDescription

ALFANUMERICO

30

Descripción del bien adquirido

goodQuantity

NUMERICO

10

Cantidad del bien adquirido

goodUnitprice

NUMERICO

10

Precio unitario del bien adquirido

productItem

NUMERICO

3

Número de ítem del producto

productCode

ALFANUMERICO

12

Código del producto

productAmount

NUMERICO

10

Monto total del producto

productPromotionCode

ALFANUMERICO

20

Código de promoción de producto

taxName

ALFANUMERICO

12

Nombre del impuesto u propina (PROPINA para propina, TASA_AERO para Tasa aeroportuaria). Obligatorios para tipos de comercio: restaurantes, aerolíneas, agencias. Maunal de Integración API Credibanco– Julio de 2013 P 20/ 43

taxAmount

NUMERICO

10

Monto del impuesto u propina (Incluye cifra decimal sin símbolo separador). Obligatorios para tipos de comercio: restaurantes, aerolíneas, agencias.

administrativeRateAmount

NUMERICO

10

Monto del impuesto Tasa Administrativa, enviado sólo por comercios tipo Agencia de Viaje (Incluye cifra decimal sin símbolo separador)

administrativeRateIva

NUMERICO

10

Monto del valor iva, relativo al pago de la Tasa Administrativa (Incluye cifra decimal sin símbolo separador).

administrativeRateIvaReturn

NUMERICO

10

Monto del valor iva de retorno, relativo al pago de la Tasa Administrativa (Incluye cifra decimal sin símbolo separador).

administrativeRateCode

ALFANUMERICO

2

Código de Tasa Administrativa generado por Credibanco: 99

transactionTrace

ALFANUMERICO

2

Identifica el canal de comunicación en la plataforma de pago (Valor fijo para VPOS: BC)

fingerprint

ALFANUMERICO

30

Código único que identifica la solicitud de pago (1).

additionalObservations

ALFANUMERICO

50

Observación adicional de la compra

reserved1

ALFANUMERICO

30

Campos para datos adicionales no revisados por el VPOS.

. Maunal de Integración API Credibanco– Julio de 2013 P 21/ 43

. . reserved40 (1) Campos requeridos por el VPOS.


Parámetros de Seguridad necesarios para el Plug-in Además de los valores o campos mostrados, se deberá ingresar al plug-in los valores o campos necesarios para el cifrado del mensaje XMLREQ así como también para la generación de la firma digital del mismo. Estos valores se describen a continuación:

Campo

Campo Plug-in

Observaciones

Vector de Inicialización

VectorInicializacion

Valor necesario para el cifrado del mensaje XMLREQ. Este valor debe ser generado por el comercio a través del VAdmin.

Llave privada de Firma

LlavePrivadaFirmaRSA

Llave privada del comercio con la que se generará la firma digital del mensaje XMLREQ. Esta llave privada es generada a través del V-Admin y sólo almacenada por el comercio.

Llave pública de cifrado

LlavePublicaCifradoRSA

Llave pública con la que se cifrará el mensaje XMLREQ. Esta llave pública es generada por Credibanco y debe ser descargada y almacenada por el comercio.


Respuesta de pago Parámetros de Recibo La respuesta de pago que enviará el V-POS al comercio estará compuesta por los siguientes campos:

Campo

Descripción

IDACQUIRER

Es el identificador fijo del Adquirente que permite al V-POS reconocer a la entidad adquirente del comercio. Este valor es generado por Credibanco.

IDCOMMERC E

Es el identificador del comercio o tienda virtual que permite al V-POS reconocer al comercio que esta enviando la solicitud de pago. Este valor es generado por Credibanco durante la configuración del comercio.

XMLRES

Es el mensaje de respuesta de pago que contiene los datos del resultado de la autorización.

DIGITALSIGN

Es la firma digital del mensaje XMLRES, y asegura tanto la autenticidad del emisor y receptor como la integridad de la información. Esta firma digital es generada por el V-POS.

SESSIONKEY Es la llave de sesión con la cual se descifrará el mensaje XMLRES.

Para recibir la respuesta de pago del V-POS es necesario que el comercio implemente una página dinámica en donde se extraiga los valores de los parámetros mostrados en la tabla anterior.


Parámetros de respuesta obtenidos del Plug-in Así mismo el XMLRES devuelve los mismos campos enviados en el XMLREQ enviados al inicio de la compra con la adición de los siguientes campos:

Campo Plug-in authorizationResult

Tipo NUMERICO

Ancho Máximo 2

Observaciones Este campo contiene el resultado de la autorización. Tiene tres posibles valores enviados por el V-POS: 00, indica que la transacción ha sido autorizada, 01, indica que la transacción ha sido denegada en el Banco Emisor, y 05, indica que la transacción ha sido rechazada por el VPOS. NOTA IMPORTANTE: El comercio mostrará los mensajes de resultado al tarjeta habiente según estos tres códigos. Por ejemplo: “Operación Autorizada”. “Operación Denegada”. “Operación Rechazada” (1)

authorizationCode

ALFANUMERICO

6

En caso que la transacción haya sido autorizada, este campo contendrá el código de autorización de la transacción. (1)

errorCode

ALFANUMERICO

4

En caso que la transacción haya sido denegada o rechazada este campo contendrá el código de error respectivo que indicará el motivo del rechazo. La lista de códigos puede aumentar o disminuir según las mejoras que se realicen al V-Payment y/o nuevas especificaciones de las marcas. Maunal de Integración API Credibanco– Julio de 2013 P 25/ 43

NOTA IMPORTANTE: Este código de respuesta no debe ser mostrado al tarjeta habiente. errorMessage

ALFANUMERICO

50

Este campo contendrá la descripción del código de error en caso de producirse un rechazo. NOTA IMPORTANTE: Este mensaje de error no debe ser mostrado al tarjeta habiente.

Adicionalmente, si el tipo de comercio es Agencia de Viaje y este realizó únicamente el Pago de Tasa Administrativa o realizó envío una doble transacción por el VPOS (Pago de tiquete y Pago de Tasa Administrativa), el XMLRES devolverá los siguientes campos:

Campo Plug-in authorizationResultAR

Tipo NUMERICO

Ancho Máximo 2

Observaciones Este campo contiene el resultado de la autorización del Pago de Tasa Administrativa. Tiene tres posibles valores enviados por el V-POS: 00, indica que la transacción ha sido autorizada, 01, indica que la transacción ha sido denegada en el Banco Emisor, y 05, indica que la transacción ha sido rechazada por el VPOS. NOTA IMPORTANTE: El comercio mostrará los mensajes de resultado al tarjeta habiente según estos tres códigos. Por ejemplo: “Operación Autorizada”. “Operación Denegada”. Maunal de Integración API

Credibanco– Julio de 2013 P 26/ 43

“Operación Rechazada” (1) authorizationCodeAR

ALFANUMERICO

6

En caso que la transacción del Pago de Tasa Administrativa haya sido autorizada, este campo contendrá el código de autorización de la transacción. (1)

errorCodeAR

ALFANUMERICO

4

En caso que la transacción del Pago de Tasa Administrativa haya sido denegada o rechazada este campo contendrá el código de error respectivo que indicará el motivo del rechazo. La lista de códigos puede aumentar o disminuir según las mejoras que se realicen al V-Payment y/o nuevas especificaciones de las marcas. NOTA IMPORTANTE: Este código de respuesta no debe ser mostrado al tarjeta habiente.

errorMessageAR

ALFANUMERICO

50

Este campo contendrá la descripción del código de error en caso de producirse un rechazo en el Pago de Tasa Administrativa. NOTA IMPORTANTE: Este mensaje de error no debe ser mostrado al tarjeta habiente.


Además de estos campos, la respuesta de pago o XMLRES, contendrá todos los campos enviados al V-POS que se ingresaron en el XMLREQ de la solicitud de pago y que podrán ser recuperados usando el componente de seguridad (plug-in). Asimismo se tiene los siguientes campos adicionales.

Campo Plug-in

Tipo

Ancho Máximo

Observaciones

planCode

NUMERICO

4

Código del plan seleccionado por el tarjetahabiente en caso haber financiado el pago

quotaCode

NUMERICO

4

Código de la cuota seleccionada por el tarjetahabiente en caso haber financiado el pago

cardType

ALFANUMERICO

4

Marca de la tarjeta seleccionada por el tarjetahabiente en caso de haber sido ingresada

cardNumber

NUMERICO

19

Número de tarjeta ingresada por el tarjetahabiente en caso de haber sido ingresada. La devolución de este dato deberá ser autorizada por el adquirente

Parámetros necesarios para obtener los datos del XMLRES Para descifrar el mensaje XMLRES, se deberá configurar al plug-in los valores o campos criptográficos necesarios, así como también para la verificación de la firma digital del mismo. Estos valores se describen a continuación:

Campo

Campo Plug-in

Observaciones

Vector de Inicialización

VectorInicializacion

Valor necesario para el descifrado del mensaje XMLRES. Este valor debe ser generado por el comercio.

Llave pública de

LlavePublicaVerificac Es la llave pública del V-POS con la que se verificará la validez de la firma digital


Firma

ionFirma

del mensaje XMLRES. Esta llave debe ser descargada y almacenada por el comercio.

Llave privada de cifrado

LlavePrivadaCifrado

Es la llave privada con la que se descifrará el mensaje XMLRES. Esta llave es generada y almacenada por el comercio.


INTEGRACIÓN CON EL PLUG-IN El comercio deberá descargar el Componente de seguridad (plug-in) que deberá ser acoplada a su solución Web, para ser activado en el momento de la solicitud final de compra (en general, al presionar el botón “Comprar”). El Componente de seguridad (plug-in) está disponible para los siguientes lenguajes de programación:   

Plug-in .Net (C#) Plug-in .Java Plug-in .PHP

Según la plataforma del comercio, se le proporcionará el plug-in respectivo. Para los detalles de integración ver Anexo correspondiente al lenguaje de programación requerido.


PREGUNTAS Y RESPUESTAS FRECUENTES 

¿Qué lenguajes soporta el Componente de seguridad (plug-in)? En la actualidad el plug-in tiene una versión para cada uno de los siguientes lenguajes: Microsoft .Net (C#), Java y PHP. De acuerdo a la plataforma del sitio Web del comercio, se deberá descargar la versión correspondiente.



El documento describe que los comercios deben generar llaves de encriptación y de firma digital. ¿Cómo será la generación? De forma adicional a la descarga del Componente de seguridad (plug-in), el comercio deberá generar y descargar estas llaves a través del aplicativo V-Admin. Si bien el comercio podrá generar sus llaves públicas y privadas, además del vector de inicialización, al momento de registrar sus llaves sólo se registrarán las llaves publicas del comercio, las llaves privadas deberá ser guardadas de forma aislada y confidencial por el comercio.



El documento describe que debemos intercambiar llaves de encriptación y de firma digital. ¿Cómo será este intercambio? El intercambio de llaves será ejecutado por un canal seguro entre el comercio y Credibanco. Adicional la plataforma proporciona la funcionalidad de descarga directa de estos componentes por parte del comercio.



¿Existe algún carrito de compras comercial que se integre al plug-in? No. En Internet existen varios sitios Web que ofrecen carritos de compras o sitios Web para comercios, pero para realizar la integración se necesita el soporte de un programador o desarrollador para que integre a la plataforma del comercio el código del plug-in.


DATOS ADICIONALES Las llaves especificadas en cada formulario varían de acuerdo al comercio se encuentre, de la misma manera las urls del VPOS.

ambiente en el que el

Se indican las urls según el ambiente en el que el comercio se encuentre: -TESTING URL VPOS: http://172.19.202.5:9080/vpos2/MM/transactionStart20.do

-PRODUCCION URL VPOS: www.ecommerce.credibanco.com


ANEXO 1: INTEGRACIÓN CON EL PLUG-IN PARA .NET C# Instalación del Plug-in C# Al comercio se le entregará una dll VPOS20_PLUGIN.dll que deberá ser acoplada a su solución web, a continuación se presenta los pasos para la integración del plug-in:

2.Examinar 1.Click derecho Agregar referencia

:

3. Escoger VPOS20_PLUGIN .dll y Abrir

o o

Referenciar al plug-in en la carpeta Referencias de la aplicación Web En la ventana Agregar Referencia buscar el componente VPOS20_PLUGIN.dll

Nota: Utilizar el archivo .DLL que se encuentra dentro de la carpeta PLUGIN.


Uso del Plug-in C# para enviar información al V-POS Llaves necesarias para el envío de información:

LLAVE.VPOS.CRB.CRYPTO.1024.PKCS1.txt Llave de cifrado publica del VPOS LlaveFirmaComercioPrivada.txt Llave de firma privada del comercio

A continuación se mostrará un ejemplo de uso del plug-in utilizando C#:

//Asemblies adicionales a usar using System.IO; using VPOS20_PLUGIN;

//Instanciando e inicializando VPOSBean oVPOSBean = new VPOSBean();

string R1 = "C:/LLAVE.VPOS.CRB.CRYPTO.1024.PKCS1.txt"; string R2 = "C:/LlaveFirmaComercioPrivada.txt";

srVPOSLlaveCifradoPublica = new StreamReader(R1); srComercioLlaveFirmaPrivada = new StreamReader(R2);

oVPOSBean.acquirerId = "2";


oVPOSBean.commerceId = "359"; oVPOSBean.purchaseCurrencyCode = "840"; oVPOSBean.purchaseAmount = "100000"; oVPOSBean.purchaseOperationNumber = "40";

// Se invoca a la clase VPPOSend que tiene como parámetros las llaves y el vector de inicialización VPOSSend

oVPOSSend

=

new

VPOSSend(srVPOSLlaveCifradoPublica,

srComercioLlaveFirmaPrivada, "D412589745DF36FA");

oVPOSSend.execute(ref oVPOSBean);

//Recuperando

datos

cifrados,

los

cuales

se

asignan

formulario de envío al VPOS String sCipheredSessionKey = oVPOSBean.cipheredSessionKey; String sCipheredXML = oVPOSBean.cipheredXML; String sCipheredSignature = oVPOSBean.cipheredSignature;

Uso del Plug-in C# para recibir información del V-POS Llaves necesarias para recibir la información: LlaveCifradoComercioPrivada.txt Llave de cifrado privada del comercio LLAVE.VPOS.CRB.SIGN.1024.PKCS1.txt Llave de firma publica del VPOS


al

A continuación se muestra un ejemplo de código implementado en C# para el descifrado de los datos y la verificación de la firma digital:

using System.IO; using System.Collections.Specialized; using VPOS20_PLUGIN;

NameValueCollection coll = new NameValueCollection(); coll = Request.Params; String sIDACQUIRER = coll.Get("IDACQUIRER"); String sIDCOMMERCE = coll.Get("IDCOMMERCE"); String sXMLRES = coll.Get("XMLRES"); String sSESSIONKEY = coll.Get("SESSIONKEY"); String sDIGITALSIGN = coll.Get("DIGITALSIGN");

VPOSBean oVPOSBean = new VPOSBean();

oVPOSBean.cipheredXML = sXMLRES; oVPOSBean.cipheredSessionKey = sSESSIONKEY; oVPOSBean.cipheredSignature = sDIGITALSIGN;

StreamReader

srVPOSLlaveFirmaPublica

=

new

StreamReader("D:/

LLAVE.VPOS.CRB.SIGN.1024.PKCS1.txt"); StreamReader

srComercioLlaveCifradoPrivada


=

new

StreamReader("D:/LlaveCifradoComercioPrivada.txt");

// Se invoca a la clase VPOSReceive que tiene como parámetros las llaves y el vector de inicialización VPOSReceive

oVPOSReceive

=

new

VPOSReceive(srVPOSLlaveFirmaPublica,

srComercioLlaveCifradoPrivada, "D412589745DF36FA"); oVPOSReceive.execute(ref oVPOSBean);

if ( oVPOSBean.validSign == true ) { //El descifrado fue correcto y la firma digital es correcta //Luego evaluar oVPOSBean.authorizationResult para saber si la //transacción fue aceptada o denegada String sAuthResult =oVPOSBean.authorizationResult; String sErrorCode =oVPOSBean.errorCode;

}

Uso del Plug-in C# para enviar información al V-POS y consumo de Web Service Para usar el Plug-In y consumir el Web Service mediante el lenguaje de programación Visual Basic es necesario lo siguiente

1.

Microsoft Visual Basic con Net Framework 2.0, 3.0 ó 3.5.

2.

Contar con las llaves para firmar y el cifrar.


3.

Contar con las DLLs que permitirán construir la petición y consumir el Web Service:

A continuación se mostrará un ejemplo de uso del plug-in utilizando Visual Basic: Agregar la referencia de las DLLs al proyecto: -

Clic derecho sobre la Aplicación y seleccionar la opción “Agregar Referencia”

-

Dentro de la pestaña “Examinar” ubicar las DLLs “Microsoft.Web.Services3.dll” y “VERIFIK_PROTOCOL.dll”, seleccionarlas y luego Aceptar.


Dentro de la programación declarar las variables que van a utilizarse al momento de invocar al Web Service:

Dim rutaLlavePubCifrado As String = "c:\ALIGNET.TESTING.NOPHP.CRYPTO.PUBLIC.txt" Dim rutaLlavePrivFirma As String = "c:\llaveprivadafirmaPSP.txt" Dim rutaLlavePubFirma As String = "c:\ALIGNET.TESTING.NOPHP.SIGNATURE.PUBLIC.txt" Dim rutaLlavePrivCifrado As String = "c:\llaveprivadacifradoPSP.txt" Dim vi As String = "0000000000000000" Dim wsdl As String = "http://172.19.44.41:9081/vpos2/services/VPOS2RESULTTXSOAP/METAINF/VPOS2RESULTTXSOAP.wsdl"

Crear un objeto de tipo VPOSBeanConsulta, el cual va a contener la respuesta al finalizar el proceso:

Dim beanConsulta As New VERIFIK_PROTOCOL.VPOSBeanConsulta

Declarar e inicializar una variable de tipo VPOSConsultaTx, pasándole los parámetros requeridos:


Dim vposConsultaTx As New VERIFIK_PROTOCOL.VPOSConsultaTx("138", "4573", "069467021", rutaLlavePubCifrado, rutaLlavePrivFirma, rutaLlavePubFirma, rutaLlavePrivCifrado, vi, wsdl)

Los parámetros utilizados son los siguientes:

AcquirerId

ID del Adquiriente

CommerceId

ID del Comercio

NumOrder

Número de Orden

RutaLlavePubCifrado

Ruta de la Llave Pública para Cifrado

RutaLlavePrivFirma

Ruta de la Llave Privada para Firma

RutaLlavePubFirma

Ruta de la Llave Pública para Firma

RutaLlavePrivCifrado

Ruta de la Llave Privada para Cifrado

Vi

Vector

Wsdl

Ruta del WSDL

Invocar el método consultaEstadoTx, pasándole como parámetro la variable beanConsulta para ser llenado:

vposConsultaTx.consultaEstadoTx(beanConsulta)

Mostrar el resultado del de la respuesta:


If beanConsulta IsNot Nothing Then MessageBox.Show("acquirerId: " + beanConsulta.acquirerId + vbCrLf + "commerceId: " + beanConsulta.commerceId + vbCrLf + "authorizationResult: " + beanConsulta.authorizationResult + vbCrLf + "authorizationCode: " + beanConsulta.authorizationCode) End If

El objeto de respuesta contiene los siguientes atributos:

AcquirerId

ID del Adquiriente

CommerceId

ID del Comercio

NumOrder

Número de Orden

CipheredSessionKey

Clave cifrada de la sesión

CipheredXML

XML Cifrado

CipheredSignature

Firma cifrada

ClearXML

XML



CIMA - Manual de Integración Boton de Pago CredibanCo #- V1.3 - Oct2013

Recommend Documents