Manual Webpay en Ingles

WEBPAY API
SOAP REFERENCE
TRANSBANK S.A.
SPECIFICATIONS HANDBOOK (V 1.0)
CONTENTS INTERACTIVE TABLE OF CONTENTS
Click on the chapter or page
number for direct access
1 CHANGE CONTROL 5
2 PREFACE 5
5 2.1 About this handbook

5 2.2 Audience
5 2.3 Feedback on this documentation
3 ABOUT WEBPAY 6
6 3.1 Introduction to Webpay

6 3.2 Webpay transaction types
7 3.3 Credit transactions authorization and capture
7 3.4 Nullifying transaction
8 3.5 Supported currencies
8 3.6 Cardholder authentication
8 3.7 Compatibility with web browsers
9 3.8 Payment types (products)
4 GENERAL CONSIDERATIONS 10
10 4.1 Communication
10 4.2 Security
10 4.3 Retailer responsibilities
10 4.3.1 Validation of request and response messages
10 4.3.2 Plugins and SDK update
5 WEBPAY API SOAP 11
11 5.1 API SOAP Security Aspects

11 5.1.1 General information

11 5.1.2 Key generation and self-signed certificate
6 INTEGRATION, INTEGRATION VALIDATION AND GO-LIVE TRANSITION 12
12 6.1 Webpay integration stages

12 6.1.1 Integration stage

12 6.1.2 Integration validation stage

13 6.1.3 Go-live transition stage
13 6.2 Environments
7 NORMAL AUTHORIZATION TRANSACTION 14
14 7.1 Description of Normal Authorization Transaction

15 7.2 Payment sequence in a normal transaction

15 7.2.1 Diagram

16 7.2.2 Sequence description
17 7.3 Alternative flow: Payment sequence in a normal transaction that has been nullified through payment form

17 7.3.1 Diagram

18 7.3.2 Description of payment sequence for a transaction that has been nullified through payment form
API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 2

18 7.4 Alternative flow: payment sequence in a normal transaction with timeout event

18 7.4.1 Diagram

19 7.4.2 Description of timeout sequence in normal transaction
19 7.5 Description of methods in a normal authorization transaction web service
19 7.5.1 initTransaction operation

20 7.5.2 getTransactionResult operation

20 7.5.3 acknowledgeTransaction operation
8 NORMAL MALL AUTHORIZATION TRANSACTION 23
23 8.1 Description of Normal Mall Authorization Transaction

24 8.2 Payment Sequence in a Normal Mall Authorization Transaction

24 8.2.1 Diagram

25 8.2.2 Sequence Description
26 8.3 Alternative Flow: nullified payment sequence in a Normal Mall Authorization Transaction through payment form

27 8.3.1 Description of alternative sequence, nullify
27 8.4 Alternative Flow: payment sequence in a Normal Mall Authorization Transaction with timeout event

27 8.4.1 Diagram

28 8.4.2 Description of alternative sequence, timeout
28 8.5 Description of methods in a payment sequence in a Normal Mall Authorization Transaction

28 8.5.1 initTransaction operation

29 8.5.2 getTransactionResult operation

31 8.5.3 AcknowledgeTransaction operation
9 ONECLICK TRANSACTION 32
32 9.1 Description of OneClick Transaction
32 9.2 Summary of Web service methods

32 9.3 Inscription on Oneclick
32 9.3.1 Description
33 9.3.2 Diagram

34 9.3.3 initInscription method
34 9.4 Eliminating user registration record
34 9.5 Oneclick Payment Transaction

35 9.6 Authorized Payments reversal
35 9.7 Detailed definition of Web Service methods
10 MALL ONECLICK TRANSACTION 37
37 10.1 Description of the Transaction

37 10.2 Web service methods summary
38 10.3 Mall Oneclick Registration
40 10.4 Eliminating user registration record

40 10.5 Mall Oneclick Payment Transaction
41 10.6 Reversal of authorized payments

41 10.7 Annulment of authorized payments
42 10.8 Annulment reversal

42 10.9 Web Service methods detailed definition

11 DEFERRED CAPTURE TRANSACTION 45
45 10.1 Description of deferred capture

45 10.2 Description of the Web Service method of deferred capture

45 10.2.1 Capture operation

46 10.2.2 Error codes
12 NULLIFYING TRANSACTION 47
47 11.1 Description of nullifying
47 11.2 Description of the Web Service method of transaction nullifying

47 11.2.1 Nullify operation

48 11.2.2 Error codes
13 APPENDIXES 49
49 13.1 Apendix A: Webpay environments and key creation

49 12.1.1 Private key and public certificate creation
50 12.1.2 Webpay environment
51 13.2 Appendix B: Transition pages and transaction end page requirements
51 12.2.1 Transition page requirements

51 12.2.2 Checkout success page requirements
51 12.2.3 Checkout failure page requirements
52 13.3 Appendix C: Webpay API SOAP exceptions
55 13.4 Appendix D: Validation tests carried out by Transbank
55 12.4.1 Validation tests for Normal Transaction, plugin mode

55 12.4.2 Validation tests for Normal Transaction
55 12.4.3 Validation tests for Normal Transaction, deferred capture
55 12.4.4 Validation tests for Mall Transaction
55 12.4.5 Validation tests for OneClick Transaction
56 13.5 Appendix D: References
57 13.6 Appendix F: Examples of integration with Webpay API SOAP

1 CHANGE CONTROL 2 PREFACE
1 CHANGE CONTROL
DATE VERSION CHANGE DESCRIPTION

22-05-2017 1.0 Initial SOAP API Webpay integration document release.
08-06-2017 1.1 Correct authorization code length.
2 PREFACE
2.1 About this handbook 2.2 Audience

This handbook describes the technical and operative aspects This handbook is addressed to implementators who make the
to be considered in Webpay integration by using SOAP API for Webpay integration in retailers using SOAP API to support payment
web services for Normal Authorization, Mall Normal and OneClick by means of bank cards.
Transaction and Annulments.
It is recommended that the person making the integration have
Before we continue, it is necessary to state that in order to have technical knowledge of at least the following topics:
a general vision of the products and modalities associated to
Webpay, revision of the Webpay Operational manual is highly • Web services
recommended. • WS-Security
• Generation and validation of digital in SOAP messages
2.3 Feedback about this documentation

Help us improve this information by sending your comments to:
This handbook is an integral part of the contract, which why it is
important to pay attention to the responsibilities, suggestions
soporte@transbank.cl
and indications described in the current document.

3 ABOUT WEBPAY
3 ABOUT WEBPAY
3.1 Introduction to Webpay to make the payment using Webpay and, depending on the
Webpay is a payment platform developed by Transbank to make products the seller has hired, a set of credit payment alternatives
transactions from the internet using credit and debit bank cards. become available such as paying in installments and/or through
Nowadays Webpay is a key tool for the development of effective Redcompra debit. During the payment process, the cardholder
and secure electronic trade in Chile. is authenticated before the final transaction is carried out, to
guarantee that the card is being used by its owner. Once the
A payment Flow on Webpay begins on the seller website, where authentication has been made, the payment is authorized.
the cardholder selects products or services that he will need Webpay sends the authorization to the seller; if this authorization
to be paid. Once the selection has been made, the user opts is accepted, Webpay emits a payment electronic receipt.
Seller Webpay Authentication Seller Webpay Seller

website Payment at issuing bank website payment website
form receipt
Webpay’s most relevant attributes include:

• It allows secure online transaction on the internet • It guarantees security by using safe, TLS 1.2 protected servers
• It protects the seller from possible frauds or unacknoledged • Digital signature.

purchases by requesting the cardholder to directly authenticate
with their issuing bank.
3.2 Webpay transaction types

The following are the available transaction types through Web services:
A normal transaction is a request to financially authorize a payment by credit or debit card. The cardholder accesses
Normal the seller website, selects the products or services they want to purchase and then safely enters the credit or debit card
data on Webpay.
A Mall transaction corresponds to multiple requests to financially authorize different seller codes that belong to a major
seller. Each transaction constitutes a credit or debit card payment in a specific store. The cardholder gets on the major
Mall
seller website, selects the products or services from different stores and then safely enters the credit or debit card data
on Webpay.
A OneClick transaction allows the cardholder to register their national credit card once and make payments by a single
click on the online store. The card register is safely stored on Webpay and linked to the user’s login onto the store site;
One Click
in this way, whenever the cardholder needs to make a purchase from the store, they only need to log in the store website
and click on PAY in order to send the information associated to the transaction.
A OneClick Mall transaction allows to group one payment in an unique Oneclick transaction into multiple sellers codes
(similar to a Normal Mall transaction). Likewise with Oneclick transaction the cardholder will be allowed to pay without
OneClick Mall
entering the credit or debit card data on each one. This payment methode considers a previous registration process
or the cardholder’s registration on the main store that allows many OneClick transactions from each secondary store.

3 ABOUT WEBPAY
3.3 Credit transactions authorization and capture to the cardholder’s credit account effective. Both stages can take
Webpay transactions have two stages: authorization and capture. place at the same time or in a delayed manner. These modes
The authorization stage is a validation process meant to assess are, if applied separately, only valid for credit cards. In the case
whether it is possible to charge the account linked to the credit of debit card purchases both processes must be simultaneous
card and, at the same time, of reserving the transaction sum. The and cannot be separated.
capture stage makes the previous reserve or the charge applied
Simultaneous
It is used when the transaction gets validated online by Transbank. The payment is simultaneously charged to the
authorization
and capture client’s credit or debit card.
It is used when the seller cannot make the transaction in real time for many reasons, such as stock verification. In
said cases, the amount of the purchase is withheld in the client’s credit card balance without charging it until the seller
confirms the purchase, via capture, and informs Transbank about it. This can be done in a period that lasts up to 7 days,
otherwise the withholding in the client’s credit card will be reversed.
Mechanism for making delayed capture:
• Through Transbank website www.transbank.cl

Delayed
authorization
and capture • Delayed capture transaction, supported through Web services.
This mode is only available for credit card transactions, but not for payments using debit card.
The kinds of payment supported by this modality are the following:

- Normal Sale
- 2 installments, no interest
- 3 installments, no interest
- N Installments
3.4 Nullifying transactions reversed the client must be refunded in cash.

Webpay allows the seller to nullify, through Web services, a
credit transaction that has been authorized. Credit transactions can be nullified only under the following criterion:
This operation considers the complete or partial annulment of a Product Code Total Partial
annulment annulment
transaction; this can be achieved by indicating the associated
Normal sale VN
data of the online authorization or capture transaction over
which the annulment is to be applied and the amounts required
2 installments, no interest S2
for said annulment. If the transaction was paid to the seller,
the annulment will generate the withholding of the previously 3 installments, no interest SI
authorized amount in subsequent payments, which will allow
the reversal of the charge in the cardholder account. The seller Number of installments NC
has a 30-day due period from the date of purchaseto nullify
Normal installments VC
transactions via Web services as of the sale date.
Debit sale VD
This functionality is only valid for credit transactions. Debit
transactions cannot be nullified so in case they need to be

3 ABOUT WEBPAY
The seller knows the product applied in a transaction when he 3.7 Compatibility with Web browsers
gets the original authorization response from Transbank. This Transbank guarantees the correct operation of Webpay under the
piece of information must be kept by the seller in order to apply following devices and browsers:
partial and/or total annulment.
PC clients:
Annulments may not, for the time being, be applied to • Internet Explorer 9 or above
OneClick sellers. • Microsoft Edge
• Mozilla Firefox 48 or above
3.5 Supported currencies • Chrome 52 or above
In the present Webpay supports the following kinds of currency: • Safari 7 or above
• Chilean pesos (CLP)
• American dollars (USD) Smartphone / Mobile devices:
• Blackberry 9900, 9700
3.6 Cardholder authentication • iPhone and iPod – any of their models
Webpay allows cardholder authentication during the payment • Android – any of its models
process, providing more security and avoiding unacknowledged
purchases. The available authentication modalities are the
following:
The seller is responsible to guarantee
• Webpay Plus, which allows authentication of cardholders compatibility of their website with Web browsers and to
whose credit and debit cards have been issued in Chile and who take all the necessary security precautions to ensure a safe
make purchases from Webpay sellers. purchase.
Use of digital certificates is recommended, as well as avoid

• 3D Secure, which correspond to international programs
the use of emerging pop-up windows so as to prevent the
implemented by VISA (Verified by VISA) and MASTERCARD latest browser versions from blocking contents.
(Mastercard Secure Code), which allow authentication during For the mobile tier display, Webpay uses the user-agent
the purchase process of cardholders whose credit cards have received via cardholder browser and identifies whether or
been issued abroad. not this corresponds to the previously specified browsers
supported.
The result of the authentication process is delivered together with
the financial authorization of the Webpay transaction. In order
for the transaction to be authenticated, the seller needs to have
enabled Webpay Plus or 3D Secure.

3 ABOUT WEBPAY
3.8 Payment types (product) enabled; in general, the following are the generally supported
The currently available payment types on Webpay depend upon payment types:
the type of card used by the cardholder and that the seller has
Payment
Payment type Description type
abbreviation
NORMAL SALE It corresponds to the payment of a product or service in one installment. VN
2
It corresponds to the payment of a product or service in two similar installments and
INSTALLMENTS, S2
no interest for the cardholder.
NO INTEREST
3
It corresponds to the payment of a product or service in three installments and no
INSTALLMENTS, SI
INSTALLMENT SALE
interest for the cardholder.

NO INTEREST
N It corresponds to the payment of a product or service in N similar installments and
CREDIT INSTALLMENTS, no interest for the cardholder. The number of installments can go from 2 to “N” NC
NO INTEREST installments. With “N” maximum 12, and defined by the seller.
INSTALLMENTS
WITH NO It corresponds to the payment of a product or service in N similar installments and
INTEREST FROM no interest for the cardholder. This is promoted by the card issuing institution. It can VC
THE ISSUING go from 2 to 48 installments. Every issuing institution picks the range they promote.
INSTITUTION
Normal or fixed installments go from 2 to 48 and the defined interest is applied to
NORMAL
them by each issuing institution. If the latter has signed in to deferral, it can offer VC
INSTALLMENTS
from 1 to 3 moths referral (without any impact for the seller).
DEBIT REDCOMPRA Redcompra debit card payment. VD
Note: In case of doubts about the payments to the seller, consult the Webpay Seller manual.

4 GENERAL CONSIDERATIONS
4 GENERAL CONSIDERATIONS
4.1 Communication Webpay presents an API and it is the sellers’ responsibility to

