Referencia API

SOAP Webpay
Transbank S.A.
D OCUMENTO DE ESPECIFI CACIONES TRANSACCIN P AT P ASS
BY W EBPAY ( V 1.3)

Transbank S.A.
10/10/2012

Contenido
1

Control de cambios ..................................................................................................................... 2

Prefacio ....................................................................................................................................... 2

2.1

Acerca de esta gua ............................................................................................................. 2

2.2

Audiencia ............................................................................................................................. 2

2.3

Feedback para esta documentacin ................................................................................... 2

Transaccin de Autorizacin PatPass by WebpayPatPass by Webpay ....................................... 3

3.1

Descripcin de la transaccin.............................................................................................. 3

3.2

Secuencia de pago en una transaccin PatPass by Webpay ............................................... 4

3.3

Descripcin de mtodos asociados a Servicio Web de PatPass by Webpay ....................... 7

3.3.1

Operacin initTransaction .......................................................................................... 7

3.3.2

Operacin getTransactionResult .............................................................................. 11

3.3.3

Operacin acknowledgeTrasaction .......................................................................... 14

Anexo C: Ejemplos de integracin con API SOAP Webpay ....................................................... 15

4.1

Ejemplo Java ...................................................................................................................... 16

4.2

Ejemplos PHP .................................................................................................................... 20

4.3

Ejemplos .Net .................................................................................................................... 27

Pgina 1

1 Control de cambios
Fecha
12-12-12

Versin
1.0

09-01-13
22-01-13
28-01-13

1.1
1.2
1.3

Descripcin del cambio

Liberacin inicial de documento general de API de integracin con WS
Transaccin Patpass by Webpay.
Futuros Release:
Ejemplos de integracin Java, PHP y .NET.
Se incorporan ejemplo de Java y PHP
Se mejora ejemplo PHP.
Se agregan ejemplos .Net

2 Prefacio
2.1 Acerca de esta gua
Esta gua describe los aspectos tcnicos que deben ser considerados en la integracin con Webpay
utilizando API SOAP, describe el servicio Web para PatPass by Webpay, sus operaciones y cmo
estas deben ser utilizadas en un flujo de pago. Se incluyen ejemplos que sirven como gua al
utilizar lenguajes Java, C# y PHP.

2.2 Audiencia
Esta gua est dirigida a implementadores que realizan la integracin de Webpay en comercios
utilizando la API SOAP para soportar en estos el pago con tarjetas bancarias.
Se recomienda que quin realice la integracin posea conocimiento tcnico de al menos en los
siguientes temas:

Servicios Web
WS-Security
Firma digital, generacin y validacin.

2.3 Feedback para esta documentacin

Aydanos a mejorar esta informacin envindonos comentarios a [email protected]

Pgina 2

3 Transaccin de Autorizacin PatPass by WebpayPatPass

by Webpay
3.1 Descripcin de la transaccin
Una transaccin de autorizacin de PatPass by Webpay corresponde a una solicitud de inscripcin
de pago recurrente con tarjetas de crdito, en donde el primer pago se resuelve al instante, y los
subsiguientes quedan programados para ser ejecutados mes a mes. PatPass by Webpay cuenta
con fecha de caducidad o termino, la cual debe ser proporcionada junto a otros datos para esta
transaccin. La transaccin puede ser realizada en Dlares y Pesos, para este ltimo caso es
posible enviar el monto en UF y Webpay realizar la conversin a pesos al momento de realizar el
cargo al tarjetahabiente.
El flujo pginas para la transaccin es el siguiente:
Sitio del
Comercio

Webpay
Formulario
de Pago

Autenticacin
en Banco
Emisor

Sitio del
Comercio

Webpay
Comprobante
de pago

Sitio del
Comercio

.
Resumen mtodos del servicio Web de Transaccin PatPass by Webpay
Mtodo
initTransaction

Descripcin general
Permite inicializar una transaccin de PatPass by Webpay, como
respuesta a la invocacin se genera un token que representa en
forma nica una transaccin.
Es importante considerar que una vez invocado este mtodo, el
token que es entregado tiene un periodo reducido de vida de 5
minutos, posterior a esto el token es caducado.

getAuthorizationResult

Permite obtener el resultado de la transaccin una vez Webpay

ha resuelto su autorizacin financiera.

acknowledgeTrasaction

Permite indicar a Webpay que se ha recibido conforme el

resultado de la transaccin.

Pgina 3

