API Referencia
undefined

Cómo empezar

Para empezar a integrar los productos de Transbank, te recomendamos usar nuestros SDK, disponibles para múltiples lenguajes de programación y plataformas. En general, existe un único Transbank SDK para el backend de tu e-commerce, el cual te permite operar con todos nuestros productos.

Adicionalmente, existen SDKs especializados para algunos productos y plataformas que requieren integraciones más allá del backend, como en el caso de Onepay.

En esta sección veremos los pasos para comenzar con el SDK que corresponda al lenguaje de programación que utilices en tu backend. Para los SDKs específicos a Onepay, visita la sección dedicada a ese producto.

Flujo de Integración

Inicialmente el comercio tendrá algunas tareas necesarias que realizar mientras ocurre el proceso de integración. A continuación, puedes conocer el flujo completo.

Flujo de integración

Instalación SDK

Para instalar el SDK, debes agregarlo al gestor de dependencias de tu lenguaje:

En Java debes agregar esta entrada en tu archivo pom.xml de Maven:

<dependency>
    <groupId>com.github.transbankdevelopers</groupId>
    <artifactId>transbank-sdk-java</artifactId>
    <version>{mira-en-github-la-ultima-version-disponible}</version>
</dependency>

Te recomendamos leer las instrucciones de instalación detalladas para el SDK Java para más opciones e información de la última versión disponible.

En PHP puedes usar composer (si no lo tienes, puedes instalarlo desde acá) para descargar la última versión del SDK, ejecutando esto en la línea de comandos cuando estés en la raíz de tu proyecto:

composer require transbank/transbank-sdk

Te recomendamos leer las instrucciones de instalación detalladas para el SDK PHP para más opciones de instalación.

En Node.js se debe instalar por NPM o Yarn, ejecutando esto en la línea de comandos cuando estés en la raíz de tu proyecto:

NPM

npm install transbank-sdk --save

además, necesitar tener intalado openssl de manera global

npm install -g openssl

Yarn

yarn add transbank-sdk

Te recomendamos leer las instrucciones de instalación detalladas para el SDK Node.js para más opciones de instalación.

En .NET puedes instalar el SDK desde la línea de comandos del Package Manager de Visual Studio:

PM> Install-Package TransbankSDK

Te recomendamos leer las instrucciones de instalación detalladas para el SDK .NET para más opciones de instalación.

En Ruby puedes instalar el SDK como una gema:

gem install transbank-sdk

Te recomendamos leer las instrucciones de instalación detalladas para el SDK Ruby para más opciones de instalación.

(Para Webpay en Ruby puedes seguir usando libwebpay u otra alternativa)

En Python puedes instalar el SDK desde PyPI:

pip install transbank-sdk

Te recomendamos leer las instrucciones de instalación detalladas para el SDK Python para más opciones de instalación.

(Para Webpay en Python puedes seguir usando libwebpay, pero te recomendamos usar python-tbk, creada por Cornershop que será la base de lo que integremos finalmente en transbank-sdk)

Ambientes

Transbank provee dos ambientes: Integración y Producción.

Ambiente de Integración: En este ambiente el comercio realiza la integración del producto a contratar y testea su solución de medio pago.

Ambiente de producción: En este ambiente el comercio operará luego de finalizar el proceso de puesta en producción y realizará transacciones con tarjetas de crédito o débito reales.

Ambiente de integración

Para las transacciones Webpay en estos ambientes se deben usar estas tarjetas:

  • VISA 4051885600446623, CVV 123, cualquier fecha de expiración. Esta tarjeta genera transacciones aprobadas.
  • MASTERCARD 5186059559590568, CVV 123, cualquier fecha de expiración. Esta tarjeta genera transacciones rechazadas.
  • Redcompra 4051884239937763 genera transacciones aprobadas (para operaciones que permiten débito Redcompra y prepago)
  • Redcompra 5186008541233829 genera transacciones rechazadas (para operaciones que permiten débito Redcompra y prepago)