The official communication and information provided by Transbank consume the presented services in time and form, so given
for the Webpay integrations, in all its modalities, is only available the SOAP 1.1 and WS-Security protocols used by Webpay
through the following channels: Webservices, each request by the seller and every response by
Webpay must be signed and it is a responsibility of both parts to
Transbank Portal: www.transbank.cl validate that signature.
Developers Portal: www.transbankdevelopers.cl In the case of requests by the sellers, Webpay makes sure that
the SOAP message signature corresponds to the seller using
On the Transbank portal, sellers can find general information the service by means of the self-signed public certificate that is
associated to the Webpay product, while on the developers’ portal, loaded on its systems. Then when the seller receives a response
sellers can find specific information such as manuals, SDK, plugins, to the request, Webpay signs such response and it is the seller’s
which are open code tools that have as an only purpose to facilitate responsibility to validate that said signature actually comes from
sellers’ integration and provide the understanding of the web Webpay by using the public certificate shared by Transbank.
services to operate with Webpay Plus, which is why it cannot aloe
that the available tools may be used for any other purpose. It should be pointed out that Webpay has two environments:
integration/testing and production. In both cases, Webpay
Given the above, when using any software distributed by possesses a distinct certificate for each environment, which is
Transbank, the seller understands that they accept this and other why it must make sure not to confuse the setting in which the
considerations published on seller is operating.
www.transbankdevelopers.cl
4.2 Security 4.3.2 Plugins and SDK update

Web services offered by Webpay are protected in order to guarantee If the seller is using a solution based on Plugins or
that only members authorized by Transbank can use the available SDK, they must pay attention to the updates that
operations. The security mechanism implemented is based on a Transbank will periodically make, which can be meant
TLS 1.2 and WS-Security secure communication channels, which to maintain compatibility with CMS or Shopping Cart for
provide authentication, confidentiality and integrity to the Web their compatibility, security modifications, properties or
Services. Thus, security is based on: functions addition, or corrections to the communications.
• A secure TLS 1.2 channel for communication with the Official communication will always be transmitted on
Webpay client.
• Digitally signed messages, requirements and responses. www.transbankdevelopers.cl
Webpay plugins and SDK distributed by Transbank are already

built up with the necessary libraries that allow to make the
required validations, but it is the seller who must make sure that
Transbank guarantees plugin compatibility with (a) CMS or
the payment development or solution they use fulfils the expected
Shopping Cart specific version(s) and the SDK with settings
security protocols. and requirements specified on www.transbankdevelopers.cl.
4.3 Retailers (Sellers) responsibilities It is important to be especially careful if you update the
4.3.1 Validation of request and response messages payment solution platform to a version that has not been
proven to be compatible, because the communication
Every seller that uses Webpay through Webservices MUST
between the seller and Webpay could stop working.
safeguard the security of their transactions, under the service
frame offered by Transbank.

5 WEBPAY API SOAP
*1 Webpay API SOAP is based on the standard known as Web*1 The seller must generate a digital certificate, which can be
Services, which includes the SOAP (Simple Object Access self-signed, being especially careful about using the common
Protocol) 1.1, WSDL (Web Services Definition Language), name (CN) just as the seller code provided by Transbank, for
providing a high degree of interoperability, a standard protocol example, cn = 597029124456.
to invoke remote services and platform and development
language independence. The seller must send the digital certificate (public part) that they
will use to validate the fact that the requirement actually comes
The type of transaction, the possibility to allow payment with from the seller to Transbank. The seller’s private key is not
credit or debit card, and the installments products Will depend requested and it has to always be taken care of by the seller.
upon the kind of product that the seller has hired and upon the
institution that issued the card that is used for the purchase. In the Transbank will deliver its certificate to the sellers who are in
following chapters specific information about each transaction the processes of integration, testing and go-live transition
type will be provided. independently so as to allow validation of the response signature.
5.1 API SOAP Security Aspects Every method involves a digital signature (WS-Security) in the
5.1.1 General information message body ({http://schemas.xmlsoap.org/soap/
Web services offered by Webpay are protected in order to envelope/}Body), both in its request and response. The seller
guarantee that only members authorized by Transbank can use signs, by means of its certificate, the requirement, and validates
the available operations. The security mechanism implemented the response by means of the certificate provided by Transbank.
is based on a TLS 1.2 and WS-Security secure communication .
channels, which provide authentication, confidentiality and 5.1.2 Key generation and self-signed certificate
integrity to the Web Services. Thus, security is based on: 1. Create private key
• A secure TLS 1.2 channel for communication with the
Webpay client. openssl genrsa -out 597029124456.key 2048
• Digitally signed messages, requirements and responses.
2. Create certificate requirement
REQUIREMENT openssl req -new -key 597029124456.key -out 597029124456.csr
SSL Country Name (2 letter code) []:CL

State or Province Name (full name) []:
Validate signature Locality Name (eg, city) []:SANTIAGO
with Services key Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Message signed with
Common Name (eg, your name or your server’s hostname)
seller’s private key
[]:597029124456
Seller’s Seller’s
Client public Email Address []:
Application Webpay Please enter the following ‘extra’ attributes
to be sent with your certificate request
RESPONSE A challenge password []:
An optional company name []:
Validate signature with
Webpay public key
3. Create self-signed certificate
openssl x509 -req -days 1460 -in 597029124456.csr

Message signed with Webpay -signkey 597029124456.key -out 597029124456.crt
private key
The seller must send the public certificate (597029124456.

crt) to Transbank and keep the private key with which they
will have to make the transaction.
*1 Appendix D: REF 03

6 INTEGRATION, INTEGRATION VALIDATION AND GO-LIVE TRANSITION
6.1 Webpay integration stages code 597020000541 and its private key, Webpay public
In order for the seller to incorporate Webpay as payment means, certificate, for the integration environment, are already
they need to go through the following stages: preinstalled, so no additional settings are required.
• Integration stage It is worth mentioning that the tests store supports
• Integration Validation Stage debit and credit payment in normal and simultaneous
• Go-live transition stage capture transactions, in Chilean pesos, which the
most frequently used Webpay product in the market.
Each stage is necessary for the seller to achieve an appropriate
implementation of Webpay, with special priority on transactional For further information in this respect, or any
security and integrity. particular requirements in respect to the integration
test store, contact support at 800 44 11 44 or at
6.1.1 Integration stage
The integration stage corresponds to the process by means of
which the seller develops their payment solution by consuming 6.1.1.2 Test data for the integration environment
API Webpay services. In order to use the integration environment, test cards will be
needed; they are predefined for success and failure settings.
In this case, the seller uses an integration seller code provided
by Transbank, together with all the necessary credentials to In both cases, both for debit and credit, transactions are
make the connection and the appropriate service consumption. authenticated, so the following data must be used.

In case the seller wants to use plugins or SDK provided For credit card tests, we have:
by Transbank, they already incorporate said credentials. Brand VISA MASTERCARD
If the seller wants to develop their own solution, then
Card number 4051885600446623 5186059559590568
they must use the corresponding credential available on
Expiration year Any Any
transbankdevelopers.cl or requesting them to
Expiration month Any Any
CVV 123 123
6.1.1.1 Credentials Result APPROVED REJECTED
To begin the integration process, go to

www.transbankdevelopers.cl Para el caso de transacciones con tarjeta de débito:
ACCEPT DENY
and download the corresponding plugin to your Shopping
CARD NUMBER 4051885600446620 5186059559590560
Cart or CMS, your preferred SDK, or the package containing
RUT 11.111.111-1 11.111.111-1
the corresponding credentials if you wish to use your own
PASSWORD 123 123
development.
Make sure to fulfil the technical requirements specified there 6.1.2 Integration validation stage
and follow the installation instructions detailed for each case. During the integration validation, the aim is to verify that the seller
is making secure and troublefree transactions, which is why a set
Each plugin is ‘ready to use’ in integration/validation of tests will be requested, together with their subsequent delivery
environment, fulfilling the technical, security and of evidences, so as to validate the integration.
information display requirements required by
Webpay, so that no modifications are in order. This validation is a necessary requisite to leave the seller in
production and no seller will be allowed to productively use the
The default tests store with the plugins has the trade Webpay service without having a validation.

On the other hand, Transbank will not validate any integration the self-signed public certificate associated to said key, and
to a seller which is not in possession of a productive seller likewise the change in Transbank public certificate in the
code. In order to get it, follow the instructions on how to productive environment.
become a client on the portal
www.transbank.cl
For further information about keys and certificates, see the
or contact your commercial representative. In this stage, the appendix “Integration key and environment creation.”
seller sends the evidences to
During the go-live transition period you will have to make, at
through the corresponding form, clearly indicating purchase least, one trial transaction, after which the go-live transition
orders, date and time of the transactions. period will conclude.

On the other hand, Transbank will not validate any integration to
a seller which is not in possession of a productive seller code. In
order to get it, follow the instructions on how to become a client
It is the seller’s responsibility to consider that the public
on the portal www.transbank.cl, or contact your commercial certificate that Transbank shares with sellers has an
representative. In this stage, the seller sends the evidences to expiration date, and likewise the certificate that the seller
soporte@transbank.cl, through the corresponding form, clearly generates and shares with Transbank to make transaction
indicating purchase orders, date and time of the transactions. on Webpay.
The seller is responsible for protecting their private key and

6.1.3 Go-live transition stage
their public certificate, and likewise they are responsible to
This stage corresponds to the technical-administrative activities replace them when they expire.
that both the seller and Transbank carry out so as to set out
the payment solution in production, allowing the seller to operate
with Webpay and all its range of cards.
6.2 Environments
Once the integration validation is accepted, the seller will receive For the integration, validation and go-live transition process,
instrucions from support, that include changing to productive Transbank offers two environments:
endpoints, seller’s productive public certificate, among others.
1) Integration and validation environment: in this environment,
As Webpay uses WS-Security, it is at this stage that seller and the seller integrates into Webpay and tests its payment solution.
Transbank exchange the productive public certificates, keeping Likewise, in this environments, the seller’s integration is validated.
both parts their respective private keys. Thus, both parts sign
their communications and the counterpart will validate the 2) Production environment: in this environment, the seller will
signature by means of the already exchanged certificates. finally operate productively. Here they can run tests with actual
credit and debit cards. Credentials in this environments are
Once support formally communicates that the integration has delivered once go-live transition is coordinated.
been accepted, you will have to follow the indicated steps to go-
live and to be able to start making actual transactions. Each one of these environments manages different URLs
(endpoints), different sellers codes, different test cards and
These steps include change in the environment where different certificates; this is why it is important to keep in mind
transactions, moving from integration to production, that, when changing environments, these previous points must
besides instructions for productive private key creation and be considered.

7 NORMAL AUTHORIZATION TRANSACTION
7.1 Description of Normal Authorization Transaction selects a product or service, and the entry associated to the credit
A normal authorization transaction (or normal transaction) is a or debit card data is made in a secure way on Webpay.
financial authorization request a credit or debit card payment,
where the entity that makes the payment enters the seller’s website, The page flow for the transaction is the following:

website Payment at issuing bank website payment website
form receipt
Summary of the Normal Authorization Transaction Method
METHOD GENERAL DESCRIPTION

It allows to start a transaction on Webpay. As a response to the invocation, a token is generated to represent solely
a transaction.
initTransaction
It is important to consider that once this method is invoked, the token that is delivered has a limited duration
time of 5 minutes, after which the token expires and cannot be used for a payment.
getTransactionResult It allows obtaining the transaction result once Webpay has resolved the financial authorization.
It notifies Webpay that the transaction result has been received accordingly.
acknowledgeTransaction The acknowledgeTransaction method must be always invoked, despite the result delivered by the
getTransactionResult method. If the invocation is not completed in a 30-second period, Webpay will reverse the
transaction, assuming that the seller could not inform its result, thus avoiding the charge to the cardholder.

7.2 Payment sequence in a normal transaction

7.2.1 Diagram
The following diagram illustrates the payment sequence and how the different participants interact in a normal transaction.
sd Normal Transaction Webpay Flow Sequence
CARDHOLDER SELLER WEBPAY WS
1 Pay with Webpay()
2 initTransaction()
3 Response() :token, urfFormOfPayment
4 Redirect(token...)
5 Request(token)
6 Webpay form()
7 Pay()
8 Authorize()
9 Redirect()
10 Request(token)
11 getTransactionResult(token...)
12 Response()
13 acknowledge Transaction(token)
14 Redirection(token)
15 Request(token)
16 Webpay receipt()
17 Request(token)
18 Last page()
Illustration 1: Normal Transaction sequence diagram

7.2.2 Sequence description result. It is recommended that the authorization result be kept
1. Once the godos or services have been selected, the in the seller’s system, given the fact that this method can be
cardholder decides to pay through Webpay. invoked only once per transaction.
2. The seller initiates a transaction on Webpay, invoking the 12. The seller receives the invokation result of the
initTransaction(…) method. getTransactionResult() method.
3. Webpay processes the requirement and delivers (as the 13. The seller’s system needs to consume the third method,
operation result) the transaction token and the readdressing acknolewledgeTransaction, so as to report to Transbank that
URL that the cardholder will have to readdress. the transaction has been properly received. If this operation is
correctly executed, the product can be released to the client.
4. The seller readdresses the cardholder towards Webpay,
with the transaction token to the URL mentioned in point 3.
The readdressing is carried out by delivering the token as the
token_ws variable by POST method.
If said method is not consumed or if its
consumption takes longer than 30 seconds, Webpay
5. The cardholder Web browser will make an HTTPS request
will reverse the transaction, assuming that there were
to Webpay, based on the readdressing generated by the seller
communication problems. In this case the method sends
in point 4. an Exception pointing out that such situation occurred.
This exception must be managed for not delivering the
6. Webpay responds to the requirement by displaying the product in case it happens.
Webpay payment form. At this point, the communication will
involve only Webpay and the cardholder, which means that
the seller does not intervene. The Webpay payment form will 14. Once the transaction result has been received and its
display, among other things, the transaction amount, seller according reception has been reported, the seller’s site must
information such as name and logo, credit and debit card readdress the cardholder back to Webpay, with the purpose
payment options. of displaying the payment receipt. It is important that this
happens so that the cardholder can understand that the
7. The cardholder enters the card information and clicks on pay payment process was successful and that they will be charged
in the Webpay form. to their bank card. The readdressing to Webpay is done by
using the URL informed by the getTransactionResult()
8. Webpay processes the authorization request (first the bank method as destination and sending the transaction token in
authentication and then the transaction authorization). the token_ws variable through POST method.
9. Once the authorization is resolved, Webpay sends the 15. Webpay receives a requirement with the token_ws variable.
cardholder back to the seller, making an HTTP/HTTPS
readdressing to the seller transaction page, where the transaction 16. Webpay identifies the transaction and displays the payment
token is sent as the token_ws variable by POST method. The receipt for the cardholder.
seller needs to implement the reception of this variable.
17. Once the payment receipt has been displayed for a limited
10. The cardholder’s Web browser makes an HTTP/HTTPS period of time, the cardholder is readdressed back to the
request to the seller’s site, based on the readdressing seller’s site by using token_ws variable token sent through
generated by Webpay in point 9. POST method to the last page informed by the seller in the
initTransaction method.
11. The seller’s website receives the token_ws variable and
invokes the second Web method, getTransactionResult () 18. The seller’s site displays the payment*3 final page. *3
*2 (while transaction*2 page is displayed), to get the authorization
*2 A description of details about the transition page can be found in the *3 description of details about the final page can be found in the A,
Appendix A in the API SOAP general description document. 12.1.2 in the API SOAP general description document.

