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();
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;
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.
}
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();
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;
// 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.
}
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
}
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();
Configuration configuration = new Configuration();
configuration.CommerceCode = "12345"; // acá va tu código de comercio
configuration.PrivateKey =  // pega acá la llave privada de tu certificado
    "-----BEGIN RSA PRIVATE KEY-----\n" +
    "MIIEpQIBAAKCAQEA0ClVcH8RC1u+KpCPUnzYSIcmyXI87REsBkQzaA1QJe4w/B7g\n" +
    //....
    "MtdweTnQt73lN2cnYedRUhw9UTfPzYu7jdXCUAyAD4IEjFQrswk2x04=\n" +
    "-----END RSA PRIVATE KEY-----");
configuration.PublicCert = // pega acá tu certificado público
    "-----BEGIN CERTIFICATE-----\n" +
    "MIIDujCCAqICCQCZ42cY33KRTzANBgkqhkiG9w0BAQsFADCBnjELMAkGA1UEBhMC\n" +
    //....
    "-----END CERTIFICATE-----");

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
Configuration configuration = new Configuration();
configuration.Environment = "PRODUCCION";
// agregar también configuración del código de comercio y certificados

Más Funcionalidades

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