El mtodo acknowledgeTrasaction debe ser invocado

siempre, independientemente del resultado entregado
por el mtodo getAuthorizationResult. Si la invocacin
no se realiza en un perodo de 60 segundos, Webpay reversar la
transaccin, asumiendo que el comercio no pudo informarse de
su resultado, evitando as el cobro al tarjetahabiente.

3.2 Secuencia de pago en una transaccin PatPass by Webpay

El siguiente diagrama ilustra la secuencia de pago y cmo participan los distintos actores en una
transaccin normal.
sd Secuencia pago WPM
Comercio

Webpay

Tarjetahabiente

1. Pagar con Webpay()

2. initTransaction()
3. Response() :token...
4. Redirect(token...)
5. Request(token)
6. Response() :Formulario Webpay
8. autoriza e inscribe
PatPASS()

7. Pagar()
9. Redirect()

10. Request(token)
11. getAuthorizationResult(token...)
12. Response()
13. acknow ledgeTransaction(token)
14. Redirect(token)
15. Request(token)
16. Response(token) :Comprobante Webpay
17. Request(token)
18. Response(token) :Pagina Final

Diagrama de secuencia de Transaccin PatPass by Webpay

Pgina 4

Descripcin de la secuencia:
1. Una vez seleccionado los bienes o servicios, tarjetahabiente decide pagar a travs de
Webpay.
2. El comercio inicia una transaccin en Webpay, invocando el mtodo initTransaction().
3. Webpay procesa el requerimiento y entrega como resultado de la operacin el token de la
transaccin y URL de redireccionamiento a la cual se deber redirigir al tarjetahabiente.
4. Comercio redirecciona al tarjetahabiente hacia Webpay, con el token de la transaccin a la
URL indicada en punto 3. La redireccin se realiza enviando por mtodo POST el token en
variable token_ws.
5. El navegador Web del tarjetahabiente realiza una peticin HTTPS a Webpay, en base al
redireccionamiento generado por el comercio en el punto 4.
6. Webpay responde al requerimiento desplegando el formulario de pago de Webpay. Desde
este punto la comunicacin es entre Webpay y el tarjetahabiente, sin interferir el
comercio. El formulario de pago de Webpay despliega, entre otras cosas, el monto de la
transaccin, informacin del comercio como nombre y logotipo, las opciones de pago a
travs de crdito.
7. Tarjetahabiente ingresa los datos de la tarjeta, hace clic en pagar en formulario Webpay.
8. Webpay procesa la solicitud de autorizacin (primero autenticacin bancaria y luego la
autorizacin de la transaccin), y si todo resulta exitoso, realiza el proceso de inscripcin
de PatPass by Webpay.
9. Una vez resuelta la autorizacin, Webpay retorna el control al comercio, realizando un
redireccionamiento HTTP/HTTPS hacia la pgina de transicin del comercio, en donde se
enva por mtodo POST el token de la transaccin en la variable token_ws.
10. El navegador Web del tarjetahabiente realiza una peticin HTTP/HTTPS al sitio del
comercio, en base a la redireccin generada por Webpay en el punto 9.
11. El sitio del comercio recibe la variable token_ws e invoca el segundo mtodo Web,
getTransactionResult ()(mientras se depliega la pgina de transicin1), para obtener el
resultado de la autorizacin. Se recomienda que el resultado de a autorizacin sea

El detalle de la pgina de transicin se encuentra descrito en Anexo A, del documento de descripcin

general de la API SOAP.

Pgina 5

persistida en los sistemas del comercio, ya que este mtodo se puede invocar una nica
vez.
12. Webpay responde el resultado de la invocacin del mtodo getTransactionResult ().
13. Para informar a Webpay que el resultado de la transaccin se ha recibido sin problemas, el
sistema del comercio consume el tercer mtodo acknowledgeTrasaction.
NOTA: De no ser consumido demorar ms de 30 segundos en su consumo, Webpay
realizar la reversa de la transaccin, asumiendo que existieron problemas de
comunicacin.

14. Una vez recibido el resultado de la transaccin e informado a Webpay su correcta