7.3 Alternative Flow: Payment sequence in a normal

transaction that has been nullified through payment form
7.3.1 Diagram
The following diagram illustrates the sequence of a normal
transaction where the cardholder nullifies the transaction in
the Webpay payment form; it also shows how the different
participants in the situation interact.
Illustration 2: Nullify Webpay payment form button.
sd Annulled Webpay transaction Flow Sequence
1 Pay with Webpay()
2 initTransaction()
5 Request(token)
6 Webpay form()
7 Nullify()
8 Redirect()
9 Request(token)
10 Last page()
Illustration 3: Diagram of the payment sequence in a normal transaction that has been annulled in the payment form.

7.3.2 Description of payment sequence for a transaction that result. In this case they must get an exception because the
has been nullified through payment form: payment has been aborted.
1. Steps from 1 to 6 are identical to the normal sequence.
10. The seller must inform the cardholder that their payment
7. The cardholder clicks on “nullify”, in the Webpay form. was not completed, according to the Note (glosa, glossary)
appendix non authorized transaction.
8. Webpay gives the control back to the seller by means of a
HTTP/HTTPS towards the seller final page, where the transaction 7.4 Alternative flow: payment sequence in a normal
token in TBK_TOKEN variable is sent by POST method. transaction with timeout event
9. The seller with the TBK_TOKEN variable must invoke the 7.4.1 Diagram
second Web method, getTransactionResult (), (while The following diagram illustrates the payment sequence and
*4 transition*4 page is displayed), to obtain the authorization it also shows how the different participants in the normal
transaction with timeout event interact.
sd Webservice Webpay transaction Flow Sequence
1 Pay with Webpay()
2 initTransaction()
5 Request(token)
6 Webpay form()
7 Timeout()
8 Error() : Error page
Illustration 4: Diagram of timeout sequence in normal transaction
*4 A description of further details about the transaction page can be found in

the Appendix A, 12.1.1, in the API SOAP general description document.

7.4.2 Description of timeout sequence in normal transaction: 7.5 Description of methods in a normal authorization
1. Steps from 1 to 6 are identical to the normal sequence. transaction web service
7. The cardholder is on the Webpay form, but they do not click on In this section, every Normal Transaction operation will
pay before 10 minutes elapse. This causes a timeout in the form. be described.
8. Webpay generates a timeout error and a screen is presented 7.5.1 initTransaction operation
*5 pointing out that an error*5 occurred and then it redirects This method allows the initiation of a Webpay payment transaction.
automatically back to the seller.
7.5.1.1 Input paramenter
NAME DESCRIPTION
tns:wsTransactionType
WSTransactionType
It indicates the type of transaction; its value must always be TR_NORMAL_WS
xs:string
sessionId (Optional) Session identifier, seller internal use, this value is returned at the end of the transaction.
Maximum length: 61
xs:anyURI
returnURL (Mandatory) Seller URL, where Webpay will redirect the cardholder after the authorization process.
Maximum length: 256
xs:anyURI
finalURL (Mandatory) Seller URL where Webpay will redirect the cardholder after Webpay success voucher.
Maximum length: 256
tns:wsTransactionDetail
(Mandatory) List of objects of the wsTransactionDetail type, which contains the transaction data. The maximum
transactionDetails
number of repetitions is 1 for this kind of transaction.
wsTransactionDetail is described later in this document.
tns:wPMDetail
wPMDetail
(Not used in Normal Transactions) This field contains the monthly Webpay transaction.
xs:string
commerceId (Optional) It is the seller’s unique identification code given by Transbank. It is mandatory for MALL transactions.
Length: 12
xs:string
buyOrder (Optional) It is the purchase order unique code generated by the seller. It is mandatory for MALL transactions. This
number must be unique for each transaction.
*5 The description of further details of the transition page is found in

Appendix A, 12.1.1, of the API SOAP general description document.

TYPE WSTRANSACTIONDETAIL
Description: the kind of data contains transaction details.
FIELD DESCRIPTION
xs:decimal
amount Amount of the transaction. A maximum of 2 decimal places for USD.
Maximum length: 10
xs:string
Store purchase order. This number must be unique for each transaction.*6
buyOrder
Maximum length: 26
The purchase order can have: numbers, letters, capitals and lowcase letters, and the signs |_=&%.,~:/?[+!@()>-
xs:string
commerceCode Store seller code given by Transbank.
Length: 12
sharesAmount Unused field
sharesNumber Unused field
7.5.1.2 Output parameters: TypewsInitTransactionOutput 7.5.2 getTransactionResult operation

Method that allows to get the transaction results and data.
FIELD DESCRIPTION 7.5.2.1 Input parameters
xs:string
token Transaction token.
Length: 64 FIELD DESCRIPTION
xs:string xs:string
url Webpay payment form URL tokenInput Transaction token.
Maximum length: 256 Length: 64
*6 It must fullfil the allowed characters format

7.5.2.2 Output parameters: TypeTransactionResultOutput
FIELD DESCRIPTION
xs:string
buyOrder Store purchase order.
Maximum length: 26
xs:string
sessionId
Session identifier, seller’s internal use, this value is returned at the end of the transaction. Maximum length: 61
Tns:carddetails
cardDetails
Object that represents the cardholder’s credit card data. cardDetails will be described later in this document.
xs:string
accoutingDate Authorization date.
Length: 4, MMDD format.
xs:string
transactionDate Date and time of the authorization.
Length: 6, MMDDHHmm format.
xs:string
Result of Webpay Plus and/or 3D Secure sellers’ authentication; the possible values are the following:
• TSY : successful authentication.
• TSN : failed authentication.
VCI • TO*7 : maximum authentication time exceeded.
• ABO : authentication aborted by cardholder.
• U3 : authentication internal error.
• It can be void/empty/blank if the transaction was not authenticated.
Maximum length: 3
xs:string
urlRedirection Redirection URL for visualizing voucher.
Maximum length: 256
tns:wsTransactionDetailOutput
detailsOutput
detailsOutput Object that contains details about the financial transaction. Described later in this document.
TYPECARDDETAIL
Description: Type of data containing credit card details.
FIELD DESCRIPTION
xs:string
4 last numbers of the cardholder’s credit card.
cardNumber
The complete number is sent only to sellers authorized by Transbank.
Maximum length: 16
xs:string
cardExpirationDate (Optional) Expiration date of the cardholder’s credit card. YYMM format.
Only for sellers authorized by Transbank.
*7 VCI=TO indicates that a timeout situation occurred in the bank authentication process. This transaction will not be authorized and it will follow the normal course of events.

TYPEWSTRANSACTIONDETAILOUTPUT
Description: Type of data containing the transaction result detail.
FIELD DESCRIPTION
xs:string
authorizationCode Transaction authorization code
Maximum length: 6
xs:string
Transaction payment type.
VD = Venta Débito (Debit purchase)
VN = Venta Normal (Normal purchase)
paymentTypeCode
VC = Venta en cuotas (Installment purchase)
SI = 3 cuotas sin interés (3 installments, no interest)
S2 = 2 cuotas sin interés (2 installments, no interest)
NC = N Cuotas sin interés (N installments, no interest)
xs:string
Authorization response code. Possible values:
0 Approved transaction
-1 Rejected transaction
-2 Retry transaction
responseCode -3 Transaction error
-4 Rejected transaction
-5 Rejected for rate error
-6 Exceeds monthly maximum capacity
-7 Exceeds daily limit for transaction
-8 Non-authorized trading type
Full number format for chilean peso transactions and decimal for dollar transactions.
Amount Transaction amount
Maximum length: 10
xs:int
sharesNumber Number of installments
Maximum length: 2
xs:string
commerceCode Store seller code
Length: 12
xs:string
buyOrder Store purchase order. This number must be unique for each transaction
Maximum length: 26
7.5.3 AcknowledgeTransaction operation

Method that allows to inform Webpay about the according
reception of the transaction result.
In case of retrieving the acknowledgeTransaction
7.5.3.1 Input parameters: acknowledgeTransaction method after 30 seconds of the authorization, the exception
described below will be informed and the seller shall not
FIELD DESCRIPTION deliver the product or service, because the transaction
xs:string has been reversed by Webpay:
Length: 64
Timeout error (Transactions REVERSED) with code 277.

8 NORMAL MALL AUTHORIZATION TRANSACTION
8.1 Description of Normal Mall Authorization Transaction

This kind of transaction corresponds to a financial authorization Virtual
Payment
store
request for a set of debit or credit card payments. The payer enters $1.000
1
the seller’s site, selects products or services and then enters the
credit or debit card information only once and safely on Webpay
for the set of payments. Each payment will yield its own result, Virtual
Mall Payment
authorized or declined. store
store $2.000
2
Mall Webpay gathers several stores which are the ones that can
generate transactions. Both the mall and the associated stores are
Virtual
identified by a number called seller code. Payment
store
$3.000
N
The pages flow for the transaction is the following:

website Payment by issuing website payment website
form bank receipt
Summary of the Normal Mall Authorization Transaction Method

It allows a transaction on Webpay. As a reply to the invocation a token representing a unique transaction is generated.
initTransaction
It is important to consider that once this method is invoked, the delivered token lasts a limited period of 5
minutes, after which the token expires and cannot used for a payment.
getTransactionResult It allows the reception of the transaction result once Webpay has resolved the financial authorization.
It reports to Webpay about the according reception of the transaction result.
acknowledgeTransaction The acknowledgeTransaction method must always be invoked, regardless of the result delivered by
the getTransactionResult. If the invocation is not completed in 30 seconds, Webpay will reverse the transaction,
assuming that the seller could not be notified about the result, thus preventing the charge to the cardholder.

8.2 Payment Sequence in a Normal Mall Authorization Transaction

8.2.1 Diagram
The following diagram illustrates the payment sequence and the way in which the different participants interact in a Normal Mall transaction.
sd Normal Mall Transaction Webpay Flow sequence
1 Pay with Webpay()
2 initTransaction()
5 Request(token)
6 Webpay form()
7 Pay()
8 Authorize()
9 Redirect()
10 Request(token)
11 getTransactionResult(token...)
12 Response()
13 acknowledge Transaction(token)
14 Redirection(token)
15 Request(token)
16 Webpay receipt()
17 Request(token)
18 Last page()
Illustration 5: Normal Mall Transaction sequence diagram

8.2.2 Sequence Description 29. The seller’s site receives the token_ws variable and
19. Once the products or services have been selected, the invokes the second Web method getTransactionResult ()
cardholder decides to pay through Webpay. (while transition*8 page is displayed), to get the authorization *8
result. It is recommended that the authorization result be kept
20. The seller starts a Webpay transaction, invoking the in the seller’s systems, given that this method can only be
initTransaction(…) method. invoked once per each transaction.
21. Webpay processes the requirement and delivers the 30. Webpay replies to the invokation result of the
transaction token and the URL readdressing the card holder as getTransactionResult() method.
a the result of the operation.
31. In order to inform Webpay that the transaction result has
22. The seller readdresses the cardholder to Webpay, with been received accordingly, the seller’s system consumes the
the transaction token to the URL mentioned in point 3. The third method, acknowledgeTransaction().
readdressing is achieved by sending the variable token_ws by
POST method. NOTE: If this is not consumed or its consumption takes
longer than 30 seconds, Webpay will reverse the transaction,
23. The cardholder’s Web browser makes an HTTPS request assuming that there were communication problems.
to Webpay, based on the readdressing generated by the seller
in point 4. 32. Once the transaction result is received and its according
reception reported to Webpay, the seller’s site must readdress
24. Webpay replies to the requirement by displaying The the cardholder back to Webpay again, with the purpose of
Webpay payment form. From this moment on, communication displaying the payment receipt. It is important to do this so
will be maintained exclusively between Webpay and the that the cardholder understands that the payment process was
cardholder, with no interference from the seller. The Webpay successful, and that will involve a charge on their bank card.
payment form displays, among other things, the transaction This readdressing is carried out by using the destination URL
amount, mall information such as name and logo, name and informed by getTransactionResult() method, sending the
amount per store, credit or debit payment options. token_ws transaction token via POST method.
25. The cardholder enters their card information and clicks on 33. Webpay receives a requirement with the token in the token
pay in Webpay’s form. ws variable validating that the transaction was accepted.
26. Webpay processes the authorization request for each store 34. Webpay identifies the transaction and displays the payment
payments. receipt for the cardholder to see.
27. Once each payment authorization is resolved, Webpay 35. Once the payment receipt is visualized, the cardholder is
gives control back to the seller, making an HTTP/HTTPS sent back to the seller’s site with the token in the token_ws
readdressing towards the seller’s sote, where the token_ws variable sent through POST method, towards the last page
variable transaction token is sent through POST method. informed by the seller in the initTransaction() method.
28. The cardholder Web browser makes an HTTP/HTTPS 36. The seller’s site displays the payment*9 final page. *9
request to the seller’s site, based on the readdressing
generated by Webpay in point 9.
*8 The description of further details of the transition page is found in

*9 Appendix A, of the API SOAP general description document.

8.3 Alternative Flow: nullified payment sequence in a Normal

Mall Authorization Transaction through payment form
The following diagram illustrates the sequence of a normal

transaction in which the cardholder has annulled the transaction
in the Webpay payment form and the way in which the different
participants interact in this situation.
Illustration 6. Annul button in the Webpay payment form.
sd Annulled Transaction Webpay Flow Sequence
1 Pay with Webpay()
2 initTransaction()
5 Request(token)
6 Webpay form()
7 Nullify()
8 Redirect()
9 Request(token)
10 Last page()
Illustration 7: Diagram of payment sequence in an annulled normal mall transaction in the payment form

8.3.1 Description of alternative sequence, nullify the authorization result. In this case an exception is in order
11. The cardholder clicks on “annul” in the Webpay form. given that the payment was aborted.
12. Webpay gives control back to the seller, readdressing 14. The seller must inform the cardholder that their payment
through HTTP/HTTPS towards the seller’s last page, where the was not completed, according to the non-authorized transaction
transaction token in the TBK_TOKEN is sent via POST method. annotation in the appendix.
13. The seller must invoke the second Web method, 8.4 Alternative Flow: payment sequence in a Normal Mall
getTransactionResult(), by means of the TBK_TOKEN Authorization Transaction with timeout event
*10 variable (while transaction*10 page is displayed), so as to get
8.4.1 Diagram
sd Transaction Webservice Webpay Flow Sequence
1 Pay with Webpay()
2 initTransaction()
5 Request(token)
6 Webpay form()
7 Timeout()
8 Error() : Error page
Illustration 8: Diagram of timeout sequence in normal mall authorization transaction
*10 Detailed description of the transaction page can be found in Appendix

A, 12.1.1, in the API SOAP general description document.

8.4.2 Description of alternative timeout, sequence. 8.5 Description of methods in a payment sequence in a
2. Steps from 1 to 6 are identical to the normal sequence. Normal Mall Authorization Transaction
9. The cardholder is in the Webpay form, but they do not click In the following sections, each operation to be used in a Normal
on pay for 10 minutes. This causes a timeout in the form. Mall Transaction Will be described.
10. Webpay generates a timeout error and a screen reporting 8.5.1 InitTransaction operation
the error is displayed. The cardholder is not readdressed Method that allows the start of a Webpay payment transaction.
automatically to the seller.
8.5.1.1 Input parameter
NAME DESCRIPTION
tns:wsTransactionType
WSTransactionType
It signals the type of transaction, its value must always be TR_NORMAL_WS
xs:string
sessionId (Optional) Session identifier, seller’s internal use, this value is given back at the end of the transaction.
Maximum length: 61
xs:anyURI
returnURL (Mandatory) Seller’s URL to which Webpay Will readdress after the authorization process.
Maximum length: 256
xs:anyURI
finalURL (Mandatory) Seller’s URL to which Webpay Will readdress after Webpay success voucher is issued.
Maximum length: 256
tns:wsTransactionDetail
(Mandatory) List of objects of the wsTransactionDetail type, which contains information about the transaction. The
transactionDetails
maximum number of repetitions is 1 for this type of transaction.
wsTransactionDetail está descrito más adelante.
tns:wPMDetail
wPMDetail
(Not used for Normal Transaction) This field contains the monthly Webpay transaction.
xs:string
(Mandatory) It is the single seller identification code provided by Transbank.
commerceId In this case the commerceID corresponds to the code assigned to the PST (or mall code) that collects the codes
belonging to sellers that will receive the payments.
Length: 12
xs:string
buyOrder
(Mandatory) It is the single purchase order code generated by the mall seller.

TYPE WSTRANSACTIONDETAIL
Description: type of data contains details about the transaction
FIELD DESCRIPTION
xs:decimal
amount Transaction amount. Maximum of two decimals for USD.
Maximum length: 10
xs:string
Store purchase order. This number must be unique for each transaction.*11
buyOrder
Maximum length: 26
The purchase order can have: numbers, capital and lowcase letters, and symbols |_=&%.,~:/?[+!@()>-
xs:string
commerceCode Store seller code provided by Transbank.
Length: 12
sharesAmount Unused field
sharesNumber Unused field
8.5.1.2 Output parameter:TypewsInitTransactionOutput 8.5.2 GetTransactionResult operation

Method that allows the reception of the transaction result
FIELD DESCRIPTION and data.
xs:string 8.5.2.1 Input parameter
Length: 64 FIELD DESCRIPTION
xs:string xs:string
url Webpay payment form URL tokenInput Transaction token.
Maximum length: 256 Length: 64
*11 It must fullfil the allowed characters format

8.5.2.2 Output parameter: TypeTransactionResultOutput
FIELD DESCRIPTION
xs:string
buyOrder Mall purchase order.
Maximum length: 26
xs:string
sessionId
Session identifier, seller’s internal use, this value is given back at the end of the transaction. Maximum length: 61
Tns:carddetails
cardDetails
Object representing the cardholder’s credit card information. cardDetails is described later in this document.
xs:string
accoutingDate Authorization date
Length: 4, MMDD format
xs:string
transactionDate Authorization date and time
Length: 6, format: MMDDHHmm
xs:string
Authentication result for Webpay Plus y/o 3D Secure Sellers, the possible values are as follows:
• TSY : Successful authentication.
• TSN : Failed authentication.
VCI • TO*12 : Authentication máximum time exceeded.
• ABO : Authentication aborted by the cardholder.
• U3 : Internal error in the authentication.
• It can be void if the transaction was not autheticated.
Maximum length: 3
xs:string
urlRedirection Redirecting URL for voucher visualization.
Maximum length: 256
tns:wsTransactionDetailOutput
detailsOutput
detailsOutput Object containing detail about the financial transaction. Described later in this document.
TYPECARDDETAIL
Description: Type of data containing details about the credit card.
FIELD DESCRIPTION
xs:string
4 last numbers of the cardholder credit card.
cardNumber
The complete number is sent only for Sellers authorized by Transbank. The expiration date will be null.
Maximum length: 16
xs:string
(Optional) Cardholder’s credit card expiration date. YYMM format
cardExpirationDate
Only for sellers authorized by Transbank.
Maximum length: 4
*12 VCI=TO It indicates that a timeout event was produced during the bank authentication process. This transaction will not be authorized and it will follow the normal
course of events.

TYPEWSTRANSACTIONDETAILOUTPUT
Description: this type of data contains the transaction result detail.
FIELD DESCRIPTION
xs:string
authorizationCode Transaction authorization code
Maximum length: 6
xs:string
Transaction payment type.
VD = Venta Débito (Debit purchase)
VN = Venta Normal (Normal purchase)
paymentTypeCode
VC = Venta en cuotas (Installment purchase)
SI = 3 cuotas sin interés (3 installments, no interest)
S2 = 2 cuotas sin interés (2 installments, no interest)
NC = N Cuotas sin interés (N installments, no interest)
xs:string
Authorization response code. Possible values:
0 Accepted transaction
-1 Declined transaction
-2 Retry transaction
responseCode -3 Transaction error
-4 Declined transaction
-5 Declined for fee error
-6 Exceeds monthly maximum capacity
-7 Exceeds daily limit for transaction
-8 Non-authorized trading type
xs:decimal
Amount Transaction amount
Maximum length: 10
xs:int
sharesNumber Number of installments
Maximum length: 2
xs:string
commerceCode Store seller code
Length: 12
xs:string
buyOrder Mall purchase order
Maximum length: 26
8.5.3 AcknowledgeTransaction operation

Method that allows to inform Webpay about the according
reception of the transaction result. In case of invoking the acknowledgeTransaction
8.5.3.1 Input transaction: acknowledgeTransaction method 30 seconds after the authorization takes place,
the exception described below will be reported and the
seller will not deliver the product or service because the
FIELD DESCRIPTION transaction has been reversed by Webpay:
xs:string
token Transaction token. Timeout error (Transactions REVERSED) with code
Length: 64 number 277.

9 ONECLICK TRANSACTION
9.1 Description of OneClick Transaction and decreases the risks of erroneously entering payment data.
The OneClick payment modality allows the cardholder to make
payments to the seller without the need to enter credit card The integration process with Webpay OneClick consists in the
information every time they make a purchase. development of the invocations to web services provided by
Transbank for cardholders’ registration as well as for payment
The payment model requires the cardholder who wants to transactions.
use the system to previously log in via the seller. This type of
payment facilitates the purchase, reduces the transaction time 9.2 Summary of Web service methods

It allows the registration of the cardholder and of their credit card information. A token representing the transaction
registration and a URL (UrlWebpay) corresponding to OneClick registration URL are sent back as reply.
initInscription
Once this Web service is invoked, the user must be readdressed via POST to urlWebpay by means of a TBK_
TOKEN parameter identical to the received token.
It allows the end of the cardholder’s registration process in OneClick.
The OneClick user identifier returns and it will be used to make payment transactions.
finishInscription
Once the registrarion flow is completed on Transbank, the user is sent to the end-of-registration URL established by
the seller. In that moment the seller must invoke finishInscription.
It allows payment transactions. The authorization result returns. This method can be executed every time the user
authorize
selects OneClick payment.
It allows the reversal of a previously authorized purchase transaction. This method returns a reversal transaction
codeReverseOneClick
unique identifier as a reply.
9.3 Registration on Oneclick • The seller sends the client’s browser to the received URL and
9.3.1 Description the token goes through parameter (POST method)
The registration is the process by means of which the cardholder
enters their card information on Webpay OneClick to use it in • Webplay displays a registration form, which is like Webpay
future purchases. This data is stored securely on Transbank Plus current payment form, so that the client can enter their
and are never disclosed to the seller. card information.
This process must be started by the seller’s store and is a • The client will be authenticated by their issuing bank similarly
requirement that the client is authenticated on the seller’s page as with payment normal flow. At this point a $1-peso transaction
before registration is begun. will be made but it will not be captured (it will not be reflected in
their bank statement).
Process:
• The client logs in and authenticates themselves on the seller’s • Once the registration is completed, Webpay sends the client´s
site by entering their user name and password. browser to the URL delivered by the seller, and the token goes
through parameter.
• The client selects the registration option which must be
explained on the seller’s site. • The seller must consume another Transbank web service,
with the token, in order to get the registration result and the
• The seller consumes a web service published by Transbank user identifier, which they must use in the future for making the
where they deliver client and final URL information; they get a payments.
token and Webpay URL.
• The seller displays the registration result for the client.

9.3.2 Diagram
Registration
CLIENT SELLER WEBPAY BANK

Login comercio
Select
Registration Login comercio
username/email
Token initInscription
Token
Screen
entering card
information Card information
Bank token
Screen
bank
authentication username and password
Bank token
Token
Token
finishInscription
user_tbk_id
Seller shows
result
Illustration 9: Registration process flow diagram

9.3.3 InitInscription method 9.5 Oneclick Payment Transaction

The payment is the process where the seller requests a purchase
Web Service method charge to a previously subscribed user’s credit card by means of
Allows to trigger the start of the inscription an identifier provided by Transbank at the moment of registration.
initInscription
process
{username}, {user id Transbank} Payments under this modality do not necessarily require the
Input user’s intervention.
Username : String (255)
user id Transbank : String (255)
The payment amount must be within the established limits for this
{Boolean indicating if the registration was
unsubscribed accordingly) kind of transactions, the internal process is similar to a normal
Output
Webpay charge.
Return: boolean (true/false)
Process:
• The client logs in and authenticates on the seller’s site or app by
entering their user name and password.

Once this webservice is invoked, the user must
be readdressed via POST to urlWebpay in TBK_TOKEN • The client selects Webpay Oneclick payment option.
parameter identical to the token.
• The seller uses the payment web service, published by
Transbank, delivering the user’s identifier (received during
9.4 Eliminating user registration record registration), the amount of the payment and the purchase order.
In the case the seller needs to eliminate the subscription of They obtain the reply with the authorization code.
a OneClick Webpay user either because of a customer’s
elimination from their system or because of the customer’s • The seller displays the payment result for the customer.
request no to operate with this payment type, the seller will have
to consume a Transbank web service with the user identifier
provided in the registration.
Payment
Web Service method
removeUser Allows a user unsubscription on Transbank
{username}, {user id Transbank}
CLIENT SELLER WEBPAY
Input
Username : String (255) Login
user id Transbank : String (255)
{Boolean indicating whether the inscription was
completed accordingly.) Selects
Output product
and pay Pay
Return: boolean (true/false) id_user_tbk, monto
cod_autor, id_trx
Result
Ilustration 10: Oneclick Payment Flow Diagram

Web Service method The seller, in case of needing to reverse a payment, must
consume a web service published by Transbank with the payment
authorize Allows a payment authorization.
identifier provided at the moment the transaction authorization
{username}, {user id Transbank}, {amount},
{purchase order}. reply is obtained.
String (255)
Input Web Service method
String (255)
Number (19,2) Allows to reverse a purchase and the reversal
String (255) codeReverseOneClick result is obtained together with a reversal
{reply code}, {authorization code}, {card brand}, code in case the process is successful.
Output {last 4 digits}, {transaction id} {purchase order}
Reply code: Number (10,0) Input
Purchase order: Long
{reverseCode} {reversed}
Output reverseCode: Long
9.6 Authorized Payments reversal reversed: boolean (true/false)
This process allows the reversal of a purchase when this could not
be completed, within the same accounting day with the purpose of The returned code via this method is a single identifier of the
nullifying a charge applied to a customer. reversal transaction.
9.7 Detailed definition of Web Service methods
finishInscription
INPUT
token Registration process identifier provided by Webpay in the initInscription method

OUTPUT
responseCode Return code of registration process, where 0 (zero) is accepted.
authCode Code that identifies the registration authorization.
creditCardType It indicates the type of card registered by the client (Visa, AmericanExpress, MasterCard, Diners, Magna).
last4CardDigits The last 4 digits of the card entered by the client during registration.
tbkUser Single client registration identifier must be used to make payments or delete registration.

authorize
INPUT
amount Payment amount in pesos.

tbkUser Single client registration identifier.
username Client’s user namein the seller’s system.
Single identifier of the purchase generated by the seller. It must be timestamp [yyyymmddhhMMss] + a three-digit
buyOrder correlation.
e.g. for the third transaction made on july 15 2011 at 11:55:50 the purchase order would be: 20110715115550003.
OUTPUT
Return code of payment process, where:
0 (zero) is accepted.
-1 Declined
-2 Declined
-3 Declined
-4 Declined
responseCode -5 Declined
-6 Declined
-7 Declined
-8 Declined
-97 Oneclick limits, maximum daily amount of payment exceeded
-98 Oneclick limits, maximum amount of payment exceeded
-99 Oneclick limits, maximum number of daily payments exceeded
authCode Payment transaction authorization code.
last4CardDigits The last 4 digits of the card entered by the client during registration.
creditCardType It indicates the type of card registered by the cardholder (Visa, AmericanExpress, MasterCard, Diners, Magna).
transactionId Payment transaction single identifier, it is used for reversal, if necessary
removeUser
INPUT
tbkUser Single identifier of customer’s registration.

username Client’s user name in the seller’s system.
OUTPUT
booleano True return, if it was posible to nullify the registration. False otherwise.
The integration process with Webpay Oneclick consists of

developing invokations to the webservices made available by
Transbank for cardholders’ registration, and also for the payment
transaction.
Summary of Web service methods.

10 MULTICODE MALL TRANSACTION
10.1 Description of the Transaction The integration process via Multicode Mall Webpay for a grouping
The Multicode Mall Transaction modality allows to group a payment seller consists of the development of the web service calls made
in one signle Oneclick transaction to different seller codes (like a available by Transbank to allow the cardholders to registrater and
Mall transaction). In a transaction of this type, just as with regular to make the payments.
Oneclick, the cardholder will be able to make payments without
needing to enter their credit card information in each one of them. Certificates safe-keeping and tbkUser should not be stored on
This payment model considers a cardholder’s previous inscription the cardholder’s side (mobile apps and/or other kind of apps);
or log-in process in the retailer where the service is requested. This it should be stored on the server’s side, given that the server is
payment type facilitates the sale, centralizes the payments, reduces accountable for the connection to web services. tbkUser should
transaction time and reduces the risks of incorrect data entry of the be encripted on the server.
payment site data.
10.2 Web service methods summary

It allows the beginning of the cardholder registration process to the Multicode Mall seller. The cardholder will get
initInscription back a registration transaction token and an URL presenting a Oneclick registration form where he will have to enter
his credit card data.
It allows the ending of the registration process to the Multicode Mall seller and delivery of the user ID assigned to
finishInscription
the cardholder by Transbank.
It allows the removal of a Multicode Mall registration by eliminating the generated user by Webpay. The cardholder
that requests his dismissal will not be able to make any more Multicode Mall payments unless he signs in again.
removeInscription
The dismissal will be directly carried out by means of this operation call.
It allows the authorization of a cardholder’s Oneclick payment, the cardholder having previously registered with
the corresponding Multicode Mall seller. The payment will contain n payment sub-transactions in Multicode Mall
retailers associated to the grouping seller.
authorize
This method sends back the payment authorization result. It must be carried out each time the cardholder selects
payment by means of Multicode Mall.
It allows the reversal of a previously-authorized payment transaction. This method sends back a response which
consists of a single identifier of the reversal transaction.
reverse
If the same transaction contained payments to more than one Multicode Mall retailer, the reversal will apply to the
complete list of them.
It allows the Multicode Mall seller to annul the payment transactions individually, by means of a child seller code.
nullify
It does not allow to annul the complete list associated to a parent payment transaction with a single call to this
operation.
reverseNullification It allows the reversal of a Multicode Mall annulment transaction.
The integration and, therefore, the calls to these WS must

be carried out by the grouping seller.

10.3 Multicode Mall Registration • The seller consumes a web service published by Transbank,
Registration is the process by means of which the cardholder where it delivers customer information and the termination
enrolls and enters his Multicode Mall Webpay card information to URL; it gets a token and a Webpay URL.
be used in future purchases. This information is safely stored on
Transbank and is never provided to the seller. • The seller sends the customer’s browser to the obtained URL
and passes the token through parameter (POST method).
This process must be initiated by the grouping Multicode Mall seller
site; in order to do so, the customer needs to be authenticated on it • Webpay presents the registration form, which is similar to the
before the registration process begins. Webpay Plus current payment form, so that the customer can
enter his card’s information.
It should be pointed out that the registration can only be carried out
via the seller’s webpage and not through any closed application or • The customer will be authenticated by his issuing bank like he
within a mobile device. is for a payment normal flow.
Process: • Once the registration process is over, Webpay sends the

• The customer enters and authenticates himself on the customer’s browser to the URL provided by the seller and
grouping Multicode Mall seller’s webpage, by means of his passes the token through parameter.
user name and password.
• The seller must consume another Transbank web service,
• The customer selects the registration option, which must be with the token, in order to obtain the registration result and
explained on the seller’s page. the user identifier, which he will have to use in the future to
make the payments.
• The seller presents the registration result to the customer.

Registration
CARD OWNER MULTICODE WEBPAY BANK

MALL SELLER
Seller Login
Select
Registration
username/email
returnUrl
Token initInscription
urlinscriptionForm
Token
urlinscriptionForm
Card information
enter screen
Card information
Bank token
Bank
authentication
screen user / password
Bank token
returnUrl Token
Token
finishInscription
tbkUser
Other data
Seller presents
result
Ilustración 11: Flow diagram of the registration process

Web Service method 10.5 Multicode Mall Payment Transaction

The payment is the process by means of which the seller requests
initInscription It allows to initiate the registration process
the charging of a purchase to a previously-registered user’s
Input {username}, {email}, {returnUrl}
credit card, by using the identifier provided by Transbank at the
Output {token}, {urlInscriptionForm}.
momento of the registration process.
Payments under this modality do not require the intervention of the

user beyond his clicking of a “Pay with Multicide Oneclick” button.
Once this webservice is called, the user must be redirected via

POST to urlInscriptionForm with parameter TBK_TOKEN equal
The amount to be paid must be within the limits established for this
to the token. kind of transactions, the internal process is similar to a Webpay
regular charge.
Web Service method Process:

• The customer logs on and authenticates himself on the Multicode
It allows the ending of the registration process by
finishInscription
getting the Transbank user Mall seller’s webpage or app by entering his user’s name and
Input {token} password.
{responseCode}, {tbkUser}, {authorizationCode},
Output {cardType}, {cardNumber}, {cardExpirationDate}, • The customer selects the option to pay with Multicode Mall
{cardOrigin} Webpage.
• The seller uses the payment web service, published by

Transbank, providing the user’s identifier (obtained during
registration), user’s name (in the seller), the purchase order and
Once the Transbank registration flow is over, the
user is sent to the registration ending URL which the seller the details of each sub-transaction (seller’s code, amount, etc.).
defined (returnUrl). In that momento, the seller must call This allows to obtain the authorization response and code for
finishInscription. each of the involved payment sub-transactions.
The seller will have a maximum of 60 seconds to call this method
after they receive the token in the registration ending URL
(returnUrl). Once the 60 seconds have ellapsed without a call • The seller presents the payment result to the customer.
to finishInscription, the underway registration and the user will
be eliminated.
10.4 Eliminating user registration record

In case the seller needed to eliminate a user’s registration on
CLIENT MULTICODE WEBPAY
Multicode Mall Webpay, whether that be because of the removal of MALL SELLER
a customer on its system or because the customer has requested
not to operate by using this payment alternative anymore, the Payment
Login
seller will have to consume a Transbank web service with the user
identifier integrated in the registration. Select
product
and pay Pay
tbkUser
Web Service method
Other data (n)
It allows the elimination of a user’s registration authorizationCode (n)
removeInscription Result
on Multicode Mall Webpay Other data
Input {username}, {tbkUser}
Output {result)
Ilustración 12: Flow diagram of the payment process

Web Service method Web Service method

authorize It allows to authorize a payment. reverse It allows to reverse a payment.
Input Input
Header {username}, {tbkUser }, {buyOrder}. Header {buyOrder}.
List {commerceId}, {buyOrder}, {amount}, Output
(per store) sharesNumber}.
List {commerceId}, {buyOrder}, {reversed},
Output (per store) {reverseCode}.
{commerceId}, {buyOrder}, {settlementDate},
Header
{authorizationDate}.
{commerceId}, {buyOrder}, {amount},
List {authorizationCode}, {paymentType},
(per store) {responseCode}, {sharesNumber}, Calling this method and therefore the reversal operation
{shareAmount} can only be valid within the 30 seconds after the call to the authorize
method authorize.
10.7 Annulment of authorized payments

Method that has to be carried out every time the user selects This process allows to annul a Multicode payment, with the
to pay with Multicode Mall.
purpose of nullifying the charge made to the customer in the
authorization.
10.6 Reversal of authorized payments The seller, in case of needing to annul the payment, must consume
This process allows to reverse a Multicode Mall payment a web service published by Transbank with all the information
when there are operational problems (on the seller’s part) o obtained in the response to the payment authorization.
communication problems between the seller and Transbank that
prevent the timely reception of the authorization response. As in the It is important to point out that, opposite to what happens with
latter, the seller does not know what the result of the authorization, the reversal, this applies individually to the sub-transactions of a
he must try the reversal of the authorization transaction to avoid a Multicode Mall. The complete list of sub-transactions of a payment
possible imbalance between the seller and Transbank. cannot be annulled by a single call to this web service.
In order to carry out the reversal, the seller must consume a web Web Service method
service published by Transbank with the payment purchase order nullify It allows to annul a payment.
(generated by the parent seller). {buyOrder}, {authorizedAmount},
Input
{authorizationCode}, {nullifyAmount}
It is important to point out that the reversal will always apply to {token}, {buyOrder}, {commerceId},
the complete list under the parent purchase order. The reversal Output {authorizationCode}, {authorizationDate},
{nullifiedAmount}, {balance}.
operation should not be used for financial purposes because the
annulment operation is meant for those purposes (see 10.6).

10.8 Annulment reversal Web Service method

This process allows the reversal of a successful previous
reverseNullification It allows to reverse an annulment.
Multicode Mall annulment.
Input {buyOrder}, {commerceId}, {nullifyAmount}.
Output {reversed}, {reverseCode}.
In case of needing the reversal of an annulment transaction, the
seller must consume a web service published by Transbank with
the annulment information.
The call to this method and, therefore, the reversal
operation applied to the annulment, will only be available and valid
within the 30 seconds subsequent to the call to the nullyfi method.
10.9 Web Service methods detailed definition
initInscription
INPUT
email E-mail address registered by the seller, if not registered it has to be requested before.
username User or customer name in the seller’s system.
returnUrl URL to which the customer Will be forwarded once the registration process has been completed.
OUTPUT
Single/unique identifier of the registration process. It must be sent by means of a parameter (TBK_TOKEN) to the
token
urlInscriptionForm URL.
urlInscriptionForm Webpay URL to start the registration.
finishInscription
INPUT
token Identifier of the registration process. It is delivered by Webpay in the initInscription method response.
OUTPUT
responseCode Response code of the registration process, where 0 (zero) is approved.
Single/unique identifier of the customer’s registration, which must be used to make payments and to eliminate the
tbkUser
registration.
authorizationCode Code that identifies the registration authorization.
It indicates the credit card brand that was registered by the customer (Visa, American Express, MasterCard, Diners,
cardType
Magna)
cardNumber It indicates the last 4 digits and/or BIN of the credit card being used.
cardExpirationDate It indicates the expiration date of the credit card being used.
cardOrigin It indicates whether the credit card being used is national (NATIONAL_CARD) or foreign (FOREIGN_CARD).
removeUser
INPUT
tbkUser Single/unique identifier of the customer’s registration.

username Customer’s user name in the seller’s system.
OUTPUT
token Boolean indicating whether the elimination was carried out accordingly or not.

authorize
INPUT
Header
tbkUser Payment amount in pesos.
username Single/unique identifier of the customer’s registration.
buyOrder Customer’s user name in the seller’s system.
List (per store)
commerceId Child retailer’s seller code.
Single/unique purchase identifier generated by the parent seller. It must be timestamp [yyyymmddhhMMss] + a
three-digit correlate.
buyOrder
e.g. for the third transaction carried out on the 15th of july 2011 11:55:50 the purchase order would be:
20110715115550003.
amount Amount of the payment sub-transaction. In pesos or dollars depending on the parent seller configuration.
Number of installments of the payment sub-transaction.
sharesNumber Any non-number character used, including letters, inexistence of field or null, will be interpreted as zero,
that is, “No installments”.
OUTPUT
Header
commerceId Parent retailer’s seller code.
buyOrder Purchase order generated by the parent seller.
settlementDate Accounting date of the payment authorization.
authorizationDate Complete date (timestamp) of the payment authorization.
List (per store)
commerceId Child retailer’ s (store) seller code.
buyOrder Purchase order generated by child seller for the payment sub-transaction.
amount Amount of the payment sub-transaction.
authorizationCode Authorization code of the payment sub-transaction.
paymentType Payment sub-transaction type (VC, NC, SI, etc.).
Return code of the payment sub-transaction, where:
0 (zero) is approved.
-1 Rejected
-2 Rejected
-3 Rejected
-4 Rejected
responseCode -5 Rejected
-6 Rejected
-7 Rejected
-8 Rejected
-97 Multicode Mall limits: maximum number of daily payments exceeded.
-98 Multicode Mall limits: maximum amount of single payment exceeded. -99 Multicode Mall limits: maximum
number of daily transactions exceeded.
sharesNumber Number of installments of the payment sub-transaction.
shareAmount Amount per installment of the payment sub-transaction.

reverse
INPUT
buyorder Purchase order generated by the parent seller for the payment transaction to reverse.
OUTPUT
List (per store)
commerceId Child retailer’s (store) seller code.
buyOrder Purchase order generated by child seller for the payment sub-transaction.
reversed Boolean indicating whether the reversal was carried out accordingly or not.
reverseCode Single/Unique reversal transaction identifier.
nullify
INPUT
buyOrder Purchase order generated by child seller for the payment sub-transaction to annul.
authorizedAmount Amount of the payment sub-transaction to annul.
authorizationCode Authorization code of the payment sub-transaction to annul.
nullifyAmount Amount to annul of the payment sub-transaction. It can be a partial or total amount.
OUTPUT
token Single/Unique annulment transaction identifier.
buyOrder Purchase order of the annulled payment sub-transaction.
authorizationCode Authorization code of the annulment transaction.
authorizationDate Authorization date of the annulled transaction.
nullifiedAmount Annulled amount.
balance Remaining amount of the original payment transaction: initial amount - annulled amount.
reverseNullification
INPUT
buyOrder Purchase order generated by child seller for the annulled payment sub-transaction.
nullifyAmount Nullified amount from the annulment transaction to be reversed.
OUTPUT
reversed Boolean indicating whether the reversal was carried out accordingly or not.
reverseCode Single/Unique reversal transaction identifier.

11 DEFERRED CAPTURE TRANSACTION
11.1 Description of deferred capture For this purpose, indication about data associated to the authorized
This method allows every authorized seller to make captures of purchase transaction without capture and the required amount for
a transaction that has been authorized without capture on the 3G capture (smaller or equal to the originally authorized amount) must
Webpay platform. The method contemplates a single capture for be pointed out.
each authorization.
Erroneous executions will deliver a SoapFault according to the
defined error codification.
Resum Summary of the web service method of deferred capture.

It allows the request to Webpay of the deferred capture of an authorized transaction that was not captured simultaneously.
capture
This capture method must always be invoked by indicating the code of the seller that made the transaction.
In the case of MALL sellers, the code must be the virtual store code.
11.2 Description of the Web Service method of deferred capture

11.2.1 Capture operation
Method that allows the realization of the transaction capture.
INPUT PARAMETER
FIELD DESCRIPTION
xs:string
authorizationCode Authorization code of the transaction that needs to be captured.
Maximum length: 6
xs:string
buyOrder Purchase order of the transaction that needs to be captured.
Maximum length: 26
xs:long
commerceId Code of seller or mall store that made the transaction.
Length: 12
xs:decimal
captureAmount Amount that needs to be captured.
Maximum length: 10
OUTPUT PARAMETER
FIELD DESCRIPTION
xs:string
token
Transaction token
xs:string
authorizationCode
Authorization code of diferred capture
xs:dateTime
authorizationDate
Date and time of the authorization
xs:decimal
captureAmount
Captured amount

11.2.2 Error codes

The following are error codes exclusive to the Capture method.
CODE DESCRIPTION
304 Validation of null entrance fields.
245 Seller code does not exist
22 The seller is not active
316 The indicated seller does not correspond to the certificate or it is not the MALL seller’s child in the case of MALL transactions
308 Operation is not permitted
274 Transaction is not found
16 The transaction is not one of deferred capture.
292 The transaction is not authorized.
284 Capture period exceeded
310 Previously reversed transaction
309 Previously captured transaction
311 Amount to capture exceeds the authorized amount
315 Authorizer error
53 Transaction does not permit partial deferred capture transactions in installments

12 NULLIFYING TRANSACTION
12.1 Description of nullifying Webpay supports only one partial annulment for the online
This method allows every authorized seller to annul a transaction purchase transaction. In case of sending a second partial
generated on the 3G Webpay platform. The method can totally or annulment it will become an Exception.
partially annul a transaction. For this purpose, indication must be
provided about data associated to the purchase online transaction Executions with errors will deliver a SoapFault according to the
meant to be annulled and the annulled amount or the amount to defined error codification.
be annulled. The transaction is totally annulled when the annulled
amount or the total amount of completed annulments reaches the The annulment can be completed in a maximum of 30 days after
authorized amount for the online purchase. original transaction date.
Summary of web service method of transaction annulment.

It allows to request to Webpay the annulment of a previously made transaction which is still valid.
Nullify
The nullify method must always be invoked by indicating the code of the seller that made the transaction.
In the case of MALL sellers, the code must be the virtual store code
121.2 Description of the Web Service method of transaction 12.2.1 Nullify operation
nullifying Method that allows to annul a payment transaction.
INPUT PARAMETER
FIELD DESCRIPTION
xs:string
The transaction authorization code that needs to be annulled. If what is being annulled is an online capture
authorizationCode
transaction, this code corresponds to the capture authorization code.
Maximum length: 6
xs:decimal
Transaction authorized amount that needs to be annulled. If what is being annulled is an online capture transaction,
authorizedAmount
this amount corresponds to the capture amount.
Maximum length: 10
xs:string
buyOrder Purchase order of the transaction that needs to be annulled.
Maximum length: 26
xs:long
commerceId Seller or mall store code that made the transaction.
Length: 12
xs:decimal
ullifyAmount Transaction amount that needs to be annulled.
Maximum length: 10
OUTPUT PARAMETER
FIELD DESCRIPTION
xs:string
token
Transaction token
xs:string
authorizationCode
Annulment athorization code
xs:dateTime
authorizationDate
Authorization date and time
xs:decimal
Balance
Updated transaction balance (it considers the purchase minus the annulled amount)
xs:decimal
nullifiedAmount
Annulled amount

12.2.2 Error codes

The following error codes are he most commonly associated to the annulment method
CÓDIGO DESCRIPCIÓN
304 Null input fields validation
245 Seller code does not exist
22 The seller is not active
316 The indicated seller does not correspond to the certificate ori t is not MALL seller’s child in the case of MALL transactions.
308 Operation not permitted
274 Transaction not found
16 The transaction does not allow annulment.
292 The transaction is not authorized.
284 Exceeded annulment period.
310 Previously annulled transaction.
311 Amount to annul exceeds the balance. The amount to annul exceeds the balance available for annulment.
312 Generic error for annulments
315 Authorizer error

13 APPENDIXES
13 APPENDIXES
13.1 Apendix A: Webpay environments and key creation

13.1.1 Private key and public certificate creation 1. Create private key.
This is an example to create a private key, the Certificate Signing In a terminal or control panel, using openSSL, create a key using
Request (CSR) and the productive public certificate of a seller the following command.
whose productive seller code is 12345678
openssl genrsa -out 597012345678.key 2048
2. Create certificate requirement. command will have to create the certificate requirement (csr file).
Keeping the private key in the same directory, using the following
openssl req -new -key 597012345678.key -out 597012345678.csr
The following information will have to be entered, being especially It will be generated by a file called 59702012345678.csr
careful to enter the productive seller code, already provided by
Transbank, in the field Common Name (CN) as follows:
Country Name (2 letter code) []:CL

State or Province Name (full name) []: Ingrese_su_provincia
Locality Name (eg, city) []:Ingrese_su_ciudad
Organization Name (eg, company) []: Ingrese_el_nombre_de_su_organizacion
_el Organizational Unit Name (eg, section) []: Ingrese_un_nombre_opcional
Common Name (eg, your name or your server’s hostname) []:597012345678
Email Address []:
Please enter the following ‘extra’ attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
3. Create self-signed certificate command, trying to indicate 1460 days or more for certificate
Once the private key and the CRS have been created, the validity extension.
public certificate needs to be created by means of the following
openssl x509 -req -days 1460 -in 597029124456.csr -signkey 597029124456.key -out 597012345678.crt
After all these steps, 3 files will be obtained:

• 59702012345678.key
• 59702012345678.csr
• 59702012345678.crt The seller is responsible to take care of their private
key and their public certificate, as well as responsible for
And it is this last (crt) that the seller shares with Transbank for the replacing these when they expire.
authorization of their seller in production.

13 APPENDIXES
13.1.2 Webpay environment

integration / validation endpoint
https://webpay3gint.transbank.cl/WSWebpayTransaction/cxf/WSWebpayService?wsdl

Public certificate for Webpay integration
-----BEGIN CERTIFICATE-----
MIIDKTCCAhECBFZl7uIwDQYJKoZIhvcNAQEFBQAwWTELMAkGA1UEBhMCQ0wxDjAMBgNVBAgMBUNo
aWxlMREwDwYDVQQHDAhTYW50aWFnbzEMMAoGA1UECgwDa2R1MQwwCgYDVQQLDANrZHUxCzAJBgNV
BAMMAjEwMB4XDTE1MTIwNzIwNDEwNloXDTE4MDkwMjIwNDEwNlowWTELMAkGA1UEBhMCQ0wxDjAM
BgNVBAgMBUNoaWxlMREwDwYDVQQHDAhTYW50aWFnbzEMMAoGA1UECgwDa2R1MQwwCgYDVQQLDANr
ZHUxCzAJBgNVBAMMAjEwMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAizJUWTDC7nfP
3jmZpWXFdG9oKyBrU0Bdl6fKif9a1GrwevThsU5Dq3wiRfYvomStNjFDYFXOs9pRIxqX2AWDybjA
X/+bdDTVbM+xXllA9stJY8s7hxAvwwO7IEuOmYDpmLKP7J+4KkNH7yxsKZyLL9trG3iSjV6Y6SO5
EEhUsdxoJFAow/h7qizJW0kOaWRcljf7kpqJAL3AadIuqV+hlf+Ts/64aMsfSJJA6xdbdp9ddgVF
oqUl1M8vpmd4glxlSrYmEkbYwdI9uF2d6bAeaneBPJFZr6KQqlbbrVyeJZqmMlEPy0qPco1TIxrd
EHlXgIFJLyyMRAyjX9i4l70xjwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQBn3tUPS6e2USgMrPKp
sxU4OTfW64+mfD6QrVeBOh81f6aGHa67sMJn8FE/cG6jrUmX/FP1/Cpbpvkm5UUlFKpgaFfHv+Kg
CpEvgcRIv/OeIi6Jbuu3NrPdGPwzYkzlOQnmgio5RGb6GSs+OQ0mUWZ9J1+YtdZc+xTga0x7nsCT
5xNcUXsZKhyjoKhXtxJm3eyB3ysLNyuL/RHy/EyNEWiUhvt1SIePnW+Y4/cjQWYwNqSqMzTSW9TP
2QR2bX/W2H6ktRcLsgBK9mq7lE36p3q6c9DtZJE+xfA4NGCYWM9hd8pbusnoNO7AFxJZOuuvLZI7
JvD7YLhPvCYKry7N6x3l
-----END CERTIFICATE-----
Production endpoint
https://webpay3g.transbank.cl/WSWebpayTransaction/cxf/WSWebpayService?wsdl
Webpay productive certificate
-----BEGIN CERTIFICATE-----
MIIDNDCCAhwCCQCJEQxY1moacjANBgkqhkiG9w0BAQsFADBcMQswCQYDVQQGEwJD
TDELMAkGA1UECBMCUk0xETAPBgNVBAcTCFNhbnRpYWdvMRIwEAYDVQQKEwl0cmFu
c2JhbmsxDDAKBgNVBAsTA1BSRDELMAkGA1UEAxMCMTAwHhcNMTQwNTA4MjEwNjIy
WhcNMTgwNTA4MjEwNjIyWjBcMQswCQYDVQQGEwJDTDELMAkGA1UECBMCUk0xETAP
BgNVBAcTCFNhbnRpYWdvMRIwEAYDVQQKEwl0cmFuc2JhbmsxDDAKBgNVBAsTA1BS
RDELMAkGA1UEAxMCMTAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCk
ag5P6b/BnlpxGk1YX8OeX04ZqmxWThxHP1J+6FVj/hMYw9JGf2gMDCWd3fYaWwRM
X7Y6MidAGCiVwNgsixsUad9C2qQWtpTHoc3T+rQuZ6wmGwxc/K/Gcjf4nuJQUPBo
3zjat+HC0HzPrTscms4A2EZ2VQ/bbznKiOWxcBSqqZ/8jK/RMmu4E6Pzj8Ms+vbA
BfDCq9GDfeNZ+gtQna86enEX7XY/N55SO+VHv/6zGIof7kGIobeF1hYwALrKDhvy
FVQgh4VUBhP0adtnQBfCc1mGVgnviAjioxMxGT4wwaj6IfTvtHhkxVcJ9qmX9oki
wygTooWtcMM6U4oiVd+vAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAEqW5DtWdAUP
iSBpExhPgSnm+X6eiDmM3q0S8gWls3hnZCQ9RfhVROj93OS4Zaqg82RLGiU3GsWF
pj4YRw0flCC7bCxo7Mt4Lvv6ihQYdsWxA97HN55HQOVv853kQAu6/vnCxoTtMt6W
+zuiQY7hhabLhOCNJcrFpabj0wCO62IrWv65AZlikcsNKLAwQrstY7Y1VU5DOcXy
FfE5niUGxH0mARXMxq1Z3CBqJ3GKKMmngqCMxX8ZFjIvz0z0VsOJQheX4Hl8prAR
ZlVlkH02xlKKLIO2tcnXik1eW5VCpzuF6z9W3WqcvpaltfspJPx3kN3k5NHATNgk
IypDl0jmq2w=
-----END CERTIFICATE-----

13 APPENDIXES
13.2 Appendix B: Transition pages and transaction end page • Transaction authorization code
requirements • Transaction date
13.2.1 Transition page requirements • Type of payment made (Debit or Credit)
The seller transition page is the page that the seller displays when • Kind of installment
Webpay gives them the control, after the authorization process • Number of installments
and previous to the redirection of the cardholder to the transaction • 4 last digits of the bank card
successful receipt. It applies to all the types of transaction. • Goods and/or services description
It is recommended that on this page the payment form backgound 13.2.3 Checkout failure page requirements
image that is on the URL be displayed. When the transaction is not authorized, it is recommended to
inform the cardholder about it.
https://webpay3g.transbank.cl/
webpayserver/imagenes/background.gif
An explanatory text such as the following may be displayed:
13.2.2 Checkout success page requirements
Once the transaction is completed, the seller must display a page
Purchase order XXXXXXX
for cardholder so as to inform them about the transaction result.
The information to be presented will depend on whether the The possible declination causes are:
transaction was authorized or not.
- Error in entering your credit or debit card information (date
and/or security code).
It is recommended that it contain at least
• Request order number - Your credit or debit card does not enough credit.
• Seller’s name (Mall store) - The card has not been activated to be used in the financial
• Transaction amount and currency system yet.

13 APPENDIXES
13.3 Appendix C: Webpay API SOAP exceptions

The most common exceptions that can be displayed in any Webpay integration in their SOAP modality are the following.
# ERROR # ERROR
1 ERR_LECTURA_INPUT 40 ERR_CONF_TIENDA
2 ERR_LECTURA_PARAMETROS 41 ERR_URL_RESULTADO
3 ERR_PARAM_CODIGO_COMERCIO 42 ERR_CONECTA_SERVIDOR
4 ERR_PARAM_URL_CGI_COMERCIO 43 ERR_SOCKET_LECTURA
5 ERR_PARAM_SERVIDOR_COMERCIO 44 ERR_SOCKET_ESCRITURA
6 ERR_PARAM_PUERTO_COMERCIO 45 ERR_TIMEOUT_ACK
7 ERR_PARAM_URL_CGI_TRANSBANK 46 ERR_OBTENER_ACK
8 ERR_PARAM_SERVIDOR_TRANSBANK 47 ERR_ORDEN_TIENDA
9 ERR_PARAM_PUERTO_TRANSBANK 48 ERR_NUMERO_TARJETA
10 ERR_MEM_MENSAJE 49 ERR_NUMERO_CUOTAS
11 ERR_MAC 50 ERR_MES_VENCIMIENTO
12 ERR_VERSION_KCC 51 ERR_ANO_VENCIMIENTO
13 ERR_MSG_OLDKCC 52 ERR_TARJETA
14 ERR_CODIGO_COMERCIO 53 ERR_TIPO_PAGO
15 ERR_DATOS_COMERCIO 54 ERR_RESPUESTA_BASE24
16 ERR_TIPO_TRANSACCION 55 ERR_ACK
17 ERR_URL_CGI_COMERCIO 57 ERR_TIENDA_EN_NULO
18 ERR_SERVIDOR_COMERCIO 58 ERR_PARAM_PREF_CONF_TR
19 ERR_PUERTO_COMERCIO 59 ERR_PARAM_URL_CONF_TR
20 ERR_CVV 60 ERR_PARAM_PUERTO_CONF_TR
21 ERR_DUPLICADO 61 ERR_PARAM_SERVIDOR_CONF_TR
22 ERR_ESTADO_COMERCIO 62 ERR_FECHA_TRANSACCION
23 ERR_TEMPLATE_COMPRA 63 ERR_ABRIR_BITACORA
24 ERR_TEMPLATE_COMPRA_DET 64 ERR_FALLO_CUOTA_NORMAL
25 ERR_FECHA_EXPIRACION 65 ERR_FALLO_CUOTA_C3C
26 ERR_MONEDA_INVALIDA 66 ERR_MONEDA_DESCONOCIDA
27 ERR_TEMPLATE_REINTENTO 67 ERR_TIENDA_NOENCONTRADA
28 ERR_EDITA_MONTO 68 ERR_TIENDA_NOASOCIADA
29 ERR_ORDEN_COMPRA 69 ERR_TIENDA_DIF_MONEDA
30 ERR_ID_TRANSACCION 70 ERR_SINMEMORIA
31 ERR_URL_EXITO 71 ERR_MONTO_DESCUADRADO
32 ERR_URL_FRACASO 72 ERR_TRX_DESCUADRADAS
33 ERR_MONTO 73 ERR_TEMPLATE_ONECLICK
34 ERR_REFERER 74 ERR_TIENDA_TIPO_PAGO
35 ERR_NUM_TRX 75 ERR_ID_USUARIO
36 ERR_MAX_TIENDA 76 ERR_USUARIO_YA_REGISTRADO
37 ERR_CODIGO_TIENDA 77 ERR_INSERTAR_ONECLICK
38 ERR_TIENDA_NO_SOCIADA 78 ERR_USUARIO_NO_REGISTRADO
39 ERR_MONTO_TIENDA 79 ERR_LEER_ONECLICK

13 APPENDIXES
# ERROR # ERROR
80 ERR_TEMPLATE_TRANSICION 121 ERR_LARGO_TIPO_TBK_PUERTO_COMERCIO
81 ERR_LOGO_WEBPAY 122 ERR_LEN_TBK_VERSION_KCC
82 ERR_TEMPLATE_LOGO_WEBPAY 123 ERR_LEN_TBK_MAC
83 ERR_ACTUALIZAR_ONECLICK 124 ERR_LEN_TBK_MONTO
84 ERR_ELIMINAR_ONECLICK 125 ERR_LEN_TBK_ORDEN_COMPRA
85 ERR_TEMPLATE_MENSAJE 126 ERR_LEN_TBK_ID_SESION
86 ERR_NUMERO_TARJET_ANTIGUA 127 ERR_LEN_TBK_URL_EXITO
87 ERR_ONECLICK_DESHABILITADO 128 ERR_LEN_TBK_URL_FRACASO
88 ERR_TR_COMPLETA_DESHABILITADA 129 ERR_LEN_TBK_TARJETA
89 ERR_CAMBIO_MULTICODE 130 ERR_LEN_TBK_TIPO_PAGO
90 ERR_RESPUESTA 131 ERR_LEN_TBK_NUMERO_CUOTAS
91 ERR_LARGO_TIENDA 132 ERR_LEN_TBK_NUMERO_TARJETA
92 ERR_CORRESPONDENCIA_CUOTAS 133 ERR_LEN_TBK_MES_VENCIMIENTO
93 ERR_TIPO_PAGO_DESHABILITADO 134 ERR_LEN_TBK_ANO_VENCIMIENTO
94 ERR_ENVIO_REG_ONECLICK 135 ERR_LEN_TBK_CVV
95 ERR_ID_SESION 136 ERR_TIPO_TBK_URL_RESULTADO
96 ERR_TIPO_TBK_TIPO_TRANSACCION 137 ERR_TIPO_TBK_NUM_TRX
97 ERR_TIPO_TBK_CODIGO_COMERCIO 138 ERR_TIPO_TBK_CODIGO_TIENDA
98 ERR_TIPO_TBK_ID_TRANSACCION 139 ERR_TIPO_TBK_ORDEN_TIENDA
99 ERR_TIPO_TBK_URL_CGI_COMERCIO 140 ERR_TIPO_TBK_MONTO_TIENDA
100 ERR_TIPO_TBK_SERVIDOR_COMERCIO 141 ERR_TIPO_TBK_ID_USUARIO
101 ERR_TIPO_TBK_PUERTO_COMERCIO 142 ERR_LEN_TBK_URL_RESULTADO
102 ERR_TIPO_TBK_VERSION_KCC 143 ERR_LARGO_TIPO_TBK_NUM_TRX
103 ERR_TIPO_TBK_MAC 144 ERR_LARGO_TIPO_TBK_CODIGO_TIENDA
104 ERR_TIPO_TBK_MONTO 145 ERR_LARGO_TIPO_TBK_ORDEN_TIENDA
105 ERR_TIPO_TBK_ORDEN_COMPRA 146 ERR_LARGO_TIPO_TBK_MONTO_TIENDA
106 ERR_TIPO_TBK_ID_SESION 147 ERR_LARGO_TIPO_TBK_ID_USUARIO
107 ERR_TIPO_TBK_URL_EXITO 148 ERR_LEN_PARAM_TR_NORMAL
108 ERR_TIPO_TBK_URL_FRACASO 149 ERR_LEN_PARAM_TR_MALL
109 ERR_TIPO_TBK_TARJETA 150 ERR_LEN_PARAM_TR_COMPLETA
110 ERR_TIPO_TBK_TIPO_PAGO 151 ERR_LEN_PARAM_TR_ONECLICK
111 ERR_TIPO_TBK_NUMERO_CUOTAS 152 ERR_LEN_PARAM_TR_INGRESO_ONECLICK
112 ERR_TIPO_TBK_NUMERO_TARJETA 153 ERR_LEN_PARAM_TR_ELIMINACION_ONECLICK
113 ERR_TIPO_TBK_MES_VENCIMIENTO 154 ERR_LEN_PARAM_TR_MODIFICACION_ONECLICK
114 ERR_TIPO_TBK_ANO_VENCIMIENTO 155 ERR_LEN_PARAM_TR_MALL_COMPLETA
115 ERR_TIPO_TBK_CVV 156 ERR_LEN_PARAM_TR_MALL_ONECLICK
116 ERR_LEN_TBK_TIPO_TRANSACCION 157 ERR_LEN_PARAM_TR_LOGO_WEBPAY
117 ERR_LEN_TBK_CODIGO_COMERCIO 158 ERR_CANT_PARAM_TR_NORMAL
118 ERR_LEN_TBK_ID_TRANSACCION 159 ERR_CANT_PARAM_TR_MALL
119 ERR_LEN_TBK_URL_CGI_COMERCIO 160 ERR_CANT_PARAM_TR_COMPLETA
120 ERR_LEN_TBK_SERVIDOR_COMERCIO 161 ERR_CANCOMERCIOT_PARAM_TR_ONECLICK

13 APPENDIXES
# ERROR # ERROR
162 ERR_CANT_PARAM_TR_INGRESO_ONECLICK 264 ERR_TOKEN_INVFOR
163 ERR_CANT_PARAM_TR_ELIMINACION_ONECLICK 265 ERR_BUFF_OVERFLOW
164 ERR_CANT_PARAM_TR_MODIFICACION_ONECLICK 266 ERR_TRANSACCION_DEBITO_NO_PERMITIDA
165 ERR_CANT_PARAM_TR_MALL_COMPLETA 267 ERR_TRANSACCION_NECESITA_AUTENTICAR
166 ERR_CANT_PARAM_TR_MALL_ONECLICK 268 ERR_TRANSACCION_DEBITO_FALTA_PARAMETRO
167 ERR_CANT_PARAM_TR_LOGO_WEBPAY 269 ERR_CORRESPONDENCIA_TRANSACCION_DEBITO
170 ERR_TIPO_TBK_FECHA_EXPIRACION 270 ERR_CANT_PARAM_COMUNES
171 ERR_LEN_TBK_FECHA_EXPIRACION 271 ERR_FALTA_PARAM
172 ERR_TIPO_TBK_URL_COMERCIO 272 ERR_TIMEOUT
173 ERR_LEN_TIPO_TBK_URL_COMERCIO 273 ERR_MONTO_CERO
174 ERR_TIPO_TBK_MONTO_CUOTA 274 ERR_TRANSACCION_NO_ENCONTRADA
175 ERR_LEN_TBK_MONTO_CUOTA 275 ERR_INSTRUMENTO_DE_PAGO
176 ERR_MONTO_CUOTA 276 ERR_IR_PAGINA_FALLO
177 ERR_TR_TASA_INTERES_DESHABILITADA 277 ERR_TIPO_CONEXION_COMERCIO
178 ERR_LEN_PARAM_TR_TASA_INTERES_MAX 278 ERR_MALL_NO_IGUAL_TIENDA
179 ERR_CANT_PARAM_TR_TASA_INTERES_MAX 279 ERR_MALL_SIN_TIENDA
180 ERR_CONSISTENCIA_CIC 280 ERR_HTTP
181 ERR_FALLO_CUOTA_CIC 281 ERR_FILE_POPULATOR
241 ERR_TBK_TOKEN_NO_ENCONTRADO 282 ERR_FORMAT_PARAM
242 ERR_RESPUESTA_AUTH 283 ERR_ENCRIPTATION
243 ERR_EMISOR_NO_ENCONTRADO 284 ERR_EXPIRED_TIME
244 ERR_ARCHIVO_EMISOR 285 ERR_RUT
245 ERR_COMERCIO_NO_ENCONTRADO 286 ERR_SET_STATUS
246 ERR_ARCHIVO_COMERCIO 287 ERR_PARAM_LEN
247 ERR_BIN_NO_ENCONTRADO 288 ERR_DOUBLE_SUBMIT
248 ERR_ARCHIVO_BINES 289 ERR_INCONSISTENT_BIN_INFO
249 ERR_EMISOR_NO_PARTICIPA 290 ERR_VCI_DECISION_TABLE
250 ERR_COMERCIO_NO_PARTICIPA 291 ERR_NOT_FOUND_PARAM
251 ERR_TRANSACCION_NO_PARTICPA 292 ERR_INVALID_STATUS
252 ERR_NO_SE_PUEDE_GENERAR_TOKEN 293 ERR_INVOCATION_METHOD
253 ERR_BIN_NO_PARTICIPA 294 ERR_ANOTHER_TRANSACCION
254 ERR_VVR 295 ERR_SEND_MAIL
255 ERR_TOKEN_STATUS 296 ERR_UNKNOWN
256 ERR_GEN_TOKENCOM 300 ERR_INVALID_TOKEN
257 ERR_SIN_VALIDACION 301 ERR_MALL_COMMERCES_MAX
258 ERR_TBK_PARAM 302 ERR_BUTTON_COMMERCE_NOT_FOUND
259 ERR_SSL_CONEXION 303 ERR_COMMERCE_NOT_WPM
260 ERR_SSL_ESCRITURA 304 ERR_INVALID_INPUT_DATA
261 ERR_SSL_REINTENTAR 305 ERR_COMMERCE_WPM
262 ERR_SSL_LECTURA 306 ERR_COMMERCE_SIGNATURE_MATCH
263 ERR_PUB_KEY 307 ERR_COMMERCE_NOT_FOUND

13 APPENDIXES
# ERROR # ERROR
308 ERR_OPERATION_NOT_ALLOWED 319 ERR_CAPTURE_GENERIC
309 ERR_TRANSACTION_ALREADY_CAPTURED 320 ERR_COMMERCES_UNRELATED
310 ERR_TRANSACTION_NULLIFIED 321 ERR_DETAIL_NOT_FOUND
311 ERR_EXCEEDED_REQUIRED_BALANCE 322 ERR_PAYMENT_TYPE_NUMBER
312 ERR_NULLIFY_GENERIC 323 ERR_UF_SERVICE_ERROR
313 ERR_COMMERCE_NOT_INTELLIGENT ERR_DEFERRED_CAPTURE_NOT_ALLOWED_
324
314 ERR_PAYMENT_TYPE_NOT_FOUND TRANSACTION_TYPE
315 ERR_DEFERRED_PERIOD_NOT_FOUND 325 ERR_ONECLICK_HABILITADO

316 ERR_QUERY_SHARE_NOT_FOUND 326 ERR_INVALID_KEY
317 ERR_INCOMPATIBLE_PAYMENT_TYPE 327 ERR_COMMERCE_WSCT_WITH_ONLINE_CAPTURE
318 ERR_GRACE_FLAG_NOT_ENABLED 328 ONE_CLICK_REVERSE_TIMEOUT
13.4 Appendix D: Validation tests carried out by Transbank 13.4.3 Validation tests for Normal Transaction, deferred capture
13.4.1 Validation tests for Normal Transaction, plugin mode • Successful credit payment, no installments
• Successful credit payment, no installments • Successful credit payment, installments
• Successful credit payment, installments • Declined payment credit
• Declined payment credit • Cancelled payment (aborte don Webpay form)
• Successful debit payment • Partial annulment (only if the method is integrated)
• Declined debit payment • Total annulment (only if the method is integrated)
• Cancelled payment (aborte don Webpay form)
13.4.4 Validation tests for Mall Transaction
13.4.2 Validation tests for Normal Transaction • Successful credit payment, no installments
• Successful credit payment, no installments • Successful credit payment, installments
• Successful credit payment, installments • Declined payment credit
• Declined payment credit • Successful debit payment
• Successful debit payment • Declined debit payment
• Declined debit payment • Partial annulment (only if the method is integrated)
• Partial annulment (only if the method is integrated) • Total annulment (only if the method is integrated)
• Total annulment (only if the method is integrated) • Cancelled payment (aborte don Webpay form)
• Cancelled payment (aborte don Webpay form)
13.4.5 Validation tests for OneClick Transaction
• Declined registration
• Successful registration
• Authorization
• Reversal
• Remove user

13 APPENDIXES
13.5 Appendix D: References
https://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

13 APPENDIXES
13.6 Appendix F: Examples of integration with Webpay Next, in order to generate the necessary clases to connect
API SOAP to Web services, the Easy WSDL2PHP tool can be used.
The following examples seek to present a feasible way of The required documents and download information can be
integration with Webpay API SOAP to resolve the following found on
points relating integration:
http://sourceforge.net/projects/easywsdl2php/
1. Customer or tool generation to consume Web services, which
allows to abstract from complex SOAP messaging associated Once the fonts/sources are downloaded, they have to be copied
to Web services and to make use of the service operations. in the Apache directory that has an output through the browser.
2. Message signature and signature validation in the The file wsdl2php.php is called through the browser and the
response; there are frameworks and tools associated to following screen is displayed:
every programming language that implments the WS Security
standard; all you need to do is to use one the them, set it and
let it carry out the message digital signature process.
The following example is based on PHP version 5, on which

the following software libraries were used to call Webpay web
services under the WSS standard:
• Security library: file made up of three classes that integrate The URL of the WSDL file you need to connect to and a class
validation and verification PHP native libraries. These classes name are entered and then click on the GenerateCode button.
allow us to generate enough security through methods of After this, a screen like the following is displayed:
encryption and decryption.
• WSSE-PHP: it integrates the XML security libraries and

generates a safe XML-SOAP document. It depends on XML
security libraries.
• SOAP-VALIDATION: class in charge of response safe SOAP

validation messages. It verifies the authenticity and integrity of
the message. It depends on WSSE-PHP.
Fonts/Sources can be downloaded from
https://github.com/OrangePeople/php-wss-validation

Steps to follow:
1. Web Service customer generation:
Before the integration an Apache HTTP server must be insalled
and working and set the directory to generate an output through
the web browser. If a more simple alternative is desired, Apache
provides a directory by omission, which varies according to the Once the result displayed in the image is obtained, you need
operating system. Generally, on Linux platforms it is “/var/ to copy and save in a file the generated PHP, which represents
www” and on Windows “C:\<directorio hacia Apache>/ the web service stub. Once this process is carried out you
htdocs”. are in possession of the necessary classes to integrate with
Webpay web services.

13 APPENDIXES
2. Create a class that extends from SoapClient (SoapClient is

the native class that provides PHP for the use of Web services)
(In the example is called MySoap)
//Note that two files are provided in the encrypting library

require_once(‘xmlseclibs.php’);
require_once(‘soap-wsse.php’);
define(“PRIVATE_KEY”, “private_key.pem”);
define(‘CERT_FILE’, ‘cert_file.pem’);
define(“SERVER_CERT”, “oneclick.pem”);
class MySoap extends SoapClient {
function __doRequest($request, $location, $saction, $version) {

$doc = new DOMDocument(‘1.0’);
$doc->loadXML($request);
$objWSSE = new WSSESoap($doc);
$objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA1,array(‘type’ =>
‘private’));
$objKey->loadKey(PRIVATE_KEY, TRUE);
$options = array(“insertBefore” => TRUE);
$objWSSE->signSoapDoc($objKey, $options);
$objWSSE->addIssuerSerial(CERT_FILE);
$objKey = new XMLSecurityKey(XMLSecurityKey::AES256_CBC);
$objKey->generateSessionKey();
$retVal = parent::__doRequest($objWSSE->saveXML(), $location, $saction,
$version);
$doc = new DOMDocument();
$doc->loadXML($retVal);
return $doc->saveXML();
}
}
The constants PRIVATE_KEY and CERT_FILE are the routes of Where it says:
the lost key and seller certificate respectively.
$this->soapClient = new SoapClient($url,

3. Include the generated class in the previous step in the
array(“classmap” =>self::$classmap, “trace” =>
main file of the services. true, “exceptions” => true));
The class previously generated has to be included with the
sentence require_once.
Has to stay: (using the class name from step 2)
Example:

require_once(“mysoap.php”); $this->soapClient = new MySoap($url,
array(“classmap” =>self::$classmap, “trace”
4. Edit the stub file created in step 1 => true, “exceptions” => true));
The stub method __contruct has to be edited as illustrated in
the example:

13 APPENDIXES
5. Webpay web service operation call. 4. The getValidationResult method indicate whether the
message is signed by Transbank. This must be validated in all
Observations cases.
1. For all the examples, reference to the files in the downloaded 5. The SERVER_CERT constant represents the certificate route
library must be made. delivered by Transbank to carry out the integration. In this
case, Transbank must be in possession of the seller’s public
key and the seller in possession of its own private key and of
require_once(‘soap-wsse.php’); Transbank’s public key.
require_once(‘soap-validation.php’); 6. Transbank provides the public key for the seller to establish
require_once(<file containing the stub class a specific route so that the same application can call it.
created in step 1>); 7. The PRIVATE_KEY y CERT_FILE constants represent the
routes where the private and public keys are respectively
located. These parameters are completely settable and can be
2. The OneClickWS object represents the generated stub class. called in the file where the MySoap customized class can be
3. The objects with the response suffix contain the response to found. (e.g. mysoap.php).
the operation carried out.
Operation initInscription
define(“SERVER_CERT”, dirname(__FILE__) . “/certs/oneclick.pem”);

$oneClickService = new OneClickWS();
$initInscription = new initInscription();
$initInscriptionResponse = new initInscriptionResponse();
$oneClickInitInscriptionInput = new wsOneClickMulticodeInitInscriptionInput();
$oneClickInitInscriptionOutput = new wsOneClickMulticodeInitInscriptionOutput();
$oneClickInitInscriptionInput->email = ‘<email del usuario>’;

$oneClickInitInscriptionInput->username = ‘<nombre del usuario del comercio>’;
$oneClickInitInscriptionInput->returnUrl = ‘<url comercio resultado de inscripción>’;
$initInscription->input = $oneClickInitInscriptionInput;
$initInscriptionResponse = $oneClickService->initInscription($initInscription);
$xmlResponse = $oneClickService->soapClient->__getLastResponse();
$soapValidation = new SoapValidation($xmlResponse, SERVER_CERT);
//Esto valida si el mensaje está firmado por Transbank

$soapValidation->getValidationResult();
//Esto obtiene el resultado de la operación

$oneClickInitInscriptionOutput = $initInscriptionResponse->return;
//Token de resultado
$tokenOneClick = $oneClickInitInscriptionOutput->token;
//URL para realizar el post

$inscriptionURL = $oneClickInitInscriptionOutput->urlInscriptionForm;

13 APPENDIXES
Operation finishInscription

$finishInscription = new finishInscription();
$initInscriptionResponse = new finishInscriptionResponse();
$oneClickFinishInscriptionInput = new wsOneClickMulticodeFinishInscriptionInput();
$oneClickFinishInscriptionOutput = new wsOneClickMulticodeFinishInscriptionOutput();
$oneClickFinishInscriptionInput->token = ‘<token que devuelve el servicio initInscription>’;

$finishInscription->input = $oneClickFinishInscriptionInput;
$oneClickFinishInscriptionResponse = $oneClickService->finishInscription($finishInscription);
$oneClickFinishInscriptionOutput = $oneClickFinishInscriptionResponse->return;
$authorizationCode = $oneClickFinishInscriptionOutput->authorizationCode;
$cardExpirationDate = $oneClickFinishInscriptionOutput->cardExpirationDate;
$cardNumber = $oneClickFinishInscriptionOutput->cardNumber;
$cardOrigin = $oneClickFinishInscriptionOutput->cardOrigin;
$cardType = $oneClickFinishInscriptionOutput->cardType;
$responseCode = $oneClickFinishInscriptionOutput->responseCode;
$tbkUser = $oneClickFinishInscriptionOutput->tbkUser;

13 APPENDIXES
Operation authorize

$authorize = new authorize();
$authorizeResponse = new authorizeResponse();
$paymentInput = new wsOneClickMulticodePaymentInput();
$storePaymentInput = new wsOneClickMulticodeStorePaymentInput();
$paymentOutput = new wsOneClickMulticodePaymentOutput();
$storePaymentOutput = new wsOneClickMulticodeStorePaymentOutput();
$paymentInput->username = ‘<identificador de usuario del comercio>;’;

$paymentInput->tbkUser = ‘<identificador de usuario entregado en el servicio finishInscription>’;
$paymentInput->buyOrder = ‘<orden de compra>’;
$storePaymentInput->buyOrder = ‘<orden de compra del comercio 1>’;

$storePaymentInput->amount = ‘<monto de pago del comercio 1>’;
$storePaymentInput->commerceId = ‘<identificador del comercio 1>’;
$storePaymentInput->sharesNumber = ‘<cuotas>’;
$paymentInput->storesInput = $storePaymentInput;
$authorize->input = $paymentInput;
$authorizeResponse = $oneClickService->authorize($authorize);
$soapValidation->getValidationResult(); //Esto valida si el mensaje está firmado por
$paymentOutput = $authorizeResponse->return;
$commerceId = $paymentOutput->commerceId;
$buyOrder = $paymentOutput->buyOrder;
$settlementDate = $paymentOutput->settlementDate;
$authorizationDate = $paymentOutput->authorizationDate;
$storePaymentOutput = $paymentOutput->storesOutput;
$storeCommerceId = $storePaymentOutput->commerceId;
$storeBuyOrder = $storePaymentOutput->buyOrder;
$storeAmount = $storePaymentOutput->amount;
$storePaymentType = $storePaymentOutput->paymentType;
$storeSharesNumber = $storePaymentOutput->sharesNumber;
$stroeShareAmount = $storePaymentOutput->shareAmount;
$storeAuthorizationCode = $storePaymentOutput->authorizationCode;
$storeResponseCode = $storePaymentOutput->responseCode;

13 APPENDIXES
Operation reverse

$reverse = new reverse();
$reverseResponse = new reverseResponse();
$oneClickReverseInput = new wsOneClickMulticodeReverseInput();
$oneClickReverseOutput = new wsOneClickMulticodeReverseOutput();
$oneClickReverseInput->buyOrder = ‘<orden de compra>’;
$reverse->input = $oneClickReverseInput;
$reverseResponse = $oneClickService->reverse($reverse);
$soapValidation->getValidationResult(); //Esto valida si el mensaje está firmado por Transbank
$oneClickReverseOutput = $reverseResponse->return;
$storesReverse = $oneClickReverseOutput->storesReverse;
Operation removeInscription (removes the registered user)

$removeInscription = new removeInscription();
$removeInscriptionResponse = new removeInscriptionResponse();
$oneClickRemoveInscriptionInput = new wsOneClickMulticodeRemoveInscriptionInput();
$oneClickRemoveInscriptionOutput = new wsOneClickMulticodeRemoveInscriptionOutput();
$oneClickRemoveInscriptionInput->tbkUser = ‘<usuario tbk>’;

$oneClickRemoveInscriptionInput->username = ‘<nombre de usuario asociado a la inscripción>’;
$removeInscription->input = $oneClickRemoveInscriptionInput;
$removeInscriptionResponse = $oneClickService->removeInscription($removeInscription);
$soapValidation->getValidationResult(); //Esto valida si el mensaje está firmado por Transbank
$oneClickRemoveInscriptionOutput = $removeInscriptionResponse->return;
$result = $oneClickRemoveInscriptionOutput->result;

13 APPENDIXES
Operation nullify (annuls an already authorized payment)

$nullify = new nullify();
$nullifyResponse = new nullifyResponse();
$oneClickNullificationInput = new wsOneClickMulticodeNullificationInput();
$oneClickNullificationOutput = new wsOneClickMulticodeNullificationOutput();
$oneClickNullificationInput->commerceId = ‘<identificador de comercio que devuelve el servicio authorize>’;

$oneClickNullificationInput->buyOrder = ‘<orden de compra que devuelve el servicio authorize>’;
$oneClickNullificationInput->authorizedAmount = ‘<monto que devuelve el servicio authorize>’;
$oneClickNullificationInput->authorizationCode = ‘<código de autorización que devuelve el servicio authorize>’;
$oneClickNullificationInput->nullifyAmount = ‘<monto a anular de la compra>’;
$nullify->input = $oneClickNullificationInput;
$nullifyResponse = $oneClickService->nullify($nullify);
$oneClickNullificationOutput = $nullifyResponse->return;
$token = $oneClickNullificationOutput->token;
$authorizationCode = $oneClickNullificationOutput->authorizationCode;
$authorizationDate = $oneClickNullificationOutput->authorizationDate;
$buyOrder = $oneClickNullificationOutput->buyOrder;
$commerceId = $oneClickNullificationOutput->commerceId;
$balance = $oneClickNullificationOutput->balance;
$nullifiedAmount = $oneClickNullificationOutput->nullifiedAmount;

13 APPENDIXES
Operation reverseNullification (it reverses the annulment)

$reverseNullification = new reverseNullification();
$reverseNullificationResponse = new reverseNullificationResponse();
$oneClickReverseNullificationInput = new wsOneClickMulticodeReverseNullificationInput();
$oneClickReverseNullificationOutput = new wsOneClickMulticodeReverseNullificationOutput();
$oneClickReverseNullificationInput->commerceId = ‘<identificador de comercio de compra anulada>’;

$oneClickReverseNullificationInput->buyOrder = ‘<orden de compra anulada>’;
$oneClickReverseNullificationInput->nullifyAmount = ‘<monto de la compra anulado>’;
$reverseNullification->input = $oneClickReverseNullificationInput;
$reverseNullificationResponse =
$oneClickService->reverseNullification($reverseNullification);
$oneClickReverseNullificationOutput = $reverseNullificationResponse->return;
$reverseCode = $oneClickReverseNullificationOutput->reverseCode;
$reversed = $oneClickReverseNullificationOutput->reversed;

Manual Webpay en Ingles

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Manual Webpay en Ingles

Загружено:

Авторское право:

Доступные форматы

WEBPAY API

5 2.1 About this handbook

6 3.1 Introduction to Webpay

5 WEBPAY API SOAP 11

11 5.1 API SOAP Security Aspects

6 INTEGRATION, INTEGRATION VALIDATION AND GO-LIVE TRANSITION 12

12 6.1 Webpay integration stages

7 NORMAL AUTHORIZATION TRANSACTION 14

14 7.1 Description of Normal Authorization Transaction

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 2

19 7.5.1 initTransaction operation

8 NORMAL MALL AUTHORIZATION TRANSACTION 23

23 8.1 Description of Normal Mall Authorization Transaction

32 9.1 Description of OneClick Transaction

32 9.2 Summary of Web service methods

34 9.5 Oneclick Payment Transaction

35 9.7 Detailed definition of Web Service methods

10 MALL ONECLICK TRANSACTION 37

37 10.1 Description of the Transaction

38 10.3 Mall Oneclick Registration

40 10.4 Eliminating user registration record

41 10.6 Reversal of authorized payments

42 10.8 Annulment reversal

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 3

45 10.1 Description of deferred capture

47 11.1 Description of nullifying

47 11.2 Description of the Web Service method of transaction nullifying

49 13.1 Apendix A: Webpay environments and key creation

51 12.2.1 Transition page requirements

55 13.4 Appendix D: Validation tests carried out by Transbank

55 12.4.1 Validation tests for Normal Transaction, plugin mode

57 13.6 Appendix F: Examples of integration with Webpay API SOAP

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 4

DATE VERSION CHANGE DESCRIPTION

2.1 About this handbook 2.2 Audience

2.3 Feedback about this documentation

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 5

Seller Webpay Authentication Seller Webpay Seller

Webpay’s most relevant attributes include:

• It protects the seller from possible frauds or unacknoledged • Digital signature.

3.2 Webpay transaction types

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 6

Mechanism for making delayed capture:

• Through Transbank website www.transbank.cl

The kinds of payment supported by this modality are the following:

3.4 Nullifying transactions reversed the client must be refunded in cash.

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 7

Use of digital certificates is recommended, as well as avoid

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 8

interest for the cardholder.

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 9

4.1 Communication Webpay presents an API and it is the sellers’ responsibility to

4.2 Security 4.3.2 Plugins and SDK update

Webpay plugins and SDK distributed by Transbank are already

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 10

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

SSL Country Name (2 letter code) []:CL

openssl x509 -req -days 1460 -in 597029124456.csr

The seller must send the public certificate (597029124456.

API REFERENCE SOAP WEBPAY TRANSBANK S.A. SPECIFICATIONS HANDBOOK (V 1.0) 11

6 INTEGRATION, INTEGRATION VALIDATION AND GO-LIVE TRANSITION

6.1.1.1 Credentials Result APPROVED REJECTED