CIMA - Manual de Integración Boton de Pago CredibanCo #- V1.3 - Oct2013
Short Description
Download CIMA - Manual de Integración Boton de Pago CredibanCo #- V1.3 - Oct2013...
Description
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
Maunal de Integración API Credibanco– Julio de 2013 P 1/ 43
HISTORIA DE REVISIONES Fecha
Versión
1.0
Generación del documento
Descripción
Credibanco
1.1
Ajustes de Alignet
Credibanco
1.2 1.3
Ajustes inclusion nuevos campos Aclaración campos
Credibanco Credibanco
Maunal de Integración API Credibanco– Julio de 2013 P 2/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 3/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 5/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 6/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 7/ 43
Figura 5: Página de resultado del comercio
Maunal de Integración API Credibanco– Julio de 2013 P 8/ 43
¿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
Maunal de Integración API Credibanco– Julio de 2013 P 9/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 10/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 11/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 13/ 43
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:
Maunal de Integración API Credibanco– Julio de 2013 P 14/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 17/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 18/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 19/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 22/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 23/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 24/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 27/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 28/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 29/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 30/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 31/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 32/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 33/ 43
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";
Maunal de Integración API Credibanco– Julio de 2013 P 34/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 35/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 36/ 43
=
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.
Maunal de Integración API Credibanco– Julio de 2013 P 37/ 43
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.
Maunal de Integración API Credibanco– Julio de 2013 P 38/ 43
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:
Maunal de Integración API Credibanco– Julio de 2013 P 39/ 43
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:
Maunal de Integración API Credibanco– Julio de 2013 P 40/ 43
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
Maunal de Integración API Credibanco– Julio de 2013 P 41/ 43
Maunal de Integración API Credibanco– Julio de 2013 P 42/ 43
View more...
Comments