Cuando aparece un formulario de autenticación con RUT y clave, se debe usar el RUT 11.111.111-1 y la clave 123.

En cuanto al comercio, en este ambiente puedes usar las credenciales genéricas provistas por Transbank que te permiten hacer pruebas rápidamente (pues vienen pre-configuradas en nuestros SDKs). Si tienes prisa, puedes ir directo a ver como probar nuestros productos en este ambiente:

En el caso de requerir los códigos de comercio de integración son los siguientes:

Producto Código de comercio
Webpay Plus 597020000540
webpay PLus Mall
tienda 1
tienda 2		 597044444401
597044444402
597044444403
Webpay Plus Captura Diferida 597044444404
Oneclick 597044444405
Oneclick Mall
tienda 1
tienda 2		 597044444429
597044444430
597044444431

Para mayor detalle de las credenciales puedes visitar el repositorio GitHub transbank-webpay-credenciales

Seguridad

Los servicios Web de Transbank están protegidos para garantizar que solamente miembros autorizados por Transbank hagan uso de las operaciones disponibles.

El mecanismo de seguridad implementado está basado en un canal de comunicación seguro TLS 1.2 sumado a WS-Security (para servicios SOAP) o API Keys + Mensajes firmados (para servicios REST). Esto provee autenticación, confidencialidad e integridad a los Servicios Web.

Los plugins y SDK para Webpay que distribuye Transbank ya están construidos con las librerías necesarias para realizar las validaciones requeridas, pero es deber del comercio asegurarse que la solución o desarrollo de medio de pago que utilice, cumpla con los protocolos de seguridad.

Deberes del Comercio

Actualizaciones de plugins y SDK

Si el comercio está utilizando una solución basada en Plugins o SDK, debe estar atento a las actualizaciones que periódicamente Transbank realizará. Estas actualizaciones pueden responder a mantener compatibilidad con los CMS o Shopping Cart, modificaciones por seguridad, adición de propiedades o funciones, o correcciones a las comunicaciones. La comunicación oficial siempre se realizará a través del sitio http://www.transbankdevelopers.cl.

Uso de HTTPS

Los servidores del comercio tanto en ambientes de integración como en ambiente de producción deben hacer uso de HTTPS para sus endpoints web (tanto de cara al tarjetahabiente como en los callbacks expuestos a Transbank). El no uso de HTTPS puede provocar problemas en las redirecciones en navegadores modernos (ej: Safari en iOS 11.3 o superior), impidiendo que se complete el flujo de pago.

Validación de firmas

Todo comercio que utiliza Webpay mediante servicios web DEBE velar por la seguridad de las transacciones, bajo el esquema del servicio ofertado por Transbank. En cada operación que exista una firma electrónica es OBLIGACIÓN de la parte receptora validar dicha firma.

Validación de montos y órdenes de compra

El comercio debe verificar al completar cualquier transacción que los valores informados por Transbank (monto de la compra, buyOrder, etc.) coinciden con los valores entregados por el comercio al principio del flujo transaccional.

Puesta en Producción

  1. Una vez que el comercio determine que ha finalizado su integración, se debe realizar un proceso de validación. Si realizaste la integración con un plugin, considera que junto con la planilla de integración, debes generar tus credenciales y enviar el certificado público y el logo (GIF, 130x59) a soporte@transbank.cl.

  2. Posterior a que Transbank confirme que la planilla de integración se encuentra correcta (no aplica para plugins), se solicitará al comercio la generación de las credenciales (llave privada y certificado publico). El certificado público debe ser enviado junto al logo del comercio (GIF, 130x59) a soporte@transbank.cl para su registro.

  3. Transbank informará via correo electrónico el correcto registro del certificado público enviado por el comercio. Posterior a ello, será necesario cambiar la configuración del e-commerce para funcionar en producción

  4. Con la configuración del ambiente de producción ya lista, será necesario realizar una compra de $10 para validar el correcto funcionamiento.

Credenciales en Onepay

En el caso de Onepay las credenciales consisten en:

  • Un API Key
  • Un secreto ("shared secret").

