Académique Documents
Professionnel Documents
Culture Documents
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
Prefacio ....................................................................................................................................... 2
2.1
2.2
Audiencia ............................................................................................................................. 2
2.3
Descripcin de la transaccin.............................................................................................. 3
3.2
3.3
3.3.1
3.3.2
3.3.3
4.2
4.3
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
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.
Pgina 2
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
acknowledgeTrasaction
Pgina 3
Webpay
Tarjetahabiente
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
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
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.
El detalle de la pgina de final se encuentra descrito en Anexo A, del documento de descripcin general de
la API SOAP.
Pgina 6
Operacin initTransaction
sessionId
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
transactionDetails
Pgina 7
wPMDetail
wsTransactionDetail
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
Pgina 9
commerceMail
amount
Largo mximo: 50
xs:decimal
ufFlag
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
xs:string
Token de la transaccin.
Largo: 64
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
transactionDate
Pgina 11
Largo:
xs:string
VCI
Largo mximo: 3
xs:string
urlRedirection
detailsOutput
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
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
Campo
tokenInput
Descripcin
xs:string
Token de la transaccin.
Largo: 64
Pgina 14
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.
Pgina 15
Apache CXF, es un framewok open source que ayuda a construir y consumir servicios
Web en Java. En este ejemplo se utilizar para:
o
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
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
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("example@example.com");
detail.setCellPhoneNumber("55555555");
detail.setCommerceMail("example2@example2.com");
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
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
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.
Pasos a seguir:
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');
Las constantes PRIVATE_KEY Y CERT_FILE son las rutas de la llave privada y certificado del
comercio, respectivamente.
Pgina 22
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:
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
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
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;
}
}
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;
}
}
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 = example@example.com,
cellPhoneNumber = 1234567,
expirationDate = DateTime.Parse(2014-01-15),
commerceMail = user@domain.com,
ufFlag=false /* Indica que monto no es en UF */
};
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*/
Pgina 33
Referencias:
Pgina 34