API Referencia
undefined

Webpay

Webpay Plus

Crear una transacción

Para una transacción asociada a un único comercio (también conocida como "normal"), lo primero que necesitas es preparar una instancia de WebpayNormal con la Configuration que incluye el código de comercio y los certificados a usar.

Una forma fácil de comenzar es usar la configuración para pruebas que viene incluida en el SDK:

import cl.transbank.webpay.configuration.Configuration;
import cl.transbank.webpay.Webpay;
import cl.transbank.webpay.WebpayNormal;
// ...

WebpayNormal transaction =
    new Webpay(Configuration.forTestingWebpayPlusNormal())
    .getNormalTransaction();
use Transbank\Webpay\Configuration;
use Transbank\Webpay\Webpay;
// ...

$transaction = (new Webpay(Configuration::forTestingWebpayPlusNormal()))
               ->getNormalTransaction();
using Transbank.Webpay;
//...

var transaction =
    new Webpay(Configuration.ForTestingWebpayPlusNormal()).NormalTransaction;

Una vez que ya cuentas con esa preparación, puedes iniciar transacciones:

import com.transbank.webpay.wswebpay.service.WsInitTransactionOutput;
// ...
double amount = 1000;
// Identificador que será retornado en el callback de resultado:
String sessionId = "mi-id-de-sesion";
// Identificador único de orden de compra:
String buyOrder = String.valueOf(Math.abs(new Random().nextLong()));
String returnUrl = "https://callback/resultado/de/transaccion";
String finalUrl = "https://callback/final/post/comprobante/webpay";
WsInitTransactionOutput initResult = transaction.initTransaction(
        amount, sessionId, buyOrder, returnUrl, finalUrl);

String formAction = initResult.getUrl();
String tokenWs = initResult.getToken();
$amount = 1000;
// Identificador que será retornado en el callback de resultado:
$sessionId = "mi-id-de-sesion";
// Identificador único de orden de compra:
$buyOrder = strval(rand(100000, 999999999));
$returnUrl = "https://callback/resultado/de/transaccion";
$finalUrl = "https://callback/final/post/comprobante/webpay";
$initResult = $transaction->initTransaction(
        $amount, $buyOrder, $sessionId, $returnUrl, $finalUrl);

$formAction = $initResult->url;
$tokenWs = $initResult->token;
using Transbank.Webpay;
//...

var amount = 1000;
// Identificador que será retornado en el callback de resultado:
var sessionId = "mi-id-de-sesion";
// Identificador único de orden de compra:
var buyOrder = new Random().Next(100000, 999999999).ToString();
var returnUrl = "https://callback/resultado/de/transaccion";
var finalUrl = "https://callback/final/post/comprobante/webpay";
var initResult = transaction.initTransaction(
        amount, buyOrder, sessionId, returnUrl, finalUrl);

var formAction = initResult.url;
var tokenWs = initResult.token;

La URL y el token retornados te indican donde debes redirigir al usuario para que comience el flujo de pago. Esta redirección debe ser vía POST por lo que deberás crear un formulario web con un campo token_ws hidden y enviarlo programáticamente para entregar el control a Webpay.

Confirmar una transacción

Una vez que el tarjetahabiente ha pagado (o declinado, o ha ocurrido un error), Webpay retornará el control vía POST a la URL que indicaste en el returnUrl. Recibirás también el parámetro token_ws que te permitirá conocer el resultado de la transacción:

import com.transbank.webpay.wswebpay.service.TransactionResultOutput;
import com.transbank.webpay.wswebpay.service.WsTransactionDetailOutput;
// ...
TransactionResultOutput result =
    transaction.getTransactionResult(request.getParameter("token_ws"));
WsTransactionDetailOutput output = result.getDetailOutput().get(0);
if (output.getResponseCode() == 0) {
    // Transaccion exitosa, puedes procesar el resultado con el contenido de
    // las variables result y output.
}
$result = $transaction->getTransactionResult($request->input("token_ws"));
$output = $result->detailOutput;
if ($output->responseCode == 0) {
    // Transaccion exitosa, puedes procesar el resultado con el contenido de
    // las variables result y output.
}
using Transbank.Webpay;
//...

var result = transaction.getTransactionResult(tokenWs);
var output = result.detailOutput[0];
if (output.responseCode == 0) {
    // Transaccion exitosa, puedes procesar el resultado con el contenido de
    // las variables result y output.
}

Importante: El SDK se encarga de que al mismo tiempo que se obtiene el resultado de la transacción se haga el acknowledge a Transbank de manera que no haya posibilidad de que la transacción se revierta. Si luego necesitas que la transacción no se lleve a cabo (por ejemplo porque ya no tienes stock o porque se generó un error en tu lógica de negocio que entrega el producto o servicio), deberás anular la transacción.