recepcin, el sitio del comercio debe redirigir al tarjetahabiente nuevamente a Webpay,
con la finalidad de desplegar el comprobante de pago. Es importante realizar este punto
para que el tarjetahabiente entienda que el proceso de pago fue exitoso, y que involucrar
un cargo a su tarjeta bancaria. El redirecionamiento a Webpay se hace utilizando como
destino la URL informada por el mtodo getTransactionResult() enviando por mtodo
POST el token de la transaccin en la variable token_ws.
15. Webpay recibe un requerimiento con el token en la variable token_ws valida que la
transaccin se encuentre aprobada.
16. Webpay identifica la transaccin y despliega el comprobante de pago al tarjetahabiente.
17. Una vez visualizado el comprobante de pago, el tarjetahabiente es redirigido de vuelta al
sitio del comercio, por medio de redireccionamiento con el token en la variable token_ws
enviada por mtodo POST.
18. Sitio del comercio despliega pgina final de pago2.

El detalle de la pgina de final se encuentra descrito en Anexo A, del documento de descripcin general de
la API SOAP.

Pgina 6

3.3 Descripcin de mtodos asociados a Servicio Web de PatPass by

Webpay
A continuacin se describe cada una de las operaciones que deben ser utilizadas en una
Transaccin de PatPass by Webpay.
3.3.1

Operacin initTransaction

Mtodo que permite iniciar una transaccin de pago Webpay.

Parmetro de entrada: type initTransaction
Nombre
Descripcin
WSTransactionType xs:wsTransactionType

sessionId

(Obligatorio) Indica el tipo de transaccin, su valor debe ser siempre

TR_NORMAL_WS_WPM
xs:string
(Opcional) Identificador de sesin, uso interno de comercio, este valor
es devuelto al final de la transaccin. Un uso posible puede ser la
representacin del intento de pago.

returnURL

Largo mximo: 61
xs:anyURI
(Obligatorio) URL del comercio a la cual Webpay redireccionar
posterior al resultado de la autorizacin. Es aqu donde el comercio
deber procesar el resultado de la autorizacin.

finalURL

Largo mximo: 256

xs:anyURI
(Obligatorio) URL del comercio a la cual Webpay redireccionar
posterior al voucher de xito del comercio. Webpay enviar va mtodo
POST la variable token_ws con el valor del token de transaccin.

transactionDetails

Largo mximo: 256

tns:wsTransactionDetail
(Obligatorio) Lista de objetos del tipo wsTransactionDetail, el cual

Pgina 7

wPMDetail

contiene datos de la transaccin asociada al primer pago que e realizar

en lnea. Mxima cantidad de repeticiones es de 1 para este tipo de
transaccin.
tns:wpmDetailInput
(Obligatorio) Objeto del tipo wpmDetailInput, el cual contiene datos
asociados a la inscripcin de PatPass by Webpay.

wsTransactionDetail

Descripcin: Tipo de dato contiene detalles de la transaccin

Campo
amount

Descripcin
xs:decimal
(Obligatorio) Monto de la transaccin.

buyOrder

Largo mximo: 10
xs:string
(Obligatorio) Orden de compra de la tienda.

commerceCode

Largo mximo: 26
xs:string
(Obligatorio) Cdigo comercio de la tienda

sharesAmount

Largo: 12
xs:decimal
(Opcional, uso en cuotas comercio) Valor de la cuota.

sharesNumber

Largo mximo: 9
xs:int
(Opcional, uso en cuotas comercio)Nmero o cantidad de cuotas.
Largo mximo: 2

Pgina 8

WPMDetail

Descripcin: Tipo de dato que contiene los datos de una inscripcin PATPASS BY WEBPAY.
Campo
serviceId

Descripcin
xs:string
(Obligatorio) Identificador servicio, corresponde al cdigo
con el cual el comercio identifica el servicio prestado a su
cliente.

cardHolderId

Largo mximo: 30
xs:string
(Obligatorio) RUT del tarjetahabiente.
Formato: NN.NNN.NNN-A

cardHolderName

Largo mximo: 12
xs:string
(Obligatorio) Nombre tarjetahabiente.

cardHolderLastName1

Largo mximo: 50
xs:string
(Obligatorio) Apellido paterno tarjetahabiente.

cardHolderLastName2

Largo mximo: 50
xs:string
(Obligatorio) Apellido materno tarjetahabiente.

cardHolderMail

Largo mximo: 50
xs:string
(Obligatorio) Correo electrnico tarjetahabiente.

cellPhoneNumber

Largo mximo: 50
xs:string

expirationDate

(Obligatorio) Nmero telfono celular tarjetahabiente.

xs:dateTime
(Obligatorio) Fecha expiracin de PatPass by Webpay,

Pgina 9

corresponde al ltimo pago. Formato AAAA-MM-DD

