2 Iniciando el SDK - DarkGhostHunter/TransbankApi GitHub Wiki

Iniciando el SDK

Tabla de Contenido

Ambientes

Para iniciar el SDK, primero debes indicar qué ambiente usarás:

  • integration: En este ambiente puedes probar la funcionalidad del SDK entre tu aplicación y Transbank (Onepay, Webpay, Patpass y lo que les dé por inventar después).
  • production: Ambiente de producción, donde todas las transacciones entre tu aplicación y Transbank serán de verdad, 100% real no fake.

Si no ingresas uno, o no indicas explícitamente production, usaremos integration por defecto.

Para hacer las pruebas más fáciles cuando usas integration, todas las credenciales y certificados de prueba son cargados automáticamente, así que no necesitas añadir nada.

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;

$transbank = Transbank::make('notProduction!');

Sin embargo, cuando uses el ambiente de producción, deberás suministrar tus propias credenciales de Webpay y Onepay, dependiendo de qué quieras usar en tu aplicación.

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;

$transbank = Transbank::make('production', [
    'webpay' => [
        'commerceCode' => '5000000001',
        'publicKey' => 'ABCD1234EF...',
        'publicCert' => '---BEGIN CERTIFICATE---...'
    ],
    'onepay' => [
        'apiKey' => 'ABCD1234EF...',
        'secret' => 'ABCD1234EF...', 
    ],
    'patpass' => [
        'commerceCode' => '5000000001',
        'publicKey' => 'ABCD1234EF...',
        'publicCert' => '---BEGIN CERTIFICATE---...'
    ],
]);

Si no te gusta entregar arrays, o bien sólo tendrás acceso a la configuración de Transbank posteriormente en tu aplicación, puedes usar los métodos públicos:

<?php 

$transbank->setCredentials('onepay', [
    'commerceCode' => '5000000001',
    'publicKey' => 'ABCD1234EF...',
    'publicCert' => '---BEGIN CERTIFICATE---...'
]);

$transbank->setCredentials('webpay', [
    'apiKey' => 'ABCD1234EF...',
    'secret' => 'ABCD1234EF...', 
]);

$transbank->setCredentials('patpass', [
    'commerceCode' => '5000000001',
    'publicKey' => 'ABCD1234EF...',
    'publicCert' => '---BEGIN CERTIFICATE---...'
]);

Como desarrollador, tienes plena libertad para usar lo que desees para recuperarlas e ingresarlas dentro de la configuración, sin embargo el SDK sólo aceptará texto. Te recomendamos cargar el contenido de los archivos con las credenciales, así puedes reemplazarlas fácilmente.

Si no deseas usar Onepay o Webpay, puedes prescindir de esas credenciales en particular, sin embargo cuando uses estos servicios recibirás un error indicando que las credenciales no existen.

Instanciar servicios de Transbank

Tienes total flexibilidad para instanciar los servicios de Transbank en tu aplicación (Webpay, Onepay, y próximamente Patpass).

Lo más simple usar los métodos de la clase Transbank, que te ahorrarán algunas líneas de código.

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;

$transbank = Transbank::make('integration');

$webpay = $transbank->webpay();
$onepay = $transbank->onepay();

Si usas estos métodos, los servicios no serán nuevamente creados, sino almacenados dentro de $transbank. Cada vez que los llames, aparecerá la misma instancia, por lo que podrás ahorrar memoria.

También puedes crearlos a la antigua:

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;
use DarkGhostHunter\TransbankApi\Webpay;
use DarkGhostHunter\TransbankApi\Onepay;
use Psr\Log\NullLogger;

$transbank = new Transbank(new NullLogger());

$webpay = new Webpay($transbank);
$onepay = new Onepay($transbank);

Cada servicio de Transbank obtiene una instancia de Transbank. Obviamente, de esta forma, Transbank no tendrá acceso a las instancias de los servicios, por lo que al usar $transbank->webpay() generará otra.

También puedes quieras usar los métodos estáticos:

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;

$transbank = Transbank::make('integration');

$webpay = Webpay::fromConfig($transbank);
$onepay = Onepay::fromConfig($transbank);

Para mantener las cosas simples, en toda la documentación sólo usaremos el primer método.

Te recomendamos guardar las instancias de Transbank, Webpay, Onepay y Patpass en tu aplicación para que no tengas que instanciarlas una y otra vez. Mucho mejor si sólo las instancias cuando sea necesario, y no en cada petición.

Registro de transacciones (Logger)

Como podiste notar en la sección anterior, este paquete permite logear las transacciones que son emitidas hacia Transbank en tu aplicación.

Por defecto, al usar make() sin un tercer parámetro, la instancia de Transbank usará NullLogger, que es un Logger que no registra nada.

Si quieres usar un Logger, puedes usar Katzgrau\KLogger\Logger, que viene incluido y te permitirá registrar las transacciones en algún archivo a tu conveniencia:

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;
use Katzgrau\KLogger\Logger;
use Psr\Log\LogLevel;

// Registra todas las llamadas con prioridad 7, "INFO" .
LogLevel::INFO;

// Donde vamos a escribir los archivos
$logger = new Logger('/home/transbank/transactions.log');

$transbank = new Transbank($logger);

$webpay = $transbank->webpay();
$onepay = $transbank->onepay();

Si necesitas que los servicios ocupen un Logger diferente al declarado en el objeto Transbank, puedes usar tu otro Logger en un segundo parámetro:

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;
use Katzgrau\KLogger\Logger;
use Psr\Log\LogLevel;
use App\Loggers\SlackLogger;
use App\Loggers\DatabaseLogger;

// Registra todas las llamadas con prioridad 7, "INFO" .
LogLevel::INFO;

// Donde vamos a escribir los archivos
$logger = new Logger('/home/transbank/transactions.log');

$transbank = new Transbank($logger);

// Usa otro logger para webpay
$webpay = Webpay::fromConfig($transbank, new SlackLogger());

// Y otro para Onepay
$onepay = new Onepay($transbank, new DatabaseLogger);

Los servicios incluyen los métodos setLogger() y getLogger(), por lo que también tienes la opción de interceder en medio de una transacción, cambiar el Logger por el que desees, crear la transacción, y luego devolver el Logger original.

Configuraciones predeterminadas

También puedes ingresar por defecto cómo operarás con Webpay, Onepay y Patpass, usando el métodos setDefaults() junto con el nombre del servicio.

Aquí tienes el set completo de parámetros aceptados como por defecto:

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;

$transbank = Transbank::make();

$transbank->setDefaults('webpay', [
    'plusReturnUrl'         => 'http://app.com/webpay/result',
    'plusFinalUrl'          => 'http://app.com/webpay/receipt',
    'plusMallReturnUrl'     => 'http://app.com/webpay/mall/result',
    'plusMallFinalUrl'      => 'http://app.com/webpay/mall/receipt',
    'patpassReturnUrl'      => 'http://app.com/webpay/patpass/result',
    'patpassFinalUrl'       => 'http://app.com/webpay/patpass/final',
    'patpassCommerceEmail'  => '[email protected]',
    'oneclickResponseURL'   => 'http://app.com/webpay/registration',
]);

$transbank->setDefaults('onepay', [
    'channel'               => 'mobile', 
    'generateOttQrCode'     => false,
    'callbackUrl'           => 'http://app.com/onepay/result',
    'appScheme'             => 'my-app://onepay/result',
]);

$transbank->setDefaults('patpass', [
    'finalUrl'              => 'http://app.com/patpass/newReceipt',
]);

Cuando creas una transacción con estos valores predeterminados, esas propiedades serán inyectadas a la Transacción que estés realizando automáticamente. Por supuesto podrás sobreescribir usando el array o declarando la propiedad posteriormente en tus transacciones:

<?php

$transbank = Transbank::make();

$transbank->setDefaults('webpay', [
    'plusReturnUrl'         => 'http://app.com/webpay/result',
    'oneclickResponseURL'   => 'http://app.com/webpay/registration',
]);

$transaction = $transbank->webpay()->makeNormal([
    // Cambiaremos el retorno de URL si nuestro producto es uno muy especial
    'returnUrl' => 'https://app.com/webpay/specialUrl/result'
]);

Procesar la transacción inmediatamente

No es necesario que instancies una transacción y luego la envíes en otra línea. Si quieres obtener sólo el resultado desde los servidores Transbank, puedes reemplazar la palabra make por create, e ingresar los datos dentro de un array.

Por ejemplo, para crear una transacción normal y despacharla inmediatamente usaremos createNormal(), que retornará el resultado:

<?php

$result = $webpay->createNormal([
    // ...
    'returnUrl' => 'https://app.com/webpay/specialUrl/result'
]);

echo $result->token; // "a923asod3u1nd0g3ktnvk3..." 
echo $result->url; // "http://webpay3g.transbank.cl/..."

Obviamente, si usas create, sólo recibirás el resultado, por lo que la instancia de la transacción desaparecerá para siempre. Si necesitas alguna lógica con la transacción antes de enviarla, es mejor que uses make.

Además, si usas make, el resultado que se genere desde Transbank se guardará dentro de la Transacción, así que tendrás acceso a la Transacción y al Resultado dentro de ella. Podrás evitar crear un nuevo resultado si ya fue hecho, o forzar un nuevo intento usando forceGetResult() sin necesidad de volver a crear la Transacción.

¿Array, propiedades o métodos?

La gran mayoría de los métodos para crear transacciones o peticiones aceptan un array para crear una instancia, y declarar propiedades con los valores posteriormente. De hecho, debería ser lo más normal para cualquier desarrollador.

Para que tengas total libertad de cómo hacer las cosas, puedes:

  • Declarar las propiedades al crear la transacción dentro de un array.
  • Cambiar el valor de un atributo como una propiedad de la clase.
  • Cambiar el valor de un atributo como un key de un array.
  • Cambiar el valor de un atributo como una función.

Aquí tienes una ilustración sobre cómo puedes usar estos cuatro modos. Ojo, esto es sólo un ejemplo:

<?php

namespace App;

use DarkGhostHunter\TransbankApi\Transbank;
use App\Session\User;

// Procesador de transacciones para Webpay
$webpay = Transbank::make()->webpay();

// Transacción Normal
$transaction = $webpay->makeNormal([
    'buyOrder' => 'myOrder#16548',
    'amount' => 1000,
    // ...
]);

// Podemos declarar como propiedad
$transaction->amount = 2000;

// ... como si fuese una función fluida
$transaction->amount(0)->buyOrder('Orden-299');

// ... o como si fuese un array.
$transaction['amount'] = $transaction->amount + 1500;

Sobrescribir atributos automáticos

La idea de este paquete es hacer la mayoría del trabajo pesado por tí. Por ejemplo, la librería se encarga de manejar automáticamente dónde y cómo comunicarse con Transbank, y qué valores crear automáticamente dependiendo de la transacción que estás haciendo.

Por poner un ejemplo, al crear una Transacción en Onepay, el Carro de Compras automáticamente generará el total de toda la transacción, cuándo fue hecha y el identificador único, cuando sea despachado a Transbank.

Cuando quieras sobreescribir los atributos en la transacción, sólo declárala como cualquier otro atributo.

<?php

// `issuedAt` es generado automáticamente, sin embargo aquí ingresaremos un valor
// inválido (no es un "UNIX timestamp"), para demostrar que se puede.
$cart = $onepay->makeCart([
   'issuedAt' => 'como hace un ratito atrás',
   'items' => [
       // ...
    ]
]);

$result = $cart->getResult(); // El resultado nos dará error...

Cuando las transacciones se despachan, la librería ingresará los valores que debe tener la transacción pero que no fueron declarados, sin embargo, no verificará que los tuyos puestos anteriormente sean correctos.

Sobrescribe los valores automáticos sólo si es necesario. Si Transbank recibe una transacción con valores inválidos, arrojará un error.

Cuando las transacciones fallan

Cuando se recibe un resultado de Transbank, estas se verifican y validan con las credenciales de tu comercio y Transbank.

Cuando no hay ningún error grave que interrumpa el proceso de la transacción (para eso son las excepciones) los resultados dispondrán de un método llamado isSuccess().

Cuando todo está bien, isSuccess() entrega true. Si la transacción falló por cualquier razón esperada, el método entregará false, por lo que podrás usar tu propia lógica para entregar el error al usuario.

Puedes usar getErrorCode(), que devolverá el código de error. También puedes usar getErrorForHumans() que devolverá un pequeño texto en español detallando cuál fue el problema, si la traducción está disponible (sino, devolverá null).

<?php

if (!$transaction->isSuccess()) {
    
    echo $transaction->getErrorCode(); // -6
    echo $transaction->getErrorForHumans(); // "La transacción excede cupo máximo mensual"
    
}

Excepciones y TransbankException

Cuando ocurren errores graves, este paquete lanzará una excepción que implementa TransbankException. De esta forma, podrás identificar la excepción en tu aplicación, y por ejemplo, mostrarle un error al usuario en vez de detener toda la ejecución con mensajes crípticos que seguro solo tú entenderás.

<?php

try {
    $result = $transaction->getResult();
} catch (TransbankException $exception) {
    
    // Vamos a grabar el registro que nos tira la excepción para verla más tarde.
    error_log($exception);
    
    // Y finalizar diciéndole al usuario que algo pasó.
    return "Parece que Transbank no está disponible. Inténtalo más tarde.";
}

Específicamente, las excepciones en este paquete se lanzarán cuando ocurran errores que detengan el flujo de una transacción: mala configuración, transacción con datos inválidos, timeout de la red, código de comercio inexistente, firmas inválidas, certificados inválidos, error interno de Transbank, etcétera.

Si existe una excepción del paquete Transbank SDK oficial, también se anexará para que no pierdas la pista.

Por defecto, este paquete no usa error_log(). Si necesitas logear cosas, usa el Logger incluido.

⬅ Home | 3 - Operaciones Webpay ➡