Referencia API SOAP Webpay. Transbank S.A. (V 1.3) Transbank S.A.

Transcripción

1 Referencia API SOAP Webpay Transbank S.A. DOCUMENTO DE ESPECIFI CACIONES TRANSACCIÓN COMPLETA (V 1.3) Transbank S.A. 10/10/2012 0

2 Contenido 1 Control de cambios Prefacio Acerca de esta guía Audiencia Feedback para esta documentación Transacción de Autorización Completa Descripción de la Transacción de Autorización Completa Secuencia de pago en una transacción de autorización completa Descripción de métodos del Servicio Web de Transacción de Autorización Completa Operación initcompletetransaction Operación queryshare Operación autorize Operación acknowledgecompletetransaction Anexo C: Ejemplos de integración con API SOAP Webpay Ejemplo Java Ejemplos PHP Ejemplos.Net Página 1

3 1 Control de cambios Fecha Version Descripción del cambio Liberación inicial de documento general de API de integración con WS Transacción Completa. Futuros Release: Ejemplos de integración PHP,.NET Se agrega ejemplo de integración PHP Se agrega ejemplo C#.Net Se modifica formato de fecha de expiración de tarjeta de crédito de YYMM a YY/MM. 2 Prefacio 2.1 Acerca de esta guía Esta guía describe los aspectos técnicos que deben ser considerados en la integración con Webpay utilizando API SOAP, describe el servicio Web para Transacción de Autorización Completa, sus operaciones y cómo estas deben ser utilizadas en un flujo de pago. Se incluyen ejemplos para cada tipo de transacción Webpay que sirven como guía al utilizar lenguajes Java, C# y PHP. 2.2 Audiencia Esta guía está dirigida a implementadores que realizan la integración de Webpay en comercios utilizando la API SOAP para soportar en estos el pago con tarjetas bancarias tipo transacción completa.. Se recomienda que quién realice la integración posea conocimiento técnico de al menos en los siguientes temas: Servicios Web WS-Security Firma digital, generación y validación. Página 2

4 2.3 Feedback para esta documentación Ayúdanos a mejorar esta información enviándonos comentarios a soporte@webpay.cl Página 3

5 3 Transacción de Autorización Completa 3.1 Descripción de la Transacción de Autorización Completa Una transacción completa de Webpay corresponde a una solicitud de autorización financiera de un pago con tarjetas de crédito, en donde quién realiza el pago ingresa al sitio del comercio, selecciona productos o servicio, y el ingreso asociado a los datos de la tarjeta de crédito lo realiza directamente en el sitio del comercio. Es responsabilidad del comercio proveer de un ambiente seguro para realizar la captura de la información asociada a la tarjeta de crédito, y eliminar dicha información una vez finalizada la transacción. El flujo de páginas para la transacción es el siguiente, notar que todas las páginas son generadas por el comercio: Selección de productos / servicios Ingreso de tarjeta de crédito Selección de cuotas Resultado de transacción. Resumen de los métodos del servicio Web de Transacción Completa 1 Método initcompletetransaction queryshare authorize acknowledgecompletetr ansaction Descripción general Permite inicializar una transacción en Webpay, como respuesta a la invocación se genera un token que representa en forma única una transacción. Es importante considerar que una vez invocado este método, el token que es entregado tiene un periodo reducido de vida de 5 minutos, posterior a esto el token es caducado y no podrá ser utilizado en un pago (la transacción saldrá rechazada). Permite realizar consultas del valor de cuotas (producto nuevas cuotas). Ejecuta la solicitud de autorización, esta puede ser realizada con o sin cuotas. La respuesta entrega el resultado de la transacción. Permite indicar a Webpay que se ha recibido conforme el resultado de la transacción. El método acknowledgecompletetrasaction debe ser invocado siempre, independientemente del resultado entregado por el método authorize. Si la invocación 1 El detalle de los métodos se encuentra en la sección 3.3 Página 4

6 no se realiza en un período de 40 segundos, Webpay reversará la transacción, asumiendo que el comercio no pudo informarse de su resultado, evitando así el cargo al tarjetahabiente. 3.2 Secuencia de pago en una transacción de autorización completa El siguiente diagrama ilustra la secuencia de pago y cómo participan los distintos actores en una transacción completa. sd Secuencia pago completa Comercio Webpay 1. initcompletetransaction() 2. Response() :token... loop [opcional] 3. queryshare(token, buyorder, sharesnumber) 4. Response(queryShareResponse) 5. authorize(token, <List>paymentType) 6. Response() 7. acknowledgecompletetransaction(token) 8. Response() Diagrama de secuencia de Transacción Completa Página 5