Largo: 10
xs:string

commerceMail

(Obligatorio) Correo electrnico comercio.

amount

Largo mximo: 50
xs:decimal

ufFlag

(Obligatorio) Monto fijo inscripcin PatPass by Webpay

xs:boolean
Valor en true indica que el monto enviado est expresando
en UF, valor en false indica que valor esta expresado en
Pesos.

Parmetros de salida: type wsInitTransactionOutput

Campo
token

Descripcin
xs:string
Token de la transaccin.

url

Largo: 64
xs:string
URL de redireccin a la cual el comercio deber enviar el token
utilizando mtodo POST en variable token_ws.
Largo mximo: 256

Pgina 10

3.3.2

Operacin getTransactionResult

Descripcin del mtodo:

Mtodo que permite obtener el resultado de la transaccin y los datos de la misma.

Parmetros de entrada: getTransactionResult

Campo
tokenInput

Descripcin
xs:string
Token de la transaccin.
Largo: 64

Parmetros de salida: transactionResultOutput

Campo
buyOrder

Descripcin
xs:string
Orden de compra de la tienda.

sessionId

Largo mximo: 26
xs:string
Identificador de sesin, uso interno de comercio, este valor es
devuelto al final de la transaccin. Un uso posible puede ser la
representacin del intento de pago.

cardDetail

Largo mximo: 61
tns:carddetail

accoutingDate

Informacin de tarjeta de crdito.

xs:string
Fecha contable de la autorizacin de la transaccin, la cual ms el
desfase de abono indica al comercio la fecha en que Transbank
abonar al comercio.

transactionDate

Largo: 4, formato MMDD

xs:string
Fecha y hora de la autorizacin.

Pgina 11

Largo:
xs:string

VCI

(Opcional) Resultado de la autenticacin para comercios Webpay

Plus y/o 3D Secure, los valores posibles sin los siguientes:

TSY: Autenticacin exitosa

TSN: autenticacin fallida.
TO: Tiempo mximo excedido para autenticacin.
ABO: Autenticacin abortada por tarjetahabiente.

Largo mximo: 3
xs:string

urlRedirection

URL de redireccin a la cual el comercio deber enviar el token

utilizando mtodo POST en variable token_ws.
Largo mximo: 256
tns:transactionDetails

detailsOutput

Objeto que contiene el detalle de la transaccin financiera.

CARD D ETAIL

(D ETALLES T ARJETA DE C RDITO )

Descripcin: Tipo de dato

contiene detalles de la tarjeta de crdito. Se usa para los
comercios que tienen habilitado el envo de algunos de estos campos.

Campo
cardNumber

Descripcin
xs:string
Nmero de la tarjeta de crdito del tarjeta habiente.

cardExpirationDate

Largo mximo: 16
xs:string
(Opcional) Fecha de expiracin de la tarjeta de crdito del
tarjetahabiente. Formato YYMM
Largo mximo: 4

DETAILS O UTPUT

Campo
Pgina 12

Descripcin

Campo
authorizationCode

Descripcin
xs:string
Cdigo de autorizacin de la transaccin

paymentTypeCode

Largo mximo: 6
xs:string

responseCode

Tipo de pago de la transaccin.

xs:string
Cdigo de respuesta de la autorizacin. Valores posibles:
0
-1
-2
-3
-4
-5
-6
-7
-8
-100

amount

Transaccin aprobada.
Rechazo de transaccin.
Transaccin debe reintentarse.
Error en transaccin.
Rechazo de transaccin.
Rechazo por error de tasa.
Excede cupo mximo mensual.
Excede lmite diario por transaccin.
Rubro no autorizado.
Rechazo por inscripcin de PatPass by Webpay

xs:decimal
Monto de la transaccin.

sharesAmount

Largo mximo: 10
xs:decimal
Valor de la cuota.

sharesNumber

Largo mximo: 9
xs:int
Cantidad de cuotas

commerceCode

Largo mximo: 2
xs:string
Cdigo comercio de la tienda

buyOrder

Largo: 12
xs:string
Orden de compra de la tienda.

Pgina 13

Campo

Descripcin
Largo mximo: 26

3.3.3

Operacin acknowledgeTrasaction

Descripcin del mtodo:

Mtodo que permite informar a Webpay la correcta recepcin del resultado de la trasaccin.

Parmetros de entrada: getTransactionResult

Campo
tokenInput

Descripcin
xs:string
Token de la transaccin.
Largo: 64

Pgina 14

4 Anexo C: Ejemplos de integracin con API SOAP Webpay

La presente seccin, entrega ejemplos de uso de la API SOAP para transaccin normal en los
lenguajes Java, PHP y .net. Tienen por objetivo exponer una forma factible de integracin con API
SOAP Webpay para resolver los siguientes puntos asociados a la integracin:

Generacin de cliente o herramienta para consumir los servicios Web, lo cual permite
abstraerse de la complejidad de mensajera SOAP asociada a los Webservice y hacer uso
de las operaciones del servicio.

Firma del mensaje y validacin de firma en la respuesta, existen frameworks y

herramientas asociadas a cada lenguaje de programacin que implementan el estndar
WS Security, lo que se requiere es utilizar una de estas, configurarla y que realice el
proceso de firma digital del mensaje.
Estos ejemplos son slo una gua / ayuda de integracin, y no abarcan el proceso completo de
llamada a los WS. En ningn caso son una obligatoriedad su implementacin, y el comercio es libre
de realizar la integracin como ms le acomode.

Pgina 15

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

Generar el cliente del Webservice o STUBS.

Consumir los servicios Web

Apache WSS4J, proporciona la implementacin del estndar WS Security, nos

permitir:
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, tambin se
utiliza para configurar WS Security en la firma del mensaje SOAP.

Pasos a seguir:
1. Generacin de cliente del Webservice.
Para generar el cdigo 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. Ms informacin en http://cxf.apache.org/docs/wsdl-to-java.html

wsdl2java -autoNameResolution <URL del wsdl>

Pgina 16

2. Configuracin 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 configuracin de los interceptores se
puede realizar a travs de la API de servicios Web o a travs del XML de configuracin de
Spring, en este caso se realizar a travs de Spring en el archivo applicationContext.xml de
la aplicacin.
Se deben habilitar y configurar 2 interceptores, uno para realizar la firma de los mensajes
enviados al invocar una operacin 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="{Element}{http://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="{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/>
</map>
</constructor-arg>
</bean>

Las

interfaz
javax.security.auth.callback.CallbackHandler, su implementacin permite al
framework de seguridad recuperar la contrasea para acceder al almacen de llaves de la
aplicacin (Java Key Store) que almacena los certificados digitales.
Pgina 17

clases

ClientCallback

ServerCallBack

implementan

la

3. Llamada a operaciones del Webservice

Operacin initTransaction

private WSWebpayService service;

private List<WsTransactionDetail> transactionDetails= new ArrayList<
WsTransactionDetail>
private WsTransactionDetail transactionDetail = new WsTransactionDetail();
private WsInitTransactionInput transactionInput = new WsInitTransactionInput();
private WsInitTransactionOutput transactionOutput = new WsInitTransactionOutput();

transactionInput.setSessionId(12312423);
transactionInput.setReturnURL(http://www.midominio.com/recibetoken.do);
transactionInput.setFinalURL(http://www.midominio.com/resultado.do);
transactionDetail.setAmount(new BigDecimal(1000));
transactionDetail.setCommerceCode(59702512345);
transactionDetail.setBuyOrder(123456789);
transactionDetails.add(transactionDetail);
transactioInput.setWSTransactionType(WsTransactionType.TR_NORMAL_WS);
transactionInput.getTransactionDetails().add(transactionDetails);
/*Informacin asociada al pago Automtico con Tarjetas de Crdito - PAT*/
WpmDetailInput detail = new WpmDetailInput();
detail.setServiceId("335456675433");
detail.setCardHolderId("11.111.111-1");
detail.setCardHolderName("Juan Pedro");
detail.setCardHolderLastName1("Alarccn");
detail.setCardHolderLastName2("Perez");
detail.setCardHolderMail("[email protected]");
detail.setCellPhoneNumber("55555555");
detail.setCommerceMail("[email protected]");
detail.setUfFlag(false); /* Indica que monto no es en UF */
/*Llamada al servicio Web*/
transactionOutput = service.initTransaction(transactionInput);
/*Token y URL de redireccin*/
transactionOutput.getUrl();
transactionOutput.getToken();

Operacin getTransactionResult
/*Se asume que se obtuvo el token, el cual fue enviado por Webpay a la URL
notificada en el parmetro returnURL al invocar al mtodo initTransaction, el
parmetro enviado por post se llama token_ws*/
private WSWebpayService service;

Pgina 18

private TransactionResultOutput transactionResultOutput;

transactionResultOutput = service.getTransactionResult(token);
/* transactionResultOutput contendr los parmetros de resultado de la
transaccin*/

Operacin acknowledgeTransaction()
/*Se asume que se obtuvo el token, este mtodo tiene por objetivo indicarle a
Webpay que se obtuvo el resultado de la transaccin correctamente. Este mtodo es
void*/
private WSWebpayService service;
service.acknowledgeTransaction(token);

URL:
http://cxf.apache.org/docs/ws-security.html
http://ws.apache.org/wss4j/
http://cxf.apache.org/docs/wsdl-to-java.html

Pgina 19

4.2 Ejemplos PHP

El siguiente ejemplo est basado en PHP versin 5, sobre el cual se utilizaron las siguientes
bibliotecas de software para realizar la invocacin de los servicios web de Webpay bajo el estndar
WSS:

Biblioteca de seguridad: archivo compuesto de tres clases que integran libreras nativas
PHP de validacin y verificacin. Estas clases nos permitirn generar la seguridad
suficiente a travs de mtodos de encriptacin y desencriptacin.

WSSE-PHP: integra las libreras de seguridad XML y genera un documento XML-SOAP

seguro. Depende de las libreras de seguridad XML.

SOAP-VALIDATION: clase encargada de la validacin de mensajes SOAP seguros de

respuesta. Verifica la autenticidad e integridad del mensaje. Depende de WSSE-PHP.

Los fuentes pueden ser descargados desde https://github.com/OrangePeople/php-wss-validation

Pasos a seguir:

1. Generacin de cliente del Servicio Web:

Antes de la integracin se debe tener instalado y funcionando un servidor HTTP Apache y

configurar el directorio para generar una salida a travs del navegador web. Si se quiere optar
por una alternativa ms sencilla, Apache provee un directorio por omisin, que vara segn el
sistema operativo. Generalmente en plataformas Linux es /var/www y en Windows
C:\<directorio hacia Apache>/htdocs.
A continuacin, para generar las clases necesarias que conectan a los servicios Web, se puede
utilizar la herramienta Easy WSDL2PHP. La documentacin necesaria e informacin de
descarga se encuentra en http://sourceforge.net/projects/easywsdl2php/.
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:

Pgina 20

Se escribe la URL del archivo wsdl al se quiere conectar, un nombre de clase y luego se
presiona el botn 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 cdigo 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.
Pgina 21

2. Crear una clase que extienda de SoapClient (SoapClient es la clase nativa que provee PHP para
utilizacin de servicios Web)(En el ejemplo se denominar MySoap)
//Notar que se incluyen dos archivos que se proveen en la librera de encriptacin
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);

Pgina 22

4. Editar el archivo stub creado en el paso 1

Se debe editar el mtodo __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. Invocacin de operaciones del servicio web de Webpay.

Para todos los ejemplos se debe hacer referencia a los archivos de la librera descargada
require_once('soap-wsse.php');
require_once('soap-validation.php');
require_once('<archivo que contiene la clase stub creado en el paso 1>');

Operacin InitTransaction:
$wsInitTransactionInput = new wsInitTransactionInput();
$wsTransactionDetail = new wsTransactionDetail();
/*Variables de tipo string*/
$wsInitTransactionInput->wSTransactionType = $transactionType;
$wsInitTransactionInput->commerceId = $commerceId;
$wsInitTransactionInput->buyOrder = $buyOrder;
$wsInitTransactionInput->sessionId = $sessionId;
$wsInitTransactionInput->returnURL = $returnUrl;
$wsInitTransactionInput->finalURL = $finalUrl;
$wsTransactionDetail->commerceCode = $commerceCode;
$wsTransactionDetail->buyOrder = $buyOrder;
$wsTransactionDetail->amount = $amount;
$wsTransactionDetail->sharesNumber = $shareNumber;
$wsTransactionDetail->sharesAmount = $shareAmount;
$wpmDetailInput->cardHolderId = $cardHolderId;
$wpmDetailInput->cardHolderLastName1 = $cardHolderLastName1;
$wpmDetailInput->cardHolderLastName2 = $cardHolderLastName2;
$wpmDetailInput->cardHolderMail = $cardHolderMail;
$wpmDetailInput->cardHolderName = $cardHolderName;
$wpmDetailInput->cellPhoneNumber = $cellPhoneNumber;
$wpmDetailInput->commerceMail = $commerceMail;
$wpmDetailInput->expirationDate = $expirationDate;

Pgina 23

$wpmDetailInput->serviceId = $serviceId;
$wpmDetailInput->ufFlag = $ufFlag;
$wsInitTransactionInput->wPMDetail = $wpmDetailInput;
$wsInitTransactionInput->transactionDetails = $wsTransactionDetail;
$webpayService = new WebpayService($url_wsdl);
$initTransactionResponse = $webpayService->initTransaction(
array("wsInitTransactionInput" => $wsInitTransactionInput)
);
$xmlResponse = $webpayService->soapClient->__getLastResponse();
$soapValidation = new SoapValidation($xmlResponse, SERVER_CERT);
$validationResult = $soapValidation->getValidationResult();
/*Invocar slo s $validationResult es TRUE*/
$wsInitTransactionOutput = $initTransactionResponse->return;

Observaciones:

La clase WebpayService contiene los servicios principales y es el nombre que se

gener con WSDL2PHP.
La constante SERVER_CERT es la ruta del archivo del certificado cliente entregado
por Transbank.
initTransaction es un mtodo de la clase WebpayService y representa la llamada
el servicio initTransaction.
La variable $xmlResponse es un string del xml-soap que responde el servidor.
La variable $validationResult es el resultado de tipo boolean de la validacin del
mensaje de respuesta. Para un caso correcto el valor es TRUE, de lo contrario es
FALSE.
La variable $wsInitTransactionOutput contiene los datos que entrega el servidor.
Esta variable slo debe invocarse despus de un resultado correcto en el mensaje
SOAP de respuesta.

Operacin getTransactionResult:
$webpayService = new WebpayService($url_wsdl);
$getTransactionResult = new getTransactionResult();
$getTransactionResult->tokenInput = $_POST['token_ws'];
$getTransactionResultResponse = $webpayService->getTransactionResult(
$getTransactionResult);
$transactionResultOutput = $getTransactionResultResponse->return;

Pgina 24

Pgina 25

Operacin acknowledgeTransaction:
$webpayService = new WebpayService($url_wsdl);
$acknowledgeTransaction = new acknowledgeTransaction();
$acknowledgeTransaction->tokenInput = $_POST['token_ws'];
$acknowledgeTransactionResponse = $webpayService->acknowledgeTransaction(
$acknowledgeTransaction);
$xmlResponse = $webpayService->soapClient->__getLastResponse();
$soapValidation = new SoapValidation($xmlResponse, SERVER_CERT);
$validationResult = $soapValidation->getValidationResult();

Observaciones:

Pgina 26

El valor de $_POST['token_ws'] contiene un string del token de la transaccin que

entrega Webpay.

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 implementacin

Web Services Enhancements 3.0, proporciona la implementacin para desarrollo de

Web Service e interoperabilidad con otros sistemas.
o

Generar el cliente del WebService o Proxy

Consumir los servicios Web

Componente Intergrup.Core4.Soap.dll Componente para validacin y firma digital

para WS Security. Estos componentes representan una posible solucin 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 validacin 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 definicin de WSS,
WSE 3.0 no permite validar la firma sobre elementos cuyo identificado de referencia
presenta un prefijo. Una posible solucin se presenta en el sitio StackOverflow, en donde se
plantea una forma de sobrescribir el mtodo GetIdElement de la subclase
System.Security.Cryptography.Xml.SignedXml, que es utilizada al momento de
firmar y validar firmas digitales con el mtodo nativo ComputeSignature.

Nota: WSE 3.0 puede ser utilizado tambin con Framework .NET 2.0 y 3.5 respectivamente

Pgina 27

Pasos a seguir:
1. Generacin de cliente del Webservice.
Para generar el cdigo .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. Configuracin 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 personalizacin de clases est definido dentro de WSE 3.0 para lograr la
interoperabilidad entre sistemas.
o

Pgina 28

CustomPolicyAssertion: esta clase permite crear una Poltica para Assertion,

donde podemos capturar el Mensaje SOAP de Request y Response respectivamente.
Esto realizado a travs de filtros:
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 validacin de firma digital con la llave pblica del
certificado.

Definicin de poltica 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");
}
}

Pgina 29

La creacin de una poltica permite definir al stub o proxy cmo activar los interceptores
para envi o recepcin 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.

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.

Pgina 30

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 pblica) y se procede a la validacin 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 nmero del
comercio.

Pgina 31

Operacin initTransaction
wsInitTransactionInput initTransaction = new wsInitTransactionInput();
initTransaction.wSTransactionType = wsTransactionType.TR_NORMAL_WS_WPM;
initTransaction.sessionId = 1234567;
initTransaction.returnURL = http://www.midominio.com/recibetoken.aspx;
initTransaction.finalURL = http://www.midominio.com/resultado.aspx;
wsTransactionDetail transactionDetail = new wsTransactionDetail();
transactionDetail.amount= Convert.ToDecimal(5000);
transactionDetail.commerceCode= 597000000000;
transactionDetail.buyOrder=123456789;
initTransaction.transactionDetails=new wsTransactionDetail[]{
transactionDetail};
initTransaction.wPMDetail = new wpmDetailInput
{
serviceId=335456675433,
cardHolderId=11.111.111-1,
cardHolderName = Juan Pedro,
cardHolderLastName1 = Alarcn,
cardHolderLastName2 = Perez,
cardHolderMail = [email protected],
cellPhoneNumber = 1234567,
expirationDate = DateTime.Parse(2014-01-15),
commerceMail = [email protected],
ufFlag=false /* Indica que monto no es en UF */
};

using (WSWebpayServiceImplService proxy = new WSWebpayServiceImplService())

{
/*Define el ENDPOINT del Web Service Webpay*/
proxy.Url = http://localhost/WSWebpayTransaction/cxf/WSWebpayService;
Policy myPolicy = new Policy();
CustomPolicyAssertion customPolicty = new CustomPolicyAssertion();
myPolicy.Assertions.Add(customPolicty);
proxy.SetPolicy(myPolicy);
proxy.Timeout = 60000;
proxy.UseDefaultCredentials = false;
result = proxy.initTransaction(initTransaction);
}
/*Token y URL de redireccin*/
String token=result.token;
String urlRedireccion=result.url;

Pgina 32

Operacin getTransactionResult
/*Se asume que se obtuvo el token, el cual fue enviado por Webpay a la URL
notificada en el parmetro returnURL al invocar al mtodo initTransaction, el
parmetro enviado por post se llama token_ws*/

transactionResultOutput result=null;
using (WSWebpayServiceImplService proxy = new
WSWebpayServiceImplService())
{
/*Define el ENDPOINT del Web Service Webpay*/
proxy.Url =
http://localhost/WSWebpayTransaction/cxf/WSWebpayService;
Policy myPolicy = new Policy();
CustomPolicyAssertion customPolicty = new CustomPolicyAssertion();
myPolicy.Assertions.Add(customPolicty);
proxy.SetPolicy(myPolicy);
proxy.Timeout = 60000;
proxy.UseDefaultCredentials = false;
result = proxy.getTransactionResult(token);
}
/* transactionResultOutput contendr los parmetros de resultado de la
transaccin*/

Operacin acknowledgeTransaction()
/*Se asume que se obtuvo el token, este mtodo tiene por objetivo indicarle a
Webpay que se obtuvo el resultado de la transaccin correctamente. Este mtodo es
void*/

using (WSWebpayServiceImplService proxy = new

WSWebpayServiceImplService())
{
/*Define el ENDPOINT del Web Service Webpay*/
proxy.Url =
http://localhost/WSWebpayTransaction/cxf/WSWebpayService;
Policy myPolicy = new Policy();
CustomPolicyAssertion customPolicty = new CustomPolicyAssertion();
myPolicy.Assertions.Add(customPolicty);
proxy.SetPolicy(myPolicy);
proxy.Timeout = 60000;
proxy.UseDefaultCredentials = false;
proxy.acknowledgeTransaction(token);
}

Pgina 33

Referencias:

WSE 3.0: http://www.microsoft.com/en-us/download/details.aspx?id=14089

Framework .NET 4.0: http://www.microsoft.com/en-us/download/details.aspx?id=17851
Herramienta wsewsdl3 para generacin de proxy http://www.microsoft.com/enus/download/details.aspx?id=14089
Componente Intergrup.Core4.Soap.dll http://www.intergrup.cl/software/ws-security.html
Web Services Security X.509 Certificate Token Profile 1.1. https://www.oasisopen.org/committees/download.php/16785/wss-v1.1-spec-os-x509TokenProfile.pdf
StackOverflow, firma en elementos con ID que utilizan prefijos.
http://stackoverflow.com/questions/5099156/malformed-reference-element-whenadding-a-reference-based-on-an-id-attribute-w

Pgina 34