Dependiendo del uso de la versión REST o SOAP de Transbank los métodos cambian, pero la idea es la misma. En los ejemplos usaré la configuración del ambiente de integración
Paso 1: Crear la Transaccion
Voy a hacer un par de funciones para traerme una transacción lista para que tú mandes al cliente a trasbank:
En REST inicias una transacción usando Transaction::create:
use Transbank\Webpay\WebpayPlus\Transaction;
use Transbank\Webpay\Options;
function createRestTransaction($buyOrder, $amount) {
$config = Options::defaultConfig();
return Transaction::create(
$buyOrder,
session_id(),
$amount,
TU_URL_FINAL,
$config
);
}
En SOAP se usaba initTransaction:
use Transbank\Webpay\Webpay;
use Transbank\Webpay\Configuration;
function createSoapTransaction($buyOrder, $amount) {
$config = Configuration::forTestingWebpayPlusNormal();
$transaction = (new Webpay($config))->getNormalTransaction();
return $transaction->initTransaction(
$amount,
$buyOrder,
session_id(),
TU_URL_DE_TRANSICION, // esto nunca supe para qué
TU_URL_FINAL
);
}
Fíjate que en ambas API lo relevante son $buyOrder
y $amount
. El resto se saca de constantes (tus url) o son valores efímeros (la sesión)
Tú quieres hacer una tabla de pedidos que tiene esos campos
quiero almacenar las Ordenes de Compra ..., con los campos •ordencompra •cantidad •precio •total
Genial, siempre que ordencompra sea único y ojalá hasta llave primaria. En ese caso un ejemplo muy burdo usando PDO y sin procuparme de capturar excepciones (con suerte me di el trabajo de usar sentencias preparadas!) sería
$ordencompra=time(); // esto no lo uses en producción!
$precio = 100; //tú sabrás cuanto vale
$cantidad = 2; // y cuantas unidades son
$total = $precio * $cantidad;
Con esos datos podrías tanto generar una transacción como guardar en tu tabla.
Pero esa tabla no estaría completa sin el campo token
Cuando creas esa transacción te dará un token:
// en rest
$token = createRestTransaction($ordencompra,$total)->getToken();
// o en SOAP
$token = createSoapTransaction($ordencompra,$total)->token;
Y tú como ya debes saber con ese token haces un formulario donde el cliente termina en la pasarela de pago.
Justo antes de eso tú creas el registro porque, comprensiblemente, quieres almacenar incluso los casos donde el proceso no se completa.
(de nuevo, lo encapsularé en una función). El parámetro $conn es la conexión a tu BBDD en este ejemplo burdo
function storeOrdenCompra($conn, $ordencompra, $cantidad, $precio, $token)
$stmt = $conn->prepare(
"INSERT INTO ordenes (ordencompra,cantidad,precio,total,token)
values (:buyOrder, :cantidad, :precio,:amount, :token)"
);
$stmt->execute([
':ordencompra'=>$ordencompra,
':cantidad'=>$cantidad,
':precio'=>$precio,
':amount'=>$cantidad*$precio,
':token'=>$token
]);
}
Además, a tu tabla debieras ponerle un campo status
y marcas de tiempo created_at
y updated_at
.
Paso 2: Verificar la Transaccion
En el camino feliz el cliente completa el procedimiento y Transbank lo devuelve a la URL donde esperas esa respuesta. Ese request que transbank hace hacia tu sitio contiene un parámetro token_ws
.
En la versión SOAP era en el body de una petición POST. En la versión REST lo cambiaron o cambiarán para que vaya en el query string de una petición GET.
Sea como sea, si tienes el $token puedes ejecutar el último paso que es acusar recibo de la operación. Si no lo haces en 30 segundos, eventualmente Transbank hará una reversa. El paso 2 necesita únicamente el token, y no se puede hacer sin el token.
Si usas el API Rest
En Rest puedes usar una única vez el método commit
// Rest
use Transbank\Webpay\WebpayPlus\Transaction;
$response = Transaction::commit($token);
Esa respuesta tiene la forma de una instancia (TransactionCommitResponse) de la cual puedes obtener muchos datos (algunos ya los tienes, otros son irrelevantes, otros sí importan mucho), de entre los cuales el status te dice si pasó o no pasó la transacción.
De la documentación REST:
campo |
significado |
status |
Estado de la transacción (INITIALIZED, AUTHORIZED, REVERSED, FAILED, NULLIFIED, PARTIALLY_NULLIFIED, CAPTURED). Largo máximo: 64 |
-- |
-- |
El método commit ejecuta un request PUT hacia Transbank, pero si ya lo ejecutaste o quieres saber el status antes de commitear, puedes usar
$response = Transaction::getStatus($token);
Que ejecuta un request de tipo GET y devuelve una instancia de TransactionStatusResponse, la cual es casi 100% idéntica a la respuesta del commit salvo porque los 4 últimos dígitos de la tarjeta se obtienen con el método getCardNumber
en uno y con getCardDetails
en el otro.
Dejo el ejemplo de Transbank donde puedes ver los métodos de $response
$response->getVci();
$response->getAmount();
$response->getStatus();
$response->getBuyOrder();
$response->getSessionId();
$response->getCardDetail();
$response->getAccountingDate();
$response->getTransactionDate();
$response->getAuthorizationCode();
$response->getPaymentTypeCode();
$response->getResponseCode();
$response->getInstallmentsAmount();
$response->getInstallmentsNumber();
$response->getBalance();
Si usas el API SOAP
En soap se utiliza el método getTransactionResult
// Soap
use Transbank\Webpay\Webpay;
use Transbank\Webpay\Configuration;
$config = Configuration::forTestingWebpayPlusNormal();
$transaction = (new Webpay($config))->getNormalTransaction();
$result = $transaction->getTransactionResult($token)
Este método obtiene el status de autorización de la transacción (equivalente al getStatus) pero por debajo lanza un segundo request donde llama al método acknowledgeTransaction
que posiblemente tire un error si ya lo comprobaste antes.
Lo importante es el status
así que no nos distraigamos. El $result
tiene un cierto output
y éste a su vez un cierto responseCode
.
$output = $result->detailOutput;
$status = $output->responseCode;
El status=0
indica éxito. Todos los demás son errores con distintos grados de misterio
Código |
Significado |
0 |
Transacción aprobada |
-1 |
Rechazo de transacción - Reintente (Posible error en el ingreso de datos de la transacción) |
-2 |
Rechazo de transacción (Se produjo fallo al procesar la transacción. Este mensaje de rechazo está relacionado a parámetros de la tarjeta y/o su cuenta asociada) |
-3 |
Error en transacción (Interno Transbank) |
-4 |
Rechazo emisor (Rechazada por parte del emisor) |
-5 |
Rechazo - Posible Fraude (Transacción con riesgo de posible fraude) |
Dejo el ejemplo que pone Transbank porque salen las propiedades de $result y de $output
if ($output->responseCode == 0) {
// Transaccion exitosa, puedes procesar el resultado
// con el contenido de las variables $result y $output.
$result->buyOrder;
$result->sessionId;
$result->cardDetail->cardNumber;
$result->cardDetail->cardExpirationDate;
$result->accountingDate;
$result->transactionDate;
$result->vci;
$result->urlRedirection;
$output->authorizationCode;
$output->paymentType;
$output->amount;
$output->sharesNumber;
$output->commerceCode;
$output->buyOrder;
}
Actualizar el registro en BBDD
Con ese status puedes actualizar el registro, que habrás identificado usando el token. En la práctica, con solo saber un token ya puedes entrar a todo el flujo "Paso 2"
Paso 3 Manejo de transacciones interrumpidas
En REST el flujo, si no se ha completado en 5 minutos, se considera fallido. La documentación del API SOAP habla de 10 minutos, pero le creo más a la documentación REST que está más actualizada
Eso significa:
Para el cliente: que si inició un pago en tu sitio, y al llegar a la pasarela Webpay se fue a hacer un sandwich, si demora más de ese lapso tendrá que empezar de nuevo. Se le redirige a tu URL final en donde tu backend verá que la transacción falló.
Para la tienda: que si un proceso de pago figura como pendiente en Transbank y pasó ese lapso, no necesitas seguirlo actualizando una y otra vez. Ya puedes darlo como fallido.
Sabiendo eso tú puedes agendar un cron que cada 5 minutos se traiga todos los registros que se crearon hace más de 5 minutos y siguen sin status.
Dejo una estructura posible para la tabla, en donde la llave primaria es la orden de compra. Es vez de definirla como autoincremental estoy usando:
create table ordenes
(ordencompra bigint(21) unsigned
default uuid_short()
not null
primary key
-- etc etc
)
y más adelante explicaré por qué valdría la pena el esfuerzo extra
create table ordenes
(
ordencompra bigint(21) unsigned
default uuid_short()
not null
primary key,
precio float null,
cantidad int null,
total int null,
token varchar(64) null,
status int null,
created_at datetime default current_timestamp()
not null,
updated_at datetime default current_timestamp()
not null on update current_timestamp(),
constraint token unique (token)
);
Entonces los casos que quedaron "abandonados" son aquellos cuyo created_at
tenga más de 5 minutos y cuyo status
sea null.
SELECT token from ordenes
WHERE created_at < date_sub( current_timestamp, interval 300 second )
AND status is null
Por cada uno de ellos podrás llamar a commit o a getTransactionResult y actualizarlos, probablemente como fallidos, porque como dije más arriba, con el token ya sabes todo
4. Opcionalmente, generar buyOrders únicos
Es buena práctica delegar la generación de IDs únicos en vez de armarlos uno mismo. Sugiero esto teniendo en consideración que si usas el timestamp o un autoincremental, en el ambiente de desarrollo donde todos tenemos el mismo commerceCode, tarde o temprano habrá colisiones con los buyOrders de otros desarrolladores. En producción, donde tienes un commerceCode único, igual ppodrías estar facilitando que un usuario malicioso enumerase tus transacciones.
En la actualizad la manera elegante de generar un identificador realmente único es usar UUIDs. Lo malo es que Transbank sólo acepta 26 caracteres en el buyOrder (y los uuid necesitan 36). Como sustituto se podría usar por ejemplo UUID_SHORT.
// en vez de $ordencompra = time();
$ordencompra=$conn->query('SELECT uuid_short()')->fetch(\PDO::FETCH_COLUMN);
Sin ánimo de recomendar los UUID_SHORT por sobre otro enfoque, me limito a contextualizar que éstos son un pariente más simple de los verdaderos UUIDs. Combinando un id de servidor, más su timestamp de inicio, más un autoincremental global, obtienes un número de 17 cifras que es único en todas las bases de datos de todos los servidores de un mismo cluster.
En teoría se te puede repetir un UUID_SHORT si se cumplen 3 condiciones:
- tienes más de 255 servidores (el id del servidor 256 sería 1)
- los servidores que comparten ID inician con menos de 1 segundo de diferencia
- generas más de 16M de UUID_SHORT por segundo
Su suponemos que todos los desarrolladores que usamos Transbank implementamos este enfoque, y todos tenemos un solo servidor con id=1, crucemos los dedos para que no hayamos iniciado mysql al mismo tiempo o bien repartámonos los 16 millones.
EDIT: Actualizar la fecha de transacción
De seguro hay muchos datos de la transacción que quieres persistir, y no viene al caso detenerme en cada uno. (authorizationCode
es muy importante conservarlo si más adelante quieres anular total o parcialmente la transacción), pero es posible que a más de alguien le cause confusión la fecha de transacción que devuelven estos métodos dado que el formato requiere cierta transformación para meterlo en mysql.
Primero, si añades esa fecha con:
alter table ordenes
add transaction_date datetime default null null after token;
Si usas REST
En rest obtienes la fecha de transacción via
$txDate = $result->getTransactionDate();
(y da lo mismo si ese $result
viene del método commit
o de getStatus
, esas dos clases son casi idénticas). Me comentaste que la fecha obtenida por este método era algo como:
2021-01-11T02:47:27.237-03:00
Si usas SOAP
En el API Soap la salida de getTransactionResult
tiene una propiedad equivalente:
$txDate = $result->transactionDate;
Según la documentación SOAP la fecha viene en un formato medio exótico
campo |
descripcion |
accountingDate |
Fecha de la autorización. Largo: 4, formato MMDD |
transactionDate |
Fecha y hora de la autorización. Largo: 6, formato: MMDDHHmm |
Supongo que cambiaron de opínión, porque hoy responden con formato ISO_8601
2021-01-31T07:44:39.579Z,
La fecha ISO siempre se refiere a UTC. Esa Z se toma como si dijera 2021-01-31T07:44:39.579+00:00
Finalmente
Tanto si viene con el time offset explícito o se infiere del formato ISO, son strings parseables para PHP.
$dateTimeInstance = \DateTime::createFromFormat(
'Y-m-d\TH:i:s.uT',
'2021-01-11T02:47:27.237-03:00'
);
o bien
$dateTimeInstance = \DateTime::createFromFormat(
'Y-m-d\TH:i:s.u\Z',
'2021-01-31T07:44:39.579Z'
);
Con eso tengo un objeto DateTime que puedo manipular, primero ajustándola a la zona horaria UTC (a menos que de verdad quieras usar fecha local)
$dateTimeInstance
->setTimezone(new DateTimeZone('UTC'));
Y luego devolviéndola a string con el formato que le gusta a MySQL
$created_at_nice = $dateTimeInstance
->format('Y-m-d H:i:s');
Eso te vevuelve la fecha formateada para mysql.
echo \DateTime::createFromFormat(
'Y-m-d\TH:i:s.uT',
'2021-01-11T02:47:27.237-03:00'
)->setTimezone(
new DateTimeZone('UTC')
)->format('Y-m-d H:i:s');
// imprime: 2021-01-11 05:47:27
Y qué es Transbank??
Para los lectores de países donde no opera Transbank:
Transbank es la única empresa en Chile autorizada a procesar tarjetas de crédito. Esto desde 1989 cuando la sociedad compró la representación de VISA y Mastercard a un conocido empresario. Su exclusividad y estructura de propiedad casi 100% bancaria de vez en cuando genera controversias
El API, que se estancó por unos años, se ha ido modernizando vertiginosamente desde el 2019, pasando de SOAP a REST, añadiendo nuevas modalidades de pago y publicando SDKs para más y más lenguajes, amén de plugins para WooCommerce, Magento y casi todos los SaaS ecommerce. Todo eso está más o menos bien documentado en TransbankDevelopers.cl