En el caso exitoso deberás llevar el control vía POST nuevamente a Webpay para que el tarjetahabiente vea el comprobante que le deja claro que se ha realizado el cargo en su tarjeta. Nuevamente deberás generar un formulario con el token_ws como un campo hidden. La URL para redirigir la debes obtener desde result.getUrlRedirection().

Finalmente después del comprobante Webpay redirigirá otra vez (vía POST) a tu sitio, esta vez a la URL que indicaste en el finalUrl cuando iniciaste la transacción. Tal como antes, recibirás el token_ws que te permitirá identificar la transacción y mostrar un comprobante o página de éxito a tu usuario. Con eso habrás completado el flujo "feliz" en que todo funciona.

En la referencia detallada de Webpay Plus puedes ver cada paso del flujo, incluyendo los casos de borde que también debes manejar.

Webpay OneClick

Crear una inscripción

Para usar Webpay Onelick en transacciones asociadas a un único comercio, lo primero que necesitas es preparar una instancia de WebpayOneClick con la Configuration que incluye el código de comercio y los certificados a usar

Una forma fácil de comenzar es usar la configuración para pruebas que viene incluida en el SDK:

import cl.transbank.webpay.configuration.Configuration;
import cl.transbank.webpay.Webpay;
import cl.transbank.webpay.WebpayOneClick;
// ...

WebpayOneClick transaction =
    new Webpay(Configuration.forTestingWebpayOneClickNormal())
    .getOneClickTransaction();
use Transbank\Webpay\Configuration;
use Transbank\Webpay\Webpay;
// ...

$transaction =
    (new Webpay(Configuration::forTestingWebpayOneClickNormal()))
    ->getOneClickTransaction();
using Transbank.Webpay;
//...

var transaction =
    new Webpay(Configuration.ForTestingWebpayOneClickNormal())
    .OneClickTransaction;

Una vez que ya cuentas con esa preparación, puedes iniciar transacciones:

import com.transbank.webpayserver.webservices.OneClickInscriptionOutput;
//...

// Identificador del usuario en el comercio
String username = "pepito"
// Correo electrónico del usuario
String email = "[email protected]";
String urlReturn = "https://callback/resultado/de/transaccion";
OneClickInscriptionOutput initResult =
    transaction.initInscription(username, email, urlReturn);
String formAction = initResult.getUrlWebpay();
String tbkToken = initResult.getToken();
// Identificador del usuario en el comercio
$username = "pepito"
// Correo electrónico del usuario
$email = "[email protected]";
$urlReturn = "https://callback/resultado/de/transaccion";
$initResult = $transaction->initInscription($username, $email, $urlReturn);
$formAction = $initResult->urlWebpay;
$tbkToken = $initResult->token;
using Transbank.Webpay;
//...

// Identificador del usuario en el comercio
var username = "pepito"
// Correo electrónico del usuario
var email = "[email protected]";
var urlReturn = "https://callback/resultado/de/transaccion";
var initResult = transaction.initInscription(username, email, urlReturn);
var formAction = initResult.urlWebpay;
var tbkToken = initResult.token;

Tal como en el caso de Webpay Plus, debes redireccionar vía POST el navegador del usuario a la url retornada en initInscription. A diferencia de Webpay Plus, acá el nombre del parámetro que contiene el token se debe llamar TBK_TOKEN.

Confirmar una inscripción

Una vez que el usuario autorice la inscripción, retornará el control al comercio vía POST en la url indicada en urlReturn, con el parámetro TBK_TOKEN identificando la transacción. Con esa información se puede finalizar la inscripción:

import com.transbank.webpayserver.webservices.OneClickFinishInscriptionOutput;
//...

OneClickFinishInscriptionOutput result =
    transaction.finishInscription(tbkToken);
if (result.getResponseCode() == 0) {
    // Inscripcion exitosa.
    // Ahora puedes usar result.tbkUser para autorizar transacciones
    // oneclick sin nueva intervención del usuario.
}
$result = $transaction->finishInscription($tbkToken);
if ($result->responseCode == 0) {
    // Inscripcion exitosa.
    // Ahora puedes usar $result->tbkUser para autorizar transacciones
    // oneclick sin nueva intervención del usuario.
}
using Transbank.Webpay;
//...

var result = transaction.finishInscription(tbkToken);
if (result.responseCode == 0) {
    // Inscripcion exitosa.
    // Ahora puedes usar result.tbkUser para autorizar transacciones
    // oneclick sin nueva intervención del usuario.
}

Con eso habrás completado el flujo "feliz" en que todo funciona OK. En la referencia detallada de Webpay OneClick puedes ver cada paso del flujo, incluyendo los casos de borde que también debes manejar.

Realizar transacciones

Finalmente, puedes autorizar transacciones usando el tbkUser retornado:

import com.transbank.webpayserver.webservices.OneClickPayOutput;
//...

// Identificador único de orden de compra generado por el comercio:
Long buyOrder = Math.abs(new Random().nextLong());
String tbkUser = tbkUserRetornadoPorFinishInscription;
String username = "pepito"; // El mismo usado en initInscription.
BigDecimal amount = BigDecimal.valueof(50000);
OneClickPayOutput output =
    transaction.authorize(buyOrder, tbkUser, username, amount);
if (output.getResponseCode() == 0) {
    // Transacción exitosa, procesar output
}
$buyOrder = rand(100000, 999999999);
$tbkUser = $tbkUserRetornadoPorFinishInscription;
$username = "pepito"; // El mismo usado en initInscription.
$amount = 50000;
$output = $transaction->authorize($buyOrder, $tbkUser, $username, $amount);
if ($output->responseCode == 0) {
    // Transacción exitosa, procesar $output
}
using Transbank.Webpay;
//...

var buyOrder = new Random().next(100000, 999999999);
var tbkUser = tbkUserRetornadoPorFinishInscription;
var username = "pepito"; // El mismo usado en initInscription.
var amount = BigDecimal.valueof(50000);
var output = transaction.authorize(buyOrder, tbkUser, username, amount);
if (output.responseCode == 0) {
    // Transacción exitosa, procesar output
}

Credenciales y Ambiente

Para Webpay, las credenciales del comercio (código de comercio y certificados) varían según el subproducto usado (Webpay Plus, Webpay Plus Mall, Webpay OneClick, Webpay OneClick Mall). Asimismo, varían las credenciales si la captura es diferida. Y también varían si la moneda a manejar es pesos chilenos (CLP) o dólares (USD).

Por lo tanto, es clave que antes de operar con las clases que permiten realizar transacciones (WebpayNormal, WebpayMallNormal, WebpayCapture, WebpayNullify, WebpayOneClick) se configure correctamente el objeto Webpay desde donde se obtienen dichas instancias.

Ese objeto Webpay se configura en base a un objeto Configuration. Y si bien para hacer pruebas iniciales pueden usarse las credenciales pre-configuradas (como se puede ver en todos los ejemplos anteriores), para poder superar el proceso de validación en el ambiente de integración será necesario configurar explícitamente tu código de comercio y certificados:

import cl.transbank.webpay.configuration.Configuration;
import cl.transbank.webpay.Webpay;
import cl.transbank.webpay.WebpayNormal;
import cl.transbank.webpay.WebpayMallNormal;
import cl.transbank.webpay.WebpayCapture;
import cl.transbank.webpay.WebpayNullify;
import cl.transbank.webpay.WebpayOneClick;


//...

Configuration configuration = new Configuration();
configuration.setCommerceCode("12345"); // acá va tu código de comercio
configuration.setPrivateKey( // pega acá la llave privada de tu certificado
    "-----BEGIN RSA PRIVATE KEY-----\n" +
    "MIIEpQIBAAKCAQEA0ClVcH8RC1u+KpCPUnzYSIcmyXI87REsBkQzaA1QJe4w/B7g\n" +
    //....
    "MtdweTnQt73lN2cnYedRUhw9UTfPzYu7jdXCUAyAD4IEjFQrswk2x04=\n" +
    "-----END RSA PRIVATE KEY-----");
configuration.setPublicCert( // pega acá tu certificado público
    "-----BEGIN CERTIFICATE-----\n" +
    "MIIDujCCAqICCQCZ42cY33KRTzANBgkqhkiG9w0BAQsFADCBnjELMAkGA1UEBhMC\n" +
    //....
    "-----END CERTIFICATE-----");

Webpay webpay = new Webpay(configuration);
// Ahora puedes obtener las instancias de las transacciones
// que usarás, por ejemplo:
WebpayOneClick oneClickTransaction = webpay.getOneClickTransaction();
use Transbank\Webpay\Configuration;
use Transbank\Webpay\Webpay;
// ...

$configuration = new Configuration();
$configuration->setCommerceCode("12345"); // acá va tu código de comercio
$configuration->setPrivateKey( // pega acá la llave privada de tu certificado
    "-----BEGIN RSA PRIVATE KEY-----\n" +
    "MIIEpQIBAAKCAQEA0ClVcH8RC1u+KpCPUnzYSIcmyXI87REsBkQzaA1QJe4w/B7g\n" +
    //....
    "MtdweTnQt73lN2cnYedRUhw9UTfPzYu7jdXCUAyAD4IEjFQrswk2x04=\n" +
    "-----END RSA PRIVATE KEY-----");
$configuration->setPublicCert( // pega acá tu certificado público
    "-----BEGIN CERTIFICATE-----\n" +
    "MIIDujCCAqICCQCZ42cY33KRTzANBgkqhkiG9w0BAQsFADCBnjELMAkGA1UEBhMC\n" +
    //....
    "-----END CERTIFICATE-----");

