How to start
To start integrating Transbank products, we recommend using our SDKs and plugins, available for multiple programming languages and platforms. In general, there is a single Transbank SDK for the backend of your e-commerce, which allows you to operate with all our products.
If you want to implement Webpay Plus, we recommend you review our official plugins .
In this section we will see the steps to get started with the SDK that corresponds to the programming language you use in your backend.
Integration Flow
Initially, the merchant will have some business tasks to perform while the integration process occurs. This commercial affiliation process can be carried out in parallel to the technical integration process.
Below, you can know the complete flow.
Become a Client
Complete the membership form on our portal publico.transbank.cl , sign it digitally and you will receive your merchant code in the email you registered.
Integrate
Integrate the payment method into your website or application. Check out the tools available at Transbank Developers and Slack .
Valid
To validate your integration and verify that it works correctly, go to Transbank Developers, and complete the validation form . You can make inquiries at soporte@transbank.cl
Sell
Once the validation process is complete, you will be assigned a private key (Tbk-Api-Key-Secret) . Set it up in your app or website and you're ready to sell!
Technical integration process
This process contemplates all the necessary tasks that the business must carry out to integrate the contracted product within its systems.
A) Using a plugin
If you want to implement Webpay Plus with any of our official plugins, check their specific documentation . In that case, the process is simpler and does not require writing code as in the case of SDKs, since it is enough to install and configure the plugin on the platform you are using.
B) Using an SDK
To install the SDK, you must add it to your language's dependency manager:
In Java you must add this entry in your Maven pom.xml file:
<dependency>
<groupId>com.github.transbankdevelopers</groupId>
<artifactId>transbank-sdk-java</artifactId>
<version>{mira-en-github-la-ultima-version-disponible}</version>
</dependency>
We recommend reading the detailed installation instructions for the Java SDK for more options and information on the latest version available.
In PHP you can use composer (if you don't have it, you can install it from here ) to download the latest version of the SDK, by running this on the command line when you're in the root of your project:
composer require transbank/transbank-sdk:^5.0
We recommend reading the detailed installation instructions for the PHP SDK for more installation options.
In .NET you can install the SDK from the Visual Studio Package Manager command line:
PM> Install-Package TransbankSDK
We recommend reading the detailed installation instructions for the .NET SDK for more installation options.
In Ruby you can install the SDK as a gem:
gem install transbank-sdk
We recommend reading the detailed installation instructions for the Ruby SDK for more installation options.
In Python you can install the SDK from PyPI:
pip install transbank-sdk
In NodeJS you can install the SDK from NPM:
npm install transbank-sdk
We recommend reading the detailed installation instructions for the Python SDK for more installation options.
C) Using the REST API
You can also consume the REST API of the products directly. If you use a programming language that does not have an official SDK or simply want to connect directly to the API, you should review the REST API Reference in the "http" tab to know the different endpoints of each product, their input parameters and response parameters. .
Examples
Para ayudarte a entender la integración de mejor forma disponemos de un índice de proyectos de ejemplo que puedes acceder a través de este link
Environments
Transbank provides two environments: Integration and Production .
Integration environment: In this environment, the merchant performs the integration of the product to be contracted and tests its half-payment solution.
HOST: https://webpay3gint.transbank.cl
Production environment: In this environment, the business will operate after finishing the start-up process and will carry out transactions with real credit, debit or prepaid cards.
HOST: https://webpay3g.transbank.cl
Integration environment
In the integration environment, there are previously created merchant codes for all products (Webpay Plus, Oneclick Mall, etc.), for each of their modalities (Deferred Capture, Mall, Deferred Capture Mall, etc.) and depending on the currency they accept. (USD or CLP).
Make sure you are using the integration merchant code that has the same settings as the product you purchased.
Test cards
For Webpay transactions in the integration environment, these test cards must be used:
| card type | Detail | Result |
|---|---|---|
| VISA | 4051 8856 0044 6623 CVV 123 any expiration date |
Generates approved transactions. |
| AMEX | 3700 0000 0002 032 CVV 1234 any expiration date |
Generates approved transactions. |
| MASTERCARD | 5186 0595 5959 0568 CVV 123 any expiration date |
Generates declined transactions. |
| Redcompra | 4051 8842 3993 7763 | Generate approved transactions (for operations that allow Redcompra debit) |
| Redcompra | 4511 3466 6003 7060 | Generate approved transactions (for operations that allow Redcompra debit) |
| Redcompra | 5186 0085 4123 3829 | Generates rejected transactions (for operations that allow Redcompra debit) |
| Prepaid VISA | 4051 8860 0005 6590 CVV 123 any expiration date |
Generates approved transactions. |
| Prepaid MASTERCARD | 5186 1741 1062 9480 CVV 123 any expiration date |
Generates declined transactions. |
When an authentication form with RUT and password appears, the RUT 11.111.111-1 and the password 123 must be used.
Commerce codes
Below you will find all the merchant codes available in the integration environment. For all merchant codes, the secret key (Api Key Secret) is 579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C
| Product | Commercial Code |
|---|---|
| Webpay Plus | 597055555532 |
| Webpay Plus Deferred Capture | 597055555540 |
| Webpay Plus Mall | 597055555535 Mall597055555536 Store 1597055555537 Store 2 |
| Webpay Plus Mall Deferred Capture | 597055555581 Mall597055555582 Store 1597055555583 Store 2 |
| Oneclick Mall | 597055555541 Mall597055555542 Store 1597055555543 Store 2 |
| Oneclick Mall Delayed Capture | 597055555547 Mall597055555548 Store 1597055555549 Store 2 |
| Full Transaction | 597055555530 |
| Complete Transaction without CVV | 597055555557 |
| Deferred Complete Transaction | 597055555531 |
| Deferred Complete Transaction without CVV | 597055555556 |
| Complete Mall Transaction | 597055555573 Mall597055555574 Store 1597055555575 Store 2 |
| Complete Mall Transaction without CVV | 597055555551 Mall597055555552 Store 1597055555553 Store 2 |
| Complete Transaction Mall Deferred Capture | 597055555576 Mall597055555577 Store 1597055555578 Store 2 |
| Complete Mall Transaction Deferred Capture without CVV | 597055555561 Mall597055555562 Store 1597055555563 Store 2 |
| Patpass Commerce | 28299257 Código de comerciocxxXQgGD9vrVe4M41FIt Llave secreta (Api Key Secret) |
The validation process
During the validation of the integration, it is intended to verify that the merchant transacts safely and without problems, for which a series of tests will be requested and the subsequent sending of evidence to validate the integration. This validation is a necessary requirement to leave the business in production and a business will not be allowed to productively use the Webpay service without having a validation.
Transbank will only validate the integrations of those merchants that have a productive merchant code. To obtain it, follow the instructions on how to become a client on the portal http://www.transbank.cl or contact your commercial executive.
For integration with plugins , we created a new online form for you to start the validation process: Start integration form
For Webpay Plus, Webpay Plus Mall and OneClick Mall integrations (with SDK or direct API integration) , we have created a new online form for you to start the validation process: Start integration form
Para otro tipo de integraciones (PatPass, Transacción Completa), el comercio debe enviar 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.
Download the evidence form:
- For Webpay integrations that use an official plugin: use the form indicated above.
-
For Webpay Plus, Webpay Plus Mall and OneClick Mall integrations with SDK or direct API integration: use the form indicated above.
-
For Full Transaction integrations: Download
- For Patpass Commerce integrations: Download
For both validation processes (online form or sending documentation) you must have your store's logo (GIF or PNG 130x59 px).
Support will validate that the test cases are consistent with those registered in the Webpay systems and, if everything is correct, the merchant will be notified of the conformity to go into production, receiving the instructions for it. If the tests are not consistent, the business will be reached regarding its integration, so that you can make the corresponding corrections and re-send the evidence once said corrections are completed.
During the move to production you will be required to perform at least one real test transaction, which will officially end the go into production.
Start Production
- Once the merchant determines that its integration has been completed, a validation process must be carried out.
- Transbank will inform via email the result of the validation sent by the business. In case the validation is approved, Transbank will indicate the secret key ( API Key Secret ) to be able to use the production environment. After that, it will be necessary to change the e-commerce configuration to work in production
- With the configuration of the production environment ready, it will be necessary to make a purchase of $50 to validate the correct operation.
- You are already operating in production.
Webpay, Oneclick and Full Transaction
In the case of Webpay, the credentials consist of:
- A merchant code (Api-Key-Id).
- A secret key (Api-Key-Secret).
Get your Secret Key (validation process)
To use the production environment (where real money is used), you need to have your secret key , which is a special code that is associated with your trading code. To obtain it you need to pass a validation process, which is explained below .
At the end of this validation process, you will obtain your secret key .
A) Using Plugins
If you already have your production trade code and secret key, you just have to enter your plugin configuration ( see plugin documentation ) and place:
- Environment: Production
- Commerce Code: your production trading code
- Api Key: Your secret key
Upon saving, the plugin will work immediately in the production environment and you will be able to operate with real cards and transactions.
B) Using the SDKs
If you already have your production trade code and secret key, now you just have to configure your project to use the production environment, providing it with your credentials. We explain how to do it in the different SDKs by performing the following steps:
Define that the production environment will be used and pass the Api Key (Commerce Code) and the Api Key Secret (Key secret)
/**
* Todos los productos se pueden configurar de 2 formas:
* 1.- Pasando un objeto Options en su constructor.
* 2.- Utilizando los nuevos métodos de configuración
*/
//Uso del objeto Options (aplicable a todos los productos)
import cl.transbank.common.IntegrationType;
import cl.transbank.model.Options;
import cl.transbank.webpay.common.WebpayOptions;
import cl.transbank.webpay.webpayplus.WebpayPlus;
Options option = new WebpayOptions("commerceCode", "APIKey", IntegrationType.LIVE);
WebpayPlus.Transaction transaction = new WebpayPlus.Transaction(option);
//Uso de los métodos de configuración
//Webpay Plus
import cl.transbank.webpay.webpayplus.WebpayPlus;
WebpayPlus.Transaction transaction = WebpayPlus.Transaction.buildForProduction("commerceCode", "APIKey");
WebpayPlus.MallTransaction mallTransaction = WebpayPlus.MallTransaction.buildForProduction("commerceCode", "APIKey");
//Oneclick
import cl.transbank.webpay.oneclick.Oneclick;
Oneclick.MallInscription mallInscription = Oneclick.MallInscription.buildForProduction("commerceCode", "APIKey");
Oneclick.MallTransaction mallTransaction = Oneclick.MallTransaction.buildForProduction("commerceCode", "APIKey");
// Transacción Completa
import cl.transbank.webpay.transaccioncompleta.FullTransaction;
import cl.transbank.webpay.transaccioncompleta.MallFullTransaction;
FullTransaction fullTransaction = FullTransaction.buildForProduction("commerceCode", "APIKey");
MallFullTransaction mallFullTransaction = MallFullTransaction.buildForProduction("commerceCode", "APIKey");
// PatPass Comercio
// Es importante destacar que la clase Options para PatPass se importa desde una ruta distinta que en el resto de productos.
import cl.transbank.patpass.model.PatpassOptions;
import cl.transbank.patpass.PatpassComercio;
//Uso del objeto Options
PatpassComercio.Inscription patpassInscription = new PatpassComercio.Inscription(new PatpassOptions("commerceCode", "APIKey", IntegrationType.LIVE));
//Uso del método de configuración
PatpassComercio.Inscription patpassInscription = PatpassComercio.Inscription.buildForProduction("commerceCode", "APIKey");
C) Using the API directly
If you are consuming the API directly, you only have to worry about using the host corresponding to the production environment , the productive trading code and the secret key obtained in the validation process.
Result page requirements
The merchant result page is the page that the merchant shows when Webpay delivers the control, after the authorization process. Applies to all types of transactions.
Once the transaction is completed , the merchant must present a page to the cardholder so that he or she is informed of the result of the transaction. The information to present will depend on whether the transaction was authorized or not.
It is recommended, at a minimum, that you have:
- Order number
- Merchant Name
- Transaction amount and currency
- Transaction authorization code
- Transaction date
- Type of payment made (Debit or Credit)
- Amount of fees
- Last four digits of the bank card
- Description of the goods and/or services
When the transaction is not authorized , it is recommended to inform the cardholder about it. You can present explanatory text such as:
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.
Available products
The following products are available for you to integrate. Check its documentation here:
Security
Transbank's Web services are protected to ensure that only members authorized by Transbank make use of the available operations.
The implemented security mechanism is based on a TLS 1.2 secure communication channel added to WS-Security (for SOAP services) or API Keys + Signed Messages (for REST services). This provides authentication, confidentiality and integrity to the Web Services.
The plugins and SDK for Webpay distributed by Transbank are already built with the necessary libraries to carry out the required validations, but it is the duty of the merchant to ensure that the solution or development of the payment method used complies with the security protocols.
Merchant duties
Integration Recommendations
- Perform infrastructure vulnerability scans at least every three months.
- Keep all components up to date, including the operating system and plugins used.
- It uses encrypted communications with secure protocols.
- Implement protection against malware and against web attacks: choose a Web Application Firewall (WAF) or Intrusion Prevention System (IPS).
- When developing the websites and integrations follow the best practices of recognized entities, such as OWASP https://owasp.org/www-project-top-ten/
- Prefer access control restricted to authorized users only and allow access to the Administration Portal only from known, secure locations.
- Create strong passwords and always keep them safe.
- Back up the information (source code, data, etc.) in a location other than the main one.
- Constantly monitor suspicious activity (eg connections from unusual countries in transactions or excessive consumption) and support audit trails to trace any incident.
- Once a year, conduct audits with an external professional
API and SDK migration
If you need to migrate your current integration, either through direct integration with the API or through an SDK, we recommend downloading and reviewing the migration document in the following Link .
Plugin and SDK updates
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 e-commerces, modificaciones por seguridad, adición de propiedades o funcionalidades. La comunicación oficial siempre se realizará mediante la comunidad de Slack en el canal de Novedades.
También puedes revisar la última versión de los SDK en nuestra web de índice de proyectos de ejemplo
Use of HTTPS
Merchant servers both in integration environments and in production environments must use HTTPS for their web endpoints (both facing the cardholder and in the callbacks exposed to Transbank). Failure to use HTTPS can cause problems with redirects in modern browsers (eg Safari on iOS 11.3 or higher), preventing the payment flow from completing.
Validation of amounts and purchase orders
The merchant must verify when completing any transaction that the values reported by Transbank (purchase amount, buyOrder , etc.) coincide with the values delivered by the merchant at the beginning of the transaction flow.