Estos valores serán provistos por Transbank y en su conjunto permiten hacer transacciones a nombre del comercio. Debes custodiar estas credenciales para evitar que caigan en manos de terceros.

Credenciales en Webpay

En el caso de Webpay, las credenciales consisten en:

  • Un código de comercio.
  • Una llave privada.
  • Un certificado público.

La llave y el certificado (autofirmado) deben ser generados por el comercio, con la condición de que el common name del certificado debe coincidir con el código de comercio indicado por Transbank.

Para generar estas credenciales tendrás que estar en una línea de comandos y disponer de OpenSSL versión 1.0. Los pasos son los siguientes (debes reemplazar "597029124456" por tu código de comercio):

  1. Crear llave privada:

       openssl genrsa -out 597029124456.key 2048

  2. Crear requerimiento de certificado:

       openssl req -new -key 597029124456.key -out 597029124456.csr

   Country Name (2 letter code) []:CL
   State or Province Name (full name) []:
   Locality Name (eg, city) []:SANTIAGO
   Organization Name (eg, company) []:
   Organizational Unit Name (eg, section) []:
   Common Name (eg, your name or your server’s hostname) []:597029124456
   Email Address []:
   Please enter the following ‘extra’ attributes
   to be sent with your certificate request
   A challenge password []:
   An optional company name []:

  3. Crear certificado autofirmado:

     openssl x509 -req -days 1460 -in 597029124456.csr -signkey 597029124456.key -out 597029124456.crt

Finalmente debes enviar a Transbank el certificado público (597029124456.crt) y guardar el certificado y también su llave privada (597029124456.key), los que junto a tu código de comercio te permitirán transaccionar. Debes custodiar esa llave privada para evitar que caiga en manos de terceros.

El proceso de validación y puesta en producción

Durante la validación de la integración se pretende verificar que el comercio transacciona de manera segura y sin problemas, por lo que se solicitarán una serie de pruebas y su posterior envío de evidencias para validar la integración. Esta validación es requisito necesario para dejar al comercio en producción y no se permitirá que un comercio utilice productivamente el servicio Webpay sin poseer una validación.

Transbank solo validará las integraciones de aquellos comercios que tengan un código de comercio productivo. Para obtenerlo, sigue las instrucciones en cómo hacerse cliente en el portal http://www.transbank.cl o contacte a su ejecutivo comercial.

En esta etapa, el comercio envía las evidencias a soporte@transbank.cl empleando el formulario correspondiente al producto integrado indicando claramente las órdenes de compra, fecha y hora de las transacciones. Para integraciones Webpay que utilicen algún plugin oficial existe un formulario especial.

Descargar el formulario de envidencias...

  • Para integraciones Webpay: [No se aceptan nuevas integraciones SOAP]
  • Para integraciones Webpay que usen un plugin oficial: [No se aceptan nuevas integraciones SOAP]
  • Para integraciones Onepay: [No se aceptan nuevas integraciones SOAP]

Soporte validará que los casos de prueba sean consistentes con los registrados en los sistemas de Webpay y, de estar todo correcto, se le notificará al comercio la conformidad para pasar a producción, recibiendo las instrucciones para ello. De no estar consistentes las pruebas, se le hará alcances al comercio respecto de su integración, para que realices las correcciones correspondientes y vuelvas a enviar las evidencias una vez terminadas dichas correcciones.

Una vez que soporte te comunique formalmente que la integración está aprobada, deberá seguir los pasos que le indican para pasar a producción y poder comenzar a transaccionar de manera real.

Estos pasos incluyen cambio en el ambiente sobre el que transacciona, pasando de integración a producción, además de las instrucciones de creación de credenciales.

Durante el paso a producción se te exigirá realizar, al menos, una transacción de prueba real, con la que finalizará oficialmente la puesta en producción.

Configuración para producción utilizando los SDK

Si estás utilizando algún SDK oficial de Transbank y quieres pasa al ambiente de producción será necesario seguir los siguiente pasos.

  1. Remover la configuración para el ambiente de pruebas

    Antes de crear la nueva configuración para el ambiente de producción será necesario eliminar la actual comfiguración para el ambiente de pruebas que cumple con el siguiente formato Configuration.ForTestingWebpayPlusNormal()

  2. Crear un nuevo elemento Configuration

       const configuration = new Transbank.Configuration()

  3. Asignar el código de comercio productivo, entregado por Transbank al momento de contratar el producto.

       const configuration = new Transbank.Configuration()
                           .withCommerceCode(/* tu código de comercio */)

  4. Configuración de la llave privada (.key para Java y PHP .pfx o .p12 para .NET) generada por el comercio en la etapa previa.

       const configuration = new Transbank.Configuration()
                           .withCommerceCode(/* tu código de comercio */)
                           .withPrivateCert(/* tu certificado privado en forma de string */)

  5. Configuración del certificado público (.crt) enviado a Transbank para su registro. En el caso de .NET no es necesario configurar el .crt pero se debe configurar el password asignado a la llave privada.

       const configuration = new Transbank.Configuration()
                           .withCommerceCode(/* tu código de comercio */)
                           .withPrivateCert(/* tu certificado privado en forma de string */)
                           .withPublicCert(/* tu certificado público en forma de string */)

  6. Selección del ambiente productivo.

     const configuration = new Transbank.Configuration()
                         .withCommerceCode(/* tu código de comercio */)
                         .withPrivateCert(/* tu certificado privado en forma de string */)
                         .withPublicCert(/* tu certificado público en forma de string */)
                         .usingEnvironment(Transbank.environments.production) // Se define el ambiente como producción

  7. Crear elemento Webpay utilizando la configuración de producción.

const configuration = new Transbank.Configuration()
                        .withCommerceCode(/* tu código de comercio */)
                        .withPrivateCert(/* tu certificado privado en forma de string */)
                        .withPublicCert(/* tu certificado público en forma de string */)
                        .usingEnvironment(Transbank.environments.production) // Se define el ambiente como producción

const transaction = new Transbank.Webpay(configuration);

Requerimientos de páginas de transición y de fin de transacción

Webpay

La página de transición de comercio, es la página que muestra el comercio cuando Webpay le entrega el control, después del proceso de autorización y previo a redirigir al tarjeta habiente al comprobante de éxito de la transacción. Aplica para todos los tipos de transacciones.

Una vez finalizada a transacción, el comercio debe presentar una página al tarjetahabiente para que este se informe del resultado de la transacción. La información a presentar dependerá de si la transacción fue autorizada o no.

Se recomienda, como mínimo, que posea:

  • Número de orden de Pedido
  • Nombre del comercio (Tienda de Mall)
  • Monto y moneda de la transacción
  • Código de autorización de la transacción
  • Fecha de la transacción
  • Tipo de pago realizado (Débito o Crédito)
  • Tipo de cuota
  • Cantidad de cuotas
  • 4 últimos dígitos de la tarjeta bancaria
  • Descripción de los bienes y/o servicios

Cuando la transacción no sea autorizada, se recomienda informar al tarjetahabiente al respecto. Puede presentar un texto explicativo como:

Orden de Compra XXXXXXX rechazada
Las posibles causas de este rechazo son:
* Error en el ingreso de los datos de su tarjeta de Crédito o Débito (fecha y/o código de seguridad).
* Su tarjeta de Crédito o Débito no cuenta con saldo suficiente.
* Tarjeta aún no habilitada en el sistema financiero.

¿Tienes alguna duda de integración?

Únete a la comunidad de integradores en Slack y comparte buenos tips ayudando a los nuevos o buscando soluciones alternativas. Nuestro equipo está ahí para ayudarte.

Si aún tienes dudas envíanos un mensaje

Envíanos un mensaje.
Si necesitas resolver algún tipo de incidencia en el portal o si existe algún problema con tu integración y que no has podido resolver, contáctanos a través de nuestro formulario.