$webpay = new Webpay($configuration);
// Ahora puedes obtener las instancias de las transacciones
// que usarás, por ejemplo:
$oneClickTransaction = $webpay->getOneClickTransaction();
using Transbank.Webpay;
//...

var configuration = new Configuration()
{
    CommerceCode = "12345", // acá va tu código de comercio
    PrivateCertPfxPath = @"C:\Certs\certificado.pfx", // pega acá la ruta a tu archivo pfx o p12
    Password = "secret123" // pega acá el secreto con el cual se genero el archivo pfx o p12
};

var webpay = new Webpay(configuration);
// Ahora puedes obtener las instancias de las transacciones
// que usarás, por ejemplo:
var oneClickTransaction = webpay.OneClickTransaction;

Apuntar a producción

Para cambiar el ambiente al que apunta el SDK (que por defecto es integración), también debes usar el objeto Configuration (antes de crear una instancia de Webpay):

Configuration configuration = new Configuration();
configuration.setEnvironment(Webpay.Environment.PRODUCCION);
// agregar también configuración del código de comercio y certificados
use Transbank\Webpay\Configuration;
// ...

$configuration = new Configuration();
$configuration->setEnvironment("PRODUCCION");
// agregar también configuración del código de comercio y certificados
using Transbank.Webpay;
//...

Configuration configuration = new Configuration()
{
    Environment = "PRODUCCION";
    // agregar también configuración del código de comercio y certificados
}

Conciliación de Transacciones

Una vez hayas realizado transacciones en producción quedará un historial de transacciones que puedes revisar entrando a www.transbank.cl. Si lo deseas realizar una conciliación entre tu sistema y el reporte que entrega el portal.

Para realizar la conciliación debes seguir los siguientes pasos:

  1. Iniciar sesión con tu usuario y contraseña en www.transbank.cl

  2. Luego, en el menú principal presionar "Webpay" y luego "Reporte transaccional". Paso 2

  3. En la parte superior de la ventana puedes encontrar un buscador que te ayudará a filtrar, según los parámetros que gustes, las transacciones que quieras cuadrar. Para encontrar las transacciones de Webpay Plus, en producto, debes seleccionar Webpay3G, en caso de querer las de Webpay OneClick selecciona "OneClick" Paso 3

  4. Dentro de la tabla en la imagen anterior puedes presionar el número de orden de compra para abrir los detalles de la transacción. Es en esta sección donde podrás encontrar y conciliar la mayoría de los parámetros devueltos al confirmar una transacción. Paso 4

  5. Sólo queda realizar la conciliación. A continuación puedes ver una lista de parámetros que recibirás al momento de confirmar una transacción y a que fila de la tabla "Detalles de la transacción" corresponden (la lista completa de parámetros de Webpay Plus la puedes encontrar acá y la de Webpay OneClick acá).

En el caso de Webpay Plus Normal

Nombre parámetro
tipo
Fila en tabla
buyOrder
xs:string
Orden de compra
cardDetails.cardNumber
xs:string
Final número de tarjeta (solo para comercios autorizados por Transbank se envía el número completo).
transactionDate
xs:string
Fecha creación
VCI
xs:string
VCI. Este campo es información adicional suplementaria al responseCode pero el comercio no debe validar este campo. Porque constantemente se agregan nuevos mecanismos de autenticación que se traducen en nuevos valores para este campo que no están necesariamente documentados. (En el caso de tarjetas internacionales que no proveen 3D-Secure, la decisión del comercio de aceptarlas o no se realiza a nivel de configuración del comercio en Transbank y debe ser conversada con el ejecutivo del comercio)
detailsOutput[0].authorizationCode
xs:string
Código de autorización
detailsOutput[0].paymentTypeCode
xs:string
Tipo de producto
detailsOutput[0].responseCode
xs:string
Código de respuesta.
detailsOutput[0].amount
Formato número entero para transacciones en peso y decimal para transacciones en dólares.
Monto
detailsOutput[0].sharesNumber
xs:int
Número de cuotas
detailsOutput[0].commerceCode
xs:string
Comercio, desde el quinto dígito en adelante del commerceCode corresponde al número antes del guión que podemos apreciar en la imagen anterior.
detailsOutput[0].buyOrder
xs:string
Orden de compra

En el caso de Webpay Oneclick

Nombre
tipo
Descripción
authorizationCode
xs:string
Código de autorización
creditCardType
creditCardType
Medio de Pago
last4CardDigits
xs:string
Final número tarjeta
responseCode
xs:int
Código de respuesta

Más Funcionalidades

Consulta la referencia del API para más funcionalidades ofrecidas por Webpay Plus y Webpay OneClick: