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;
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay




# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay




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;
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay














# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay














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.

Video tutorial de integración SDK PHP 1
Crear una transacción
Youtube

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.
}
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay







# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay







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.

Video tutorial de integración SDK PHP 2
Confirmar una transacción
Youtube

Webpay OneClick

Crear una inscripción

Para usar Webpay OneClick 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;
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay





# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay





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;
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay










# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay










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.
}
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay







# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay







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
}
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay









# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay









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;
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay













# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay













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
}
# Para integrar Webpay en Ruby puedes utilizar la Referencia API, alguna librería externa o libwebpay







# Para integrar Webpay en Python puedes utilizar la Referencia API, alguna librería externa o libwebpay







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 puedes realizar una conciliación entre tu sistema y el reporte que entrega el portal.

Webpay Plus

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. Una vez entras al portal, en el menú principal presiona "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 filtrar por las transacciones de Webpay Plus, en el campo "Producto" debes seleccionar Webpay3G. Debes tener en cuenta que lamentablemente el reporte no distingue entre Webpay y Onepay, debido a esto, bajo el producto "Webpay3G" encontrarás transacciones de ambos productos. 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 los parámetros devueltos por el SDK 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á)

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

OneClick

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. Una vez entras al portal, en el menú principal presiona "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 filtrar por las transacciones de OneClick, en el campo "Producto" debes seleccionar 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 los parámetros devueltos por el SDK 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 OneClick la puedes encontrar acá)

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:

Ejemplos de integración

Ponemos a tu disposición una serie de repositorios en nuestro Github para ayudarte a entender la integración mejor.