7 Descripción de la secuencia: 1. Una vez seleccionado los bienes o servicios en el sitio del comercio, el tarjetahabiente decide pagar a través de Webpay, para lo cual el comercio, en una página segura, solicita al tarjetahabiente los datos asociados a su tarjeta de crédito, e invoca el método initcompletetransaction( ). 2. Webpay procesa el requerimiento y entrega como resultado de la operación el token de la transacción. 3. El comercio debe preguntar a tarjetahabiente el número de cuotas con el cual requiere realizar el pago, si este opta por realizarlo en cuotas, se deberá consultar el valor de la cuota por medio del método queryshare( ). 4. Webpay responde el resultado de la consulta de cuota, entregando el valor de la cuota y si cuenta con la posibilidad de diferir el pago. Nota. Los puntos 3 y 4 pueden repetirse tantas veces como el tarjetahabiente lo desee, hasta que encuentre un número y valor de cuota que le acomode para realizar el pago. La solicitud de autorización debe realizarse con la opción elegida por el tarjetahabiente. 5. El comercio solicita autorización de la transacción, utilizando el método autohrize( ), con la opción de pago en cuotas seleccionada por el tarjetahabiente (pasos 3 y 4). 6. Como respuesta a la invocación del método authorize(), Webpay retorna el resultado de la autorización, la cual puede ser autorizada o rechazada. 7. Para informar a Webpay que el resultado de la transacción se ha recibido sin problemas, el sistema del comercio debe consumir el tercer método acknowledgecompletetrasaction(). NOTA: De no ser consumido ó demorar más de 30 segundos en su consumo, Webpay realizará la reversa de la transacción, asumiendo que existieron problemas de comunicación. 8. El sitio del comercio despliega al tarjeta habiente la página final del pago, donde debe estar incluida la información detallada en el Anexo A del manual Referencia API SOAP Webpay General. Página 6

8 3.3 Descripción de métodos del Servicio Web de Transacción de Autorización Completa A continuación se describen cada uno de las operaciones que deben Transacción Completa. ser utilizadas en una Operación initcompletetransaction Método que permite iniciar una transacción de pago Webpay. Parámetro de entrada: type wscompleteinittransactioninput Nombre transactiontype sessionid Descripción xs:wstransactiontype (Obligatorio) Indica el tipo de transacción, su valor debe ser siempre TR_COMPLETA_WS (Opcional) Identificador de sesión, uso interno de comercio, este valor es devuelto al final de la transacción. carddetails Largo máximo: 61 tns:carddetails (Obligatorio) Objeto del tipo wstransactiondetail que contiene información asociada a la tarjeta de crédito. transactiondetails tns:wstransactiondetail (Obligatorio) Lista de objetos del tipo wstransactiondetail, el cual contiene datos de la transacción. Máxima cantidad de repeticiones es de 1 para este tipo de transacción. Página 7

9 WSTRANSACTIONDETAIL Descripción: Tipo de dato que contiene detalles de la transacción Campo amount Descripción xs:decimal Monto de la transacción. buyorder Largo máximo: 10 Orden de compra del comercio. commercecode Largo máximo: 26 Código comercio de la tienda Largo: 12 CARDDETAILS Descripción: Tipo de dato que contiene detalles tarjeta de crédito Campo cardnumber Descripción Número de la tarjeta. cardexpirationdate Largo máximo: 16 Fecha de expiración de tarjeta, formato YY/MM. cvv Largo: 5 Código de verificación de la tarjeta. Largo máximo: 4 Página 8

10 Parámetros de salida: type wscompleteinittransactionoutput Campo Token Descripción Token de la transacción. Largo: Operación queryshare Método que permite realizar la consulta del valor de una cuota dado el número de cuotas. Parámetros de entrada: queryshareinput Campo Token Descripción Token de la transacción. buyorder Largo: 64 Orden de compra de la transacción. sharenumber Largo: 26 xs:int Número de cuotas. Largo: 2 Página 9

11 Parámetros de salida: queryshareoutput Campo buyorder Descripción Orden de compra de la tienda. deferredperiods Largo máximo: 26 xs:completedeferredperiod Lista de contiene los meses en los cuales se puede diferir el pago, y el monto asociado a cada periodo. queryid xs:long Identificador de la consulta de cuota. shareamount xs:decimal Monto de la cuota. Token Largo máximo: 10 Orden de compra de la tienda. Largo máximo: 64 COMPLETEDEFERREDPERIOD Descripción: Corresponde a un elemento opcional en la respuesta, que dependiendo del tipo de contrato que tenga el comercio podría o no ser retornado. Informa los posibles meses en los cuales se puede diferir un pago y el monto asociado para cada uno. Campo amount Descripción xs:decimal Monto de la cuota con meses diferido. period Largo máximo: 10 xs:int Número de meses en que se difiere el pago. Largo máximo: 1 Página 10

12 3.3.3 Operación autorize Método que permite solicitar la autorización de una transacción. Parámetros de entrada: authorize Campo token Descripción Token de la transacción. paymenttypelist Largo: 64 tns:wscompletepaymenttypeinput (Opcional) Específica para la transacción el número de cuotas con el cual se realizará, si aplicará meses de pago diferido o mes de gracia. Para este caso la lista va con un sólo elemento. WSCOMPLETEPAYMENTTYPEINPUT Descripción: Corresponde a un elemento opcional, específica para la transacción el número de cuotas con el cual se realizará y si aplicará meses de pago diferido. Campo commercecode Descripción xs:decimal Monto de la cuota con meses diferido. buyorder Largo máximo: 10 xs:int Número de meses en que se difiere el pago. queryshareinput graceperiod Largo máximo: 1 tns:wscompletequeryshareinput Indica con qué opción de valor de cuota consultada se realizará la transacción. xs:boolean Flag que indica si aplica o no periodo de gracia, valor en true indica que aplica, en false indica que no aplica. Este flag es válido solamente para ventas sin cuota. Página 11

13 WSCOMPLETEQUERYSHAREINPUT Descripción: Corresponde a un elemento opcional, específica para la transacción el número de cuotas con el cual se realizará y si aplicará meses de pago diferido. Campo idqueryshare deferredperiodindex Descripción xs:long Identificador de la consulta de cuotas. Este dato es el entregado por el método de consulta de cuotas. xs:int (Opcional) Identificador del período diferido con el cual se desea realizar el pago. (Número del período)(campo period del objeto completedeferredperiod) Parámetros de salida: wscompleteauthorizeoutput Campo accountingdate Descripción Fecha contable de la autorización de la transacción, la cual más el desfase de abono indica al comercio la fecha en que Transbank abonará al comercio. buyorder Largo: 4, formato MMDD Orden de compra de la tienda. detailsoutput sessionid Largo máximo: 26 tns:wstransactiondetailoutput Contiene los detalles de la transacción Identificador de sesión, uso interno de comercio, este valor es devuelto al final de la transacción. Un uso posible puede ser la representación del intento de pago. transactiondate Largo máximo: 61 Fecha y hora de la autorización. Largo: 8 Página 12

14 WSTRANSACTIONDETAILOUTPUT Campo authorizationcode Descripción Código de autorización de la transacción paymenttypecode responsecode amount Largo máximo: 6 Tipo de pago de la transacción. Código de respuesta de la autorización. Valores posibles: 0 Transacción aprobada. -1 Rechazo de transacción. -2 Transacción debe reintentarse. -3 Error en transacción. -4 Rechazo de transacción. -5 Rechazo por error de tasa. -6 Excede cupo máximo mensual. -7 Excede límite diario por transacción. -8 Rubro no autorizado. xs:decimal Monto de la transacción. sharesamount Largo máximo: 10 xs:decimal Valor de la cuota. sharesnumber Largo máximo: 9 xs:int Cantidad de cuotas commercecode Largo máximo: 2 Código comercio de la tienda buyorder Largo: 12 Orden de compra de la tienda. Largo máximo: 26 Página 13

15 3.3.4 Operación acknowledgecompletetransaction Método que permite informar a Webpay la correcta recepción del resultado de la transacción. Parámetros de entrada: Campo tokeninput Descripción Token de la transacción. Largo: 64 Página 14

16 4 Anexo C: Ejemplos de integración con API SOAP Webpay Los siguientes ejemplos tienen por objetivo exponer una forma factible de integración con API SOAP Webpay para resolver los siguientes puntos asociados a la integración: 1. Generación de cliente o herramienta para consumir los servicios Web, lo cual permite abstraerse de la complejidad de mensajería SOAP asociada a los Webservice y hacer uso de las operaciones del servicio. 2. Firma del mensaje y validación de firma en la respuesta, existen frameworks y herramientas asociadas a cada lenguaje de programación que implementan el estándar WS Security, lo que se requiere es utilizar una de estas, configurarla y que realice el proceso de firma digital del mensaje. Página 15

17 4.1 Ejemplo Java Este ejemplo hará uso de los siguientes frameworks para consumir los servicios Web de Webpay utilizando WS Security: Apache CXF, es un framewok open source que ayuda a construir y consumir servicios Web en Java. En este ejemplo se utilizará para: o o Generar el cliente del Webservice o STUBS. Consumir los servicios Web Apache WSS4J, proporciona la implementación del estándar WS Security, nos permitirá: o o Firmar los mensajes SOAP antes de enviarlo a Webpay. Validar la firma de la respuesta del servicio Web de Webpay. Spring framewok 3.0, permite que CXF y WSS4J trabajen en conjunto, también se utiliza para configurar WS Security en la firma del mensaje SOAP. Pasos a seguir: 1. Generación de cliente del Webservice. Para generar el código Java que implementará el cliente SOAP se utilizará wsdl2java de CXF, el cual toma el WSDL del servicio y genera todas las clases necesarias para invocar el servicio Web. Más información en wsdl2java -autonameresolution <URL del wsdl> Página 16

18 2. Configuración de WS Security Para configurar WS Security en CXF se deben habilitar y configurar los interceptores que realizaran el trabajo de firmado del mensaje. La configuración de los interceptores se puede realizar a través de la API de servicios Web o a través del XML de configuración de Spring, en este caso se realizará a través de Spring en el archivo applicationcontext.xml de la aplicación. Se deben habilitar y configurar 2 interceptores, uno para realizar la firma de los mensajes enviados al invocar una operación del servicio Web de Webpay y otro para validar la firma de la respuesta del servicio Web. Interceptor de salida <bean class="org.apache.cxf.ws.security.wss4j.wss4joutinterceptor" id="signoutrequestinterceptor"> <constructor-arg> <map> <entry key="signaturepropfile" value="signatureout.properties"/> <entry key="user" value="$alias.client"/> <entry key="action" value="signature"/> <entry key="passwordcallbackclass" value="com.transbank.webpay.wsse.clientcallback"/> <entry key="signatureparts" value="elementhttp://schemas.xmlsoap.org/soap/envelope/body"/> </map> </constructor-arg> </bean> Interceptor de entrada <bean class="org.apache.cxf.ws.security.wss4j.wss4jininterceptor" id="signinrequestinterceptor"> <constructor-arg> <map> <entry key="action" value="signature" /> <entry key="signaturepropfile" value="signaturein.properties"/> <entry key="passwordcallbackclass" value="com.transbank.webpay.wsse.servercallback"/> <entry key="signatureparts" value="elementhttp://schemas.xmlsoap.org/soap/envelope/body"/> </map> </constructor-arg> </bean> Las clases ClientCallback y ServerCallBack implementan la interfaz javax.security.auth.callback.callbackhandler, su implementación permite al framework de seguridad recuperar la contraseña para acceder al almacen de llaves de la aplicación (Java Key Store) que almacena los certificados digitales. Página 17

19 3. Llamada a operaciones del Webservice Operación initcompletetransaction private WSCompleteWebpayService service; private WsTransactionDetailOutput detailoutput; WsCompleteInitTransactionInput input = new WsCompleteInitTransactionInput(); input.setsessionid( ); input.settransactiontype(wscompletetransactiontype.tr_completa_ws); WsCompleteTransactionDetail detail = new WsCompleteTransactionDetail(); detail.setamount(100); detail.setbuyorder( OC_PRUEBA ); detail.setcommercecode( ); input.gettransactiondetails().add(detail); CompleteCardDetail carddetail = new CompleteCardDetail(); carddetail.setcardexpirationdate( 13/04 ); carddetail.setcvv( 123 ); carddetail.setcardnumber( ); input.setcarddetail(carddetail); WsCompleteInitTransactionOutput output = service.initcompletetransaction(input); token = output.gettoken(); Operación queryshare private WSCompleteWebpayService service; WsCompleteQuerySharesOutput output = service.queryshare(token, OC_PRUEBA, 7); queryid = output.getqueryid(); shareamount = output.getshareamount(); deferredperiods = output.getdeferredperiods(); Operación authorize (Sin cuotas) Página 18 WsCompletePaymentTypeInput paymenttype = new WsCompletePaymentTypeInput(); paymenttype.setbuyorder( OC_PRUEBA ); paymenttype.setcommercecode( ); //Si se quiere período de gracia dejar en true paymenttype.setgraceperiod(false); List<WsCompletePaymentTypeInput> paymenttypelist = new ArrayList<WsCompletePaymentTypeInput>(); paymenttypelist.add(paymenttype); WsCompleteAuthorizeOutput authorizeoutput =

20 service.authorize(token, paymenttypelist); accountingdate = authorizeoutput.getaccountingdate(); transactiondate = authorizeoutput.gettransactiondate(); detailoutput = authorizeoutput.getdetailsoutput().get(0); Página 19

21 Operación authorize (Usando cuotas) WsCompletePaymentTypeInput paymenttype = new WsCompletePaymentTypeInput(); paymenttype.setbuyorder("oc_prueba"); paymenttype.setcommercecode(" "); WsCompleteQueryShareInput queryshareinput = new WsCompleteQueryShareInput(); queryshareinput.setidqueryshare(queryid); queryshareinput.setdeferredperiodindex(1); paymenttype.setqueryshareinput(queryshareinput); List<WsCompletePaymentTypeInput> paymenttypelist = new ArrayList<WsCompletePaymentTypeInput>(); paymenttypelist.add(paymenttype); WsCompleteAuthorizeOutput authorizeoutput = service.authorize(token,paymenttypelist); accountingdate = authorizeoutput.getaccountingdate(); transactiondate = authorizeoutput.gettransactiondate(); detailoutput = authorizeoutput.getdetailsoutput().get(0); Operación acknowledgecompletetransaction private WSCompleteWebpayService service; service.acknowledgecompletetransaction(token); URL: Página 20

22 4.2 Ejemplos PHP El siguiente ejemplo está basado en PHP versión 5, sobre el cual se utilizaron las siguientes bibliotecas de software para realizar la invocación de los servicios web de Webpay bajo el estándar WSS: Biblioteca de seguridad: archivo compuesto de tres clases que integran librerías nativas PHP de validación y verificación. Estas clases nos permitirán generar la seguridad suficiente a través de métodos de encriptación y desencriptación. WSSE-PHP: integra las librerías de seguridad XML y genera un documento XML-SOAP seguro. Depende de las librerías de seguridad XML. SOAP-VALIDATION: clase encargada de la validación de mensajes SOAP seguros de respuesta. Verifica la autenticidad e integridad del mensaje. Depende de WSSE-PHP. Los fuentes pueden ser descargados desde Pasos a seguir: 1. Generación de cliente del Servicio Web: Antes de la integración se debe tener instalado y funcionando un servidor HTTP Apache y configurar el directorio para generar una salida a través del navegador web. Si se quiere optar por una alternativa más sencilla, Apache provee un directorio por omisión, que varía según el sistema operativo. Generalmente en plataformas Linux es /var/www y en Windows C:\<directorio hacia Apache>/htdocs. A continuación, para generar las clases necesarias que conectan a los servicios Web, se puede utilizar la herramienta Easy WSDL2PHP. La documentación necesaria e información de descarga se encuentra en Una vez descargados los fuentes, se deben copiar en el directorio de apache que posee la salida por navegador. Se hace la llamada por navegador del archivo wsdl2php.php y se obtiene la siguiente pantalla: Página 21

23 Se escribe la URL del archivo wsdl al se quiere conectar, un nombre de clase y luego se presiona el botón Generate Code. Luego de esto se muestra una pantalla como la siguiente: Una vez que se obtiene el resultado mostrado en la imagen se copia el código PHP generado y se guarda en un archivo, el cual representará el stub del servicio Web. Una vez realizado este proceso ya se tienen las clases necesarias para poder integrarse con los servicios web de Webpay. Página 22

24 2. Crear una clase que extienda de SoapClient (SoapClient es la clase nativa que provee PHP para utilización de servicios Web)(En el ejemplo se denominará MySoap) //Notar que se incluyen dos archivos que se proveen en la librería de encriptación require_once('xmlseclibs.php'); require_once('soap-wsse.php'); class MySoap extends SoapClient function dorequest($request, $location, $saction, $version) $doc = new DOMDocument('1.0'); $doc->loadxml($request); $objwsse = new WSSESoap($doc); $objkey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA1,array('type' => 'private')); $objkey->loadkey(private_key, TRUE); $options = array("insertbefore" => TRUE); $objwsse->signsoapdoc($objkey, $options); $objwsse->addissuerserial(cert_file); $objkey = new XMLSecurityKey(XMLSecurityKey::AES256_CBC); $objkey->generatesessionkey(); $retval = parent:: dorequest($objwsse->savexml(), $location, $saction, $version); $doc = new DOMDocument(); $doc->loadxml($retval); return $doc->savexml(); Las constantes PRIVATE_KEY Y CERT_FILE son las rutas de la llave privada y certificado del comercio, respectivamente. 3. Incluir la clase generada en el paso anterior en el archivo principal de los servicios. Se debe incluir con la sentencia require_once la clase generada en el paso anterior. Ejemplo: require_once( mysoap.php ); Página 23

25 4. Editar el archivo stub creado en el paso 1 Se debe editar el método contruct del stub tal como se muestra en el ejemplo: Donde dice: $this->soapclient = new SoapClient($url, array("classmap" => self::$classmap, "trace" => true, "exceptions" => true)); Debe quedar: (utilizando el nombre de clase del paso 2) $this->soapclient = new MySoap($url, array("classmap" => self::$classmap, "trace" => true, "exceptions" => true)); 5. Invocación de operaciones del servicio web de Webpay. Para todos los ejemplos se debe hacer referencia a los archivos de la librería descargada require_once('soap-wsse.php'); require_once('soap-validation.php'); require_once('<archivo que contiene la clase stub creado en el paso 1>'); Operación initcompletetransaction: $wscompleteinittransactioninput = new wscompleteinittransactioninput(); $completecarddetail = new completecarddetail(); $wscompletetransactiondetail = new wscompletetransactiondetail(); $wscompleteinittransactioninput->transactiontype = $transactiontype; $wscompleteinittransactioninput->sessionid = $sessionid; $wscompletetransactiondetail->amount = $amount; $wscompletetransactiondetail->buyorder = $buyorder; $wscompletetransactiondetail->commercecode = $commercecode; $completecarddetail->cardexpirationdate = $cardexpirationdate; $completecarddetail->cvv = $cvv; $completecarddetail->cardnumber = $cardnumber; $wscompleteinittransactioninput->commerceid = $commercecode; $wscompleteinittransactioninput->buyorder = $wscompletetransactiondetail- >buyorder; $wscompleteinittransactioninput->carddetail = $completecarddetail; $wscompleteinittransactioninput->transactiondetails = $wscompletetransactiondetail; $webpaycompleteservice = new WSCompleteWebpayService($url_wsdl_complete); $initcompletetransaction = new initcompletetransaction(); Página 24

26 $initcompletetransaction->wscompleteinittransactioninput = $wscompleteinittransactioninput; $initcompletetransactionresponse = $webpaycompleteservice- >initcompletetransaction( $initcompletetransaction ); $xmlresponse = $webpaycompleteservice->soapclient-> getlastresponse(); $soapvalidation = new SoapValidation($xmlResponse, SERVER_CERT); $validationresult = $soapvalidation->getvalidationresult(); $wscompleteinittransactionoutput = $initcompletetransactionresponse->return; Operación queryshare: $webpaycompleteservice = new WSCompleteWebpayService($url_wsdl_complete); $queryshare = new queryshare(); $queryshare->token = $_POST['token_ws']; $queryshare->buyorder = $buyorder; $queryshare->sharenumber = $sharenumber; $queryshareresponse = $webpaycompleteservice->queryshare($queryshare); $xmlresponse = $webpaycompleteservice->soapclient-> getlastresponse(); $soapvalidation = new SoapValidation($xmlResponse, SERVER_CERT); $validationresult = $soapvalidation->getvalidationresult(); $queryshareoutput = $queryshareresponse->return; Página 25

27 Operación authorize: $webpaycompleteservice = new WSCompleteWebpayService($url_wsdl_complete); $authorize = new authorize(); $wscompletepaymenttypeinput = new wscompletepaymenttypeinput(); $wscompletequeryshareinput = new wscompletequeryshareinput(); $authorize->token = $_POST['token_ws']; $wscompletepaymenttypeinput->buyorder = $buyorder; $wscompletepaymenttypeinput->commercecode = $commercecode; $wscompletepaymenttypeinput->graceperiod = $graceperiod; $wscompletequeryshareinput->idqueryshare = $idqueryshare; $wscompletequeryshareinput->deferredperiodindex = $deferredperiodindex; $wscompletepaymenttypeinput->queryshareinput = $wscompletequeryshareinput; $authorize->paymenttypelist = $wscompletepaymenttypeinput; $authorizeresponse = $webpaycompleteservice->authorize($authorize); $xmlresponse = $webpaycompleteservice->soapclient-> getlastresponse(); $soapvalidation = new SoapValidation($xmlResponse, SERVER_CERT); $validationresult = $soapvalidation->getvalidationresult(); $authorizeoutput = $authorizeresponse->return; Operación acknowledgecompletetransaction: $webpaycompleteservice = new WSCompleteWebpayService($url_wsdl_complete); $acknowledgecompletetransaction = new acknowledgecompletetransaction(); $acknowledgecompletetransaction->tokeninput = $token; $acknowledgetransactionresponse=$webpaycompleteservice- >acknowledgecompletetransaction( $acknowledgecompletetransaction ); $xmlresponse = $webpaycompleteservice->soapclient-> getlastresponse(); $soapvalidation = new SoapValidation($xmlResponse, SERVER_CERT); $validationresult = $soapvalidation->getvalidationresult(); Página 26

28 4.3 Ejemplos.Net Este ejemplo hará uso de los siguientes frameworks y componentes para consumir los servicios Web de Webpay utilizando WS Security: Microsoft.NET 4.0, es un framework de Microsoft que permite la independencia de hardware e integra todos sus productos desde el sistema operativo hasta las herramientas de mercado. o Soporte y Core para el desarrollo e implementación Web Services Enhancements 3.0, proporciona la implementación para desarrollo de Web Service e interoperabilidad con otros sistemas. o o Generar el cliente del WebService o Proxy Consumir los servicios Web Componente Intergrup.Core4.Soap.dll Componente para validación y firma digital para WS Security. Estos componentes representan una posible solución al problema del no soporte nativo de WSS en.net IMPORTANTE. Se debe tener presente que el framework WSE 3.0 no es compatible en su totalidad con WS Security, requiere de algunas adaptaciones. Entre estas adaptaciones se encuentra la validación de firma digital sobre el XML de SOAP del WSE. La firma que se exige en el consumo del servicio Web se debe realizar sobre el body del XML, el cual debe ser marcado con un ID, es este caso el ID lleva un prefijo impuesto por la definición de WSS, WSE 3.0 no permite validar la firma sobre elementos cuyo identificado de referencia presenta un prefijo. Una posible solución se presenta en el sitio StackOverflow, en donde se plantea una forma de sobrescribir el método GetIdElement de la subclase System.Security.Cryptography.Xml.SignedXml, que es utilizada al momento de firmar y validar firmas digitales con el método nativo ComputeSignature. Nota: WSE 3.0 puede ser utilizado también con Framework.NET 2.0 y 3.5 respectivamente Página 27

29 Pasos a seguir: 1. Generación de cliente del Webservice. Para generar el código.net que implementará el cliente SOAP se utilizará wsewsdl3 de WSE 3.0, el cual toma el WSDL del servicio y genera todas las clases necesarias para invocar el servicio Web. wsewsdl3 <URL del wsdl> /language:c# /namespace:<opcional> /type:webclient Nota: Una vez instalado WSE 3.0 en Windows puede ser encontrado en C:\Program Files\Microsoft WSE\v3.0\Tools 2. Configuración de WS Security Para configurar WS Security en WSE 3.0 se implementó un conjunto de clases para definir y personalizar clases que entreguen el soporte para WS Security. Nota: La personalización de clases está definido dentro de WSE 3.0 para lograr la interoperabilidad entre sistemas. o CustomPolicyAssertion: esta clase permite crear una Política para Assertion, donde podemos capturar el Mensaje SOAP de Request y Response respectivamente. Esto realizado a través de filtros: o o ClientOutputFilter (Interceptor Salida): permite definir y personalizar el mensaje de Response hacia el servicio. Dentro de esta clase es interceptado el mensaje Soap y se realiza la firma digital. ClientInputFilter (Interceptor de Entrada): permite definir y personalizar el mensaje de Request hacia el servicio. Dentro de esta clase es interceptado el mensaje SOAP y se realiza la validación de firma digital con la llave pública del certificado. Página 28

30 Definición de política de proceso public class CustomPolicyAssertion : PolicyAssertion private String issuernamecertificate = null; public CustomPolicyAssertion(String issuernamecertificate) : base() this.issuernamecertificate = issuernamecertificate; public override SoapFilter CreateClientInputFilter( FilterCreationContext context) return new ClientInputFilter(); public override SoapFilter CreateClientOutputFilter( FilterCreationContext context) return new ClientOutputFilter(this.issuerNameCertificate); public override SoapFilter CreateServiceInputFilter( FilterCreationContext context) return null; public override SoapFilter CreateServiceOutputFilter( FilterCreationContext context) return null; public override IEnumerable< KeyValuePair<string, Type>> GetExtensions() return new KeyValuePair<string, Type>[] new KeyValuePair<string, Type>("CustomPolicyAssertion", this.gettype()) ; public override void ReadXml(XmlReader reader, IDictionary<string, Type> extensions) reader.readstartelement("custompolicyassertion"); La creación de una política permite definir al stub o proxy cómo activar los interceptores para envió o recepción de mensaje SOAP al consumir un WebService. Esto es permite en WSE 3.0 a modo de Custom de los objetos para lograr la interoperabilidad. Página 29

31 Interceptor de salida public class ClientOutputFilter : SoapFilter private String issuernamecertificate = null; public ClientOutputFilter(String issuernamecertificate) : base() this.issuernamecertificate = issuernamecertificate; public override SoapFilterResult ProcessMessage(SoapEnvelope envelope) WSSecuritySignature<SoapEnvelope, X509Certificate2> signed = new WSSecuritySignature<SoapEnvelope, X509Certificate2>(); String issuername = HelperSetting.GetSetting(this.issuerNameCertificate); X509Certificate2 certificate = HelperCertificate.GetCertificate(issuerName); signed.signature(envelope, certificate); return SoapFilterResult.Continue; Se rescata el certificado digital del comercio y se procede a la firma digital. El componente de firma digital para WS Security se encuentra en la clase WSSecuritySignature. Página 30

32 Interceptor de Entrada public class ClientInputFilter:SoapFilter public override SoapFilterResult ProcessMessage(SoapEnvelope envelope) WSSecuritySignature<SoapEnvelope, X509Certificate2> signed = new WSSecuritySignature<SoapEnvelope, X509Certificate2>(); String issuername = HelperSetting.GetSetting(Constant.ISSUER_NAME_CERTIFICATE_SERVER); X509Certificate2 certificate = HelperCertificate.GetCertificate(issuerName); if (signed.checksignature(envelope, certificate)) return SoapFilterResult.Continue; return SoapFilterResult.Terminate; Se rescata el certificado digital del servidor (llave pública) y se procede a la validación de firma digital. Nota: los certificados digitales son almacenados en el Store de Windows para certificados digital y desde este repositorio son obtenidos mediante IssuerName o número del comercio. Página 31

33 Llamada a operaciones del Webservice Operación initcompletetransaction wscompleteinittransactioninput inittransaction = new wscompleteinittransactioninput(); inittransaction.transactiontype = wscompletetransactiontype.tr_completa_ws; inittransaction.sessionid = ; inittransaction.buyorder = OC ; inittransaction.commerceid = ; inittransaction.carddetail = new completecarddetail cardexpirationdate= 13/06, cardnumber= , cvv= 1234 ; inittransaction.transactiondetails = new wscompletetransactiondetail[] new wscompletetransactiondetail() ; wscompletetransactiondetail transactiondetail=inittransaction.transactiondetails[0] as wscompletetransactiondetail; transactiondetail.amount=convert.todecimal(txtamount.text); transactiondetail.buyorder = txtbuyorder.text; transactiondetail.commercecode = txtcommercecode.text; wscompleteinittransactionoutput result = null; using (WSWebpayServiceImplService proxy = new WSWebpayServiceImplService()) /*Define el ENDPOINT del Web Service Webpay*/ proxy.url = ; Policy mypolicy = new Policy(); CustomPolicyAssertion custompolicty = new CustomPolicyAssertion(); mypolicy.assertions.add(custompolicty); proxy.setpolicy(mypolicy); proxy.timeout = 60000; proxy.usedefaultcredentials = false; result = proxy.initcompletetransaction(inittransaction); /*Token de resultado*/ String token=result.token; Página 32

34 Operación queryshare wscompletequerysharesoutput result = null; String token= ; // Definir Token String buyorder= OC_PRUEBA ; Int sharenumber=7; using (WSWebpayServiceImplService proxy = new WSWebpayServiceImplService()) /*Define el ENDPOINT del Web Service Webpay*/ proxy.url = ; Policy mypolicy = new Policy(); CustomPolicyAssertion custompolicty = new CustomPolicyAssertion(); mypolicy.assertions.add(custompolicty); proxy.setpolicy(mypolicy); proxy.timeout = 60000; proxy.usedefaultcredentials = false; result = proxy.queryshare(token, buyorder, sharenumber); /*Resultado*/ Int64 queryid = result. queryid; Decimal shareamount = result.shareamount; completedeferredperiod[] deferredperiods = result.deferredperiods; Página 33

35 Operación authorize (Sin cuotas) String token= ; wscompletepaymenttypeinput paymenttype = new wscompletepaymenttypeinput(); paymenttype.buyorder= OC123 ; paymenttype.commercecode=" "; //Si se quiere período de gracia dejar en true paymenttype.graceperiod=false; wscompletepaymenttypeinput[] payments = new wscompletepaymenttypeinput[] paymenttype ; using (WSWebpayServiceImplService proxy = new WSWebpayServiceImplService()) /*Define el ENDPOINT del Web Service Webpay*/ proxy.url = ; Policy mypolicy = new Policy(); CustomPolicyAssertion custompolicty = new CustomPolicyAssertion(); mypolicy.assertions.add(custompolicty); proxy.setpolicy(mypolicy); proxy.timeout = 60000; proxy.usedefaultcredentials = false; result = proxy.authorize(token, payments); /*Resultado*/ accountingdate = authorizeoutput.accountingdate; transactiondate = authorizeoutput.transactiondate; detailoutput = authorizeoutput.detailsoutput[0]; Página 34

36 Operación authorize (Usando cuotas) String token= ; wscompletepaymenttypeinput paymenttype = new wscompletepaymenttypeinput(); paymenttype.buyorder= OC123 ; paymenttype.commercecode=" "; wscompletequeryshareinput queryshareinput = new wscompletequeryshareinput(); queryshareinput.idqueryshare=convert.toint64( ); queryshareinput.deferredperiodindex=1; paymenttype.queryshareinput=queryshareinput; wscompletepaymenttypeinput[] payments = new wscompletepaymenttypeinput[] paymenttype ; using (WSWebpayServiceImplService proxy = new WSWebpayServiceImplService()) /*Define el ENDPOINT del Web Service Webpay*/ proxy.url = ; Policy mypolicy = new Policy(); CustomPolicyAssertion custompolicty = new CustomPolicyAssertion(); mypolicy.assertions.add(custompolicty); proxy.setpolicy(mypolicy); proxy.timeout = 60000; proxy.usedefaultcredentials = false; result = proxy.authorize(token, payments); /*Resultado*/ accountingdate = authorizeoutput.accountingdate; transactiondate = authorizeoutput.transactiondate; detailoutput = authorizeoutput.detailsoutput[0]; Página 35

37 Operación acknowledgecompletetransaction String token= Valor Token ; using (WSWebpayServiceImplService proxy = new WSWebpayServiceImplService()) /*Define el ENDPOINT del Web Service Webpay*/ proxy.url = ; Policy mypolicy = new Policy(); CustomPolicyAssertion custompolicty = new CustomPolicyAssertion(); mypolicy.assertions.add(custompolicty); proxy.setpolicy(mypolicy); proxy.timeout = 60000; proxy.usedefaultcredentials = false; proxy.acknowledgecompletetransaction(token); Referencias: WSE 3.0: Framework.NET 4.0: Herramienta wsewsdl3 para generación de proxy Componente Intergrup.Core4.Soap.dll Web Services Security X.509 Certificate Token Profile StackOverflow, firma en elementos con ID que utilizan prefijos. Página 36