Integrated Komerci Developer Manual
Jun 18, 2020
Integrated Komerci
Developer Manual
1 Presentation 4
2 Accreditation 5
3 Configurations_______________________________________ 5
4 Komerci technical support 6
5 Komerci Transaction Flow 8
6 Authorization in one step 9 6.1
6.2
Virtual Store>Rede 9
Rede>Virtual Store 14
7 Confirmation 16
7.1
7.2
Virtual Store >Rede 16
Rede>Virtual Store 22
8 Coupon 24
8.1 Virtual Store >Rede 24
9 Sales receipt 27
10 Sales Management 28
11 Appendix A - Banners 29
CO
NT
EN
TS
12 Appendix B – Instructions for installation
of the Verification Code 30
13 Appendix C– Source Code Model 33
14 Appendix D – Capture Screens 34
15 Appendix E – Table of Codes and Return Messages 37
16 Appendix F – Security Tips 38
17Appendix G – Test in the Virtual Store 40
18 Appendix H - Confirmation/Undoing/ Cancelling Pre-Authorization Confirmation/ Komerci Transaction Report 41
19 Appendix I - Reasons for the Error Messages 46
CO
NT
EN
TS
S
4 Integrated Komerci Developer Manual
Contents
1 Presentation Congratulations! By purchasing Komerci, you have chosen to have more
amenities and technology for your sales.
And for you to make the most of all the advantages that the service offers,
we have developed this manual which will assist you in the development
and configuration of your access, as well as with the use of all the resources
and amenities offered by this technology.
Important:
• The merchant should develop its own routine for using Komerci in its virtual store, but always follow the standards defined in this manual.
• Even if you are familiar with the previous versions of Komerci, reading this manual is mandatory.
5 Integrated Komerci Developer Manual
Contents
2 Accreditation
For implementation of the Integrated and WebService Komerci solution in
your company, you need prior accreditation from Rede.
Mastercard SecureCode and Verified By Visa must be previously contracted
in order for you to be enabled.
To do this, simply contact the Customer Service Center on the following
numbers:
4001 4433 (capitals and metropolitan areas)
0800 728 4433(other locations)
Available 24 hours a day, 7 days a week, with bilingual experts trained to quickly and efficiently attend to international requests.
3 Configurations
Mandatory digital certificate:
2048-bit SSL Security Certificate (encryption)
The selection and negotiation with the certifying company is the entire
responsibility of the merchant. Rede has no relationship with the companies
approved for issuing digital certificates.
6 Integrated Komerci Developer Manual
Contents
4 Technical support If you have any problems with the procedures described below, please contact our
technical support. They are available to answer questions and help you with any
difficulty.
Before contacting:
• Please have your membership number (merchant) at hand. If you are a developer, inform the company’s CNPJ (business
taxpayer number);
• Make sure you have completely read the manual (s) and that the
development is in accordance;
• Komerci technical support is not authorized to provide or receive
credit card numbers, whether valid or not, even for testing;
• Komerci technical support is not authorized to supply, receive, or
provide support for the source code or programming languages of the merchant;
• Komerci technical support is not enabled to provide commercial information.
Questions relating to the development of Komerci should be clarified
with our Komerci Technical Support.
7 Integrated Komerci Developer Manual
Contents
Customer Service telephone numbers:
4001 4433 (capitals and metropolitan areas)
0800 728 4433 (other locations)
Available 24 hours a day, 7 days a week, with bilingual experts trained to quickly and efficiently attend to international requests.
Email: [email protected]
Remember:
On the Rede website you can access many services, such as On-line
Statement, 48h Services (Debit and Credit Searches) and Sales
Cancellations.
Access www.userede.com.br
8 Integrated Komerci Developer Manual
Contents
5 Komerci Transaction Flow Available 24 hours a day, 7 days a week, with bilingual experts trained to quickly and efficiently attend to international requests.
PRODUCT
SHOPPING CART
PAYMENT METHOD
SALES RECEIPT
9 Integrated Komerci Developer Manual
Contents
6 Authorization
6.1 Virtual Store>Rede
The virtual store shall send the following parameters to Rede, beginning with the communication with Komerci’s capture screen:
Name Size Description
TOTAL 15 Total amount for the purchase
TRANSACAO 3 Code for the transaction type
PARCELAS 2 Number of installments
FILIACAO 25 Merchant’s membership number(supplier)
DISTRIBUIDOR 9 Merchant’s membership number (distributor)
BANDEIRA 10 Card logo
NUMPEDIDO 16 Order number
CODVER 32 Verification Code
URLBACK 250 Address for return of the transaction data
URLCIMA 250 URL address of the page or upper image
TARGET 40 Frame name to which the URLBACK will be returned
INIFRAME 1 Indicates if the Komerci screen will be presented as an IFRAME
LANGUAGE 3 Language for presentation of the texts
All parameters mentioned in this step of the flow must be sent, using the POST method,to:
https://ecommerce.userede.com.br/pos_virtual/form_card.asp
If the Komerci screen is exhibited as an iframe, it will be necessary to use the parameter
INIFRAME=“S”. Otherwise, problems may occur in the operation of Komerci.
Do not use frames in communicating with the site
https://ecommerce.userede.com.br/pos_virtual. This practice will cause interference in the
functioning of the pages for certain browser configurations/versions.
Komerci offers the option to display the“banner” of the stores, see page 10 of this manual (Use of URLCIMA parameter), or contact our technical support.
Contents
10 Integrated Komerci Developer Manual
TOTAL
The “TOTAL” parameter should contain the total amount for the transaction.
The TOTAL parameter must be sent at all stages and always in the same format.
TRANSACAO
The “TRANSACAO” parameter shall contain the code for the transaction type to be
processed, in accordance with the following table:
Transaction type Code
One whole payment 04
Issuer Installments 06
Merchant Installments 08
Pre-authorization 73
One whole IATA payment 39
IATA Installments 40
In the case of Pre-authorization, the “TRANSACAO” parameter shall contain the code “73”. This code is unique for whole payment or installment transactions. The choice of payment method (whole payment or in installments) is made upon confirmation of the transaction (see the page https://ecommerce.userede.com.br/pos_virtual/confirma.asp:).
It is not possible to effect transactions in installments for cards issued outside of
Brazil. This is a rule of the foreign issuers.
This amount must be separated by a “.” (point); for example: 34.60.
It must not contain a separator for thousands.
It is mandatory to have two decimal places.
11 Integrated Komerci Developer Manual
Contents
Code “73” refers only to the authorization order request; only in the
confirmation step of the Pre-Authorization is it necessary to inform whether
the transaction will be in one payment or in installments. If the option is for installments, the number of installments must be informed.
PARCELAS
The “PARCELAS” parameter shall contain the no. of installments for the transaction. It should be filled in with the value “00”(zero zero) when the “TRANSACAO” parameter is “04” or “39”; that is, one whole payment.
FILIACAO
The “FILIACAO” parameter shall contain the membership no. of
the merchant registered with Rede.
DISTRIBUIDOR
The “DISTRIBUIDOR” parameter shall contain the membership
no. of the distributing merchant. This parameter shall only be filled in if the merchant of the “FILIACAO” field is a supplier. If
not, send this parameter but leave it blank.
BANDEIRA
The “BANDEIRA” parameter shall contain the payment method requested by the user, in uppercase. The options offered by Komerci are:
Logo Value that must be informed
Mastercard MASTERCARD
Diners DINERS
Visa VISA
Hiper HIPER
Hipercard HIPERCARD
12 Integrated Komerci Developer Manual
Contents
NUMPEDIDO
The “NUMPEDIDO” parameter shall contain the order no. relating to the product/service requested by the user. This field shall be filled in in accordance with the internal policy of the virtual store.
Rede’s system does not validate this parameter.
CODVER
The "CODVER" parameter shall contain the verification code generated by the "CodVer.class" application. The instructions for the installation of the code are described in "Appendix B — Instructions for Installation of the
Verification Code".
URLCIMA
The "URLCIMA" parameter must contain the address of the URL (in HTTPS) of the page or image to be loaded in the upper area of the Komerci screen. More
configuration information about the "URLCIMA" parameter is available in
"Appendix A - Banners".
URLBACK
The“URLBACK” parameter shall contain the address and page where the
transaction data must be returned.
Do not exceed the 250 positions permitted. Do not use symbols, punctuation marks, or special characters such as (“!’@#&*^/?).
As an increased security feature, the virtual store may register a URLBACK beforehand via the Redecard website (www.userede.com.br).Through this pre-registration, it will be possible to suppress sending the URLBACK parameter, because Komerci will always return transaction data to the address that was registered on the website.
13 Integrated Komerci Developer Manual
Contents
TARGET
The “TARGET” parameter is optional. It may contain the name of the iframe where Rede will return the URLBACK. If this parameter is not sent, Rede will return the URLBACK to the top target (target=“_top”).
Initially, this parameter will only be submitted for transactions with the
MasterCard and Visa logo.
INIFRAME
The “INIFRAME” parameter is optional. If it is necessary to exhibit the Komerci
screens in an IFRAME, this shall be sent with the value set to “S”.
LANGUAGE (Optional Parameter)
The “LANGUAGE” parameter shall contain the value relating to the language with
which you wish to exhibit the texts of the Komerci screen.
Language Code
English ENG
Portuguese POR
It is recommended to open the Komerci capture screen on the virtual store’s own page, in order to avoid problems arising from the cardholders using pop-up blocking programs. Another solution to avoid problems with these programs is to display a warning before or during the transaction, informing your clients about the need to disable or uninstall the pop-up blocking programs that they may have.
14 Integrated Komerci Developer Manual
Contents
6.2 Rede>Virtual Store1
Approved Transaction
If the transaction is approved and successful, Rede will return the following parameters to the
virtual shop, in GET method, through your URLBACK (previously registered or provided as a
parameter):
Name Size Description
DATA 8 Date of the transaction
NUMPEDIDO 16 Order Number
NR_CARTAO 19 Masked card number
ORIGEM_BIN 3 Nationality Code of the Issuer
NUMAUTOR 6 Authorization Number
NUMCV 12 Sales Receipt Number (NSU)
NUMAUTENT 6 Authentication Number
NUMSQN 12 Unique sequential number
PAX1 26 Airline Company Name of the Main Passenger Other Fields Text free for typing.
DATA_EXPI 8 Expiration Date of the Transaction
1 It is the full responsibility of the virtual store to deal with any information returned by Rede.
DATA
The “DATA” parameter will return the date on which the transaction was
performed (in the format yyyymmdd).
NUMPEDIDO
The “NUMPEDIDO” parameter will return the order no. that was informed by
the virtual store in the first stage of the flow.
15 Integrated Komerci Developer Manual
Contents
NR_CARTAO
The “NR_CARTAO” parameter will return the card number validated by the issuer, in a masked format, leaving visible only the first 6 and last 4 digits of the number; the additional numbers will be masked.
ORIGEM_BIN
The "ORIGEM_BIN" parameter will return the nationality code of the validated card issuer. The merchant may choose to reject transactions from foreign issuers (issued outside Brazil) by changing this parameter. In the case of Mastercard, Diners, Hipercard, and Hiper, this parameter is returned with the three-character standard to designate the issuing country (e.g., BRA for Brazil). In the case of Visa, this parameter is returned with the two-character standard to designate the issuing country (e.g., BR for Brazil).
NUMAUTOR
The "NUMAUTOR" parameter will return the authorization no. of the transaction.
NUMCV
The "NUMCV" parameter will return the sales receipt no. for the transaction
NUMAUTENT
The "NUMAUTENT" parameter will return the authentication no. for the transaction.
16 Integrated Komerci Developer Manual
Contents
NUMSQN
The "NUMSQN" parameter will return the unique sequential number
for the transaction.
PAX1
The "PAX1" parameter will return the same value as the "PAX1", which was
informed by the virtual store in the first step of the flow.
DATA_EXPI
The "DATA_EXPI" parameter will return the expiration date of the
Pre-Authorization transaction (in the format: yyyymmdd). This field will only
be returned for pre-authorization transactions (TRANSACTION = 73).
7 Confirmation
7.1 Virtual Store>Rede
If the transaction has been approved by the issuer, the virtual store shall confirm it, returning the parameters below to the address: https://ecommerce.userede.com.br/pos_virtual/confirma.asp:
If the merchant uses pre-authorization transactions, the confirmation of this transaction shall be done by the date contained in the "DATA_EXPI" parameter. After this date, the transaction will be discarded and another transaction will have to be done in order for its confirmation to take effect.
17 Integrated Komerci Developer Manual
Contents
The confirmation step must only occur when the previous step
(Authorization) shows no error return and has returned the authorization
data such as: NUMCV, NUMAUTOR, and NUMSQN. In other words, this step
must only be performed if the transaction had a positive return.
This data traffic should not occur via the user’s browser or through the user’s
interference; that is, the webserver of the virtual store shall communicate
directly with the Rede environment.
One can, for example, use components that allow Server to Server
communication via HTTPS protocol. This procedure ensures the security of
the data traffic between Rede and your virtual store.
Name Size Description
DATA 8 Date of the transaction
TRANSACAO 3 Code of the confirmation transaction
TRANSORIG 3 Code for the original transaction type
PARCELAS 2 Number of installments for the transaction
FILIACAO 25 Membership of the merchant (supplier)
DISTRIBUIDOR 9 Membership of the merchant (distributor)
TOTAL 15 Amount for the transaction
NUMPEDIDO 16 Order number
NUMAUTOR 6 Authorization number
NUMCV 12 Sales Receipt Number
NUMSQN 12 Unique sequential number
NUMDOC1 16 Ticket no.
PAX1 26 Passenger Name
NUMDOC2 16 Ticket no.
PAX2 26 Passenger Name
NUMDOC3 16 Ticket no.
PAX3 26 Passenger Name
NUMDOC4 16 Ticket no.
PAX4 26 Passenger Name
IATA 8 IATA code number
TAXAEMBARQUE 12 Boarding fee of the transaction
18 Integrated Komerci Developer Manual
Contents
DATA
The "DATA" parameter shall contain the date on which the
transaction was performed (in yyyymmdd format).
TRANSACAO
The "TRANSAÇÃO" parameter shall contain the confirmation code of the
transaction: 203.
TRANSORIG
The "TRANSORIG" parameter shall contain the code for the type of
transaction that was informed by the virtual store in the "TRANSAÇÃO"
field in the first step of the flow.
PARCELAS
The "PARCELAS" parameter shall contain the no. of installments for the
transaction, which was informed by the virtual store in the "PARCELAS"
field in the first step of the flow.
FILIACAO
The "FILIAÇÃO" parameter shall contain the merchant’s membership number (registered with Rede), which was informed by the virtual store in the "FILIAÇÃO" field in the first step of the flow.
Cards issued abroad cannot be used for transactions involving installments; this is a decision of the international issuers.
19 Integrated Komerci Developer Manual
Contents
DISTRIBUIDOR
The "DISTRIBUIDOR" parameter shall contain the membership number of
the distributing merchant, which was informed by the virtual store in the
"DISTRIBUIDOR" field in the first step of the flow. This parameter shall only
be filled in if the merchant in the "FILIAÇÃO" field is a supplier. If not, send
this parameter, but leave it blank.
TOTAL
The "TOTAL" parameter shall contain the amount for the transaction
which
was informed by the virtual store in the "TOTAL" field, in the first step of
the flow. "This amount shall be separated by a "." (point); for example:
34.60. It is mandatory to have two decimal places; that is, in the same
way it was sent in step 1. It should not contain a separator for
thousands.
NUMPEDIDO
The "NUMPEDIDO" parameter must contain the no. for the order which was
authorized and returned by Rede in the "NUMPEDIDO" field in the second
step of the flow.
NUMAUTOR
The "NUMAUTOR" parameter shall contain exactly the same authorization
no. of the transaction which was returned by Rede in the "NUMAUTOR"
field in the second step of the flow. For example: If no. 012345 was
returned, the virtual store shall send no. 012345 and not 12345 (the
virtual store must not remove the zero value "0"). Cases may occur in
which letters appear in this parameter; therefore, you must also return
the exact information that was sent. For example, if there are uppercase
letters, you cannot submit lowercase, because it will not be confirmed.
For example, if T12345 is informed, the virtual store must submit T12345
20 Integrated Komerci Developer Manual
Contents
and not t12345.
20 Integrated Komerci Developer Manual
Contents
NUMCV
The "NUMCV" parameter shall contain the sales receipt no. for the
transaction, which was informed by Rede in the "NUMCV" field in the
second step of the flow.
NUMSQN
The "NUMSQN" parameter shall contain the unique sequential no. of the transaction, which was informed by Rede in the "NUMSQN"
field in the second step of the flow.
PAX1
Filling in the "PAX1" parameter is optional for activities that are not in the airline segment. In this case, this field can be freely used for the inclusion of additional data. If the order number exceeds the 16 positions allowed for NUMPEDIDO, the other positions may be included in PAX1. In the case of Airline Companies, the PAX1 parameter is mandatory and must contain the name of the main passenger.
PAX2,PAX3, AND PAX4
These parameters are only sent when the transaction to be confirmed is for an Airline Company. The filling in of the "PAX2", "PAX3", and "PAX4" parameters is optional. They can be used to record the name of the passengers, corresponding to the ticket numbers informed in the "NUMDOC" parameters.
21 Integrated Komerci Developer Manual
Contents
NUMDOC1,NUMDOC2,NUMDOC3,
NUMDOC4
These parameters are sent only when the transaction is for an Airline Company. The filling in of the "NUMDOC2", "NUMDOC3", and "NUMDOC4"
parameters is optional.
They can be used to record the ticket numbers for the airline tickets
purchased.
IATA
This parameter is sent only when the transaction to be confirmed involves an
Airline Company. The "IATA" parameter shall contain the IATA code of the
supplying merchant. The filling in of this parameter is optional. The IATA code is a
registration of the airline company supplied by the International Air Transport
Association (IATA). These data are neither stored nor validated by Rede, only
transmitted at the time of the transaction.
TAXAEMBARQUE
This parameter is sent only when the transaction to be confirmed involves an
Airline Company. The "TAXAEMBARQUE" parameter shall contain the amount
for the boarding tax of the transaction, which was informed by the virtual store
in the first step of the flow.
The only exception is for “NUMDOC1”, which is a mandatory parameter in the
case of Airline Companies.
22 Integrated Komerci Developer Manual
Contents
7.2 Rede>Virtual Store
If the transaction is approved and successful, Rede will return
the following parameters to the virtual store, via GET method, through
the URLBACK (previously registered or provided as a parameter):
Name Size Description
CODRET 4 Return code
MSGRET 1024 Return message
CODRET
The “CODRET” parameter will return the transaction’s return code.
MSGRET
The “MSGRET” parameter will return the message for the transaction
relating to the "CODRET" return code. If confirmation of the transaction is
successful, this parameter will return the Sales Receipt to the cardholder.
ATTENTION
If the virtual store decides, for any reason, to not confirm the transaction, all the
merchant has to do is not execute this confirmation step of the transaction flow. In this case, the transaction is automatically undone.
After the transaction authorization and the return of the data to the URLBACK, the
virtual store will have two (2) minutes to make the confirmation. If the transaction is not confirmed within this time, it will automatically be undone.
The confirmation data must be sent via the GET method, in a HTTPS connection.
23 Integrated Komerci Developer Manual
Contents
CODES AND RETURN MESSAGES:
The "MSGRET" parameter returns the message of the transaction relating to the
return code "CODRET". If confirmation of the transaction is successful, this parameter
will return the Sales Receipt to the cardholder.
0= “CONFIRMAÇÃO COM SUCESSO” > Confirmation was successful
and effective;
1=“JA CONFIRMADA” > The transaction was confirmed earlier;
2=“TRANSAÇÃO NEGADA” > The confirmation transaction was denied
by the authorizer;
3=“TRANSAÇÃO DESFEITA” > The transaction was undone because the time
available (two minutes) for confirmation was exceeded;
4=“TRANSAÇÃO ESTORNADA” > The transaction was cancelled earlier by the transaction chargeback process;
8 =“DADOS NÃO COINCIDEM” > Data for Total, Receipt Number or Authorization Number do not match the Receipt and Authorization numbers given as a parameter;
These parameters are returned after the communication to confirm the transaction. No command or HTML code is returned. Only a single line of text is returned. For example: “CODRET=0&MSGRET=CONFIRMAÇÃO+COM+SUCESSO". Thus, the treatment of the return will be done through another component, such as a service, servlet, or another programmed routine.
24 Integrated Komerci Developer Manual
Contents
9=“TRANSAÇÃO NÃO ENCONTRADA” > No transaction was found for the corresponding fields given as parameters: NUMCV, NUMAUTOR, and DATA;
88= “DADOS AUSENTES. TRANSAÇÃO NAO PODE SER CONCLUÍDA” > Some mandatory data were not informed as a parameter (DATA, TRANSACAO, TRANSORIG, PARCELAS, TOTAL, NUMPEDIDO, NUMAUTOR, NUMCV, NUMSQN and FILIACAO)
8 Coupon
8.1 Virtual Store>Rede
Upon duly confirming the transaction, the virtual store shall display the sales receipt, sending the following parameters (GET or POST) filled in at the URL:https://ecommerce.userede.com.br/pos_virtual/cupom.asp
The virtual store shall deal with each of the return messages and inform the
cardholder, depending on the situation.
If no data is returned, the merchant shall send the confirmation again (repeat the third step of the flow).
It is recommended that, at the end of this stage, the virtual store return the following to the user: the order number, as well as the data necessary for the
cardholder to accompany the purchase.
25 Integrated Komerci Developer Manual
Contents
Name Size Description
DATA 8 Date of the transaction
TRANSACAO 3 Code 201
NUMAUTOR 6 Authorization number
NUMCV 12 Sales Receipt Number
LANGUAGE 1 Language for the Sales Receipt
DATA
The “DATA” parameter shall contain the date on which the transaction was performed (in the format yyyymmdd), informed by Rede in the "DATA" field in the second step of the flow.
TRANSACAO
The “TRANSACAO” parameter shall contain the exhibition code of the
coupon:201.
NUMAUTOR
The “NUMAUTOR” parameter shall contain exactly the same transaction
authorization no. that was returned by Rede in the "NUMAUTOR" field in
the second step of the flow. For example: if no. 012345 was returned, the virtual store shall send no. 012345, not 12345 (i.e., not suppressing the
zero "0" value). Cases in which letters appear in this parameter may occur.
In this case, if an authorization is informed as T12345, the virtual store shall send T12345 and not t12345.
NUMCV
The "NUMCV" parameter shall contain the sales receipt no. for the
transaction, which was informed by Rede in the "NUMCV" field in
the second step of the flow.
26 Integrated Komerci Developer Manual
Contents
Despite this being a step that is independent of the flow, it is the obligation of the virtual store to display the sales receipt, preferably in a new window, in such a way that the buyer can print the data The exception to this is for the type of transaction = 73, because this deals with a Pre-Authorization order; however, it is the responsibility of the virtual store to inform the customer, through a message, if the transaction in the Pre-Authorization mode has been approved or not. In this case, the Sales Receipt may be presented in the CONFIRMATION STEP of the Pre-Authorization. The display of the sales receipt can occur more than once, but only the purchaser can view it. If the display of the sales receipt is requested for an unconfirmed or unapproved transaction, an error message will appear. The sales receipt is only shown for approved transactions.
LANGUAGE
The “LANGUAGE” parameter shall contain the code corresponding to the
language used in the first step of the transaction flow, in which:
Code Form of Capture
E English
When the language is “Portuguese”, this parameter must be left blank.
IMPORTANT: carefully read the items below.
Contents
27 Integrated Komerci Developer Manual
9 Sales receipt
The sales receipts (illustrated below) will be displayed in accordance with
the request that the virtual store makes in the “BANDEIRA” parameter, in
the first step of the flow:
MASTERCARD VISA
DINERS
HIPERCARD HIPER
Attention: To display the sales receipt in this same format (illustrated), configure t he pop-up to 280X440 pixels.
Contents
28 Integrated Komerci Developer Manual
10 Sales Management
Komerci has a number of features for managing transactions processed by MASTERCARD, DINERS, VISA, HIPERCARD, and HIPER. For example:
Chargeback of transactions: Chargeback allows the merchant to cancel online transactions that were conducted through the Integrated Komerci. This service is only available for transactions done on the same day of the sale (until 23:59 Brasilia time).
Sales Summary: The Sales Summary is a document that displays the daily total of all the confirmed transactions. It is available in the system for 5 days, in a way that if it is not extracted during this period, you can no longer view it. Therefore, we recommend that it be extracted on a daily basis.
Transaction Report: The Transaction Report is a tool that makes the consultation of all the data relevant to the transactions effected through any type of Komerci, available for 15 days, beginning from the date of requesting the report.
Manuals:
This function stores the latest version of the operating manuals of the Integrated and Webservice Komerci, in Portuguese and English, as well as the Codver for download. These features are available on the Rede website. To use the Rede website, all the merchant has to do is register at www.userede.com.br, with its Komerci membership details.
Contents
30 Integrated Komerci Developer Manual
11 Appendix A - Banners
Contents
31 Integrated Komerci Developer Manual
Below are some restrictions for using this parameter:
12 Appendix B - Instructions for installation of the Verification Code
The virtual store will be responsible for programming a routine (in the language you want) to communicate with the Java utility (CodVer.class) that generates the Verification Code, but which follows the instructions set forth herein.
Prerequisite of the Merchant’s Server:
Java interpreter (e.g., JDK) version 1.1.8 (minimum) installed.
Do not exceed the 250 positions permitted. Do not use symbols, punctuation marks, or special characters such as (“!’@&*^?).
If the merchant fails to send these parameters, or sends them blank, the system will load the default color of the capture screen.
The size of the area that the "URLCIMA" parameter covers is fixed at 120 X
780 pixels. This parameter is available for cards with the MasterCard logo as well as for cards with the Diners, Visa, Hipercard, and Hiper logo.
32 Integrated Komerci Developer Manual
Contents
Syntax for communicating with the Java utility:
#javaCodVer<numfil><total><ipaddress>
Where:
<numfil>: Merchant’s membership number;
<total>:Total amount for the purchase (format ###.##) with up to 12 characters;
<ip address>:IP address of the PURCHASER’S machine;
Examples:
#java CodVer 000098756 20.75200.21.32.64
332705431571-768
#java CodVer 000056734 120.50 125.32.76.109
218937362874-605
The output can be directed to a file:
#java CodVer 000043201 35.50 32.147.125.76 > codver.out
The contents of this file will be:
647398373692-762
Once the correct arguments are provided, the Verification Code will be returned.
If just the following is entered:
# java CodVer
Without any parameters, a small “help” message will be displayed.
SUGGESTION FOR VIRTUAL STORES THAT OPERATE WITH ASP
The virtual store will be responsible for programming a routine (in the language you want) to communicate with the Java utility (CodVer.class) that generates the Verification Code, but which follows the instructions set forth herein. Rede makes the "Verification Code" file available for download, in order to assist the developer integrating his virtual store with the Rede environment.
33 Integrated Komerci Developer Manual
Contents
This file contains:
ASP page integrator; ActiveX component for generating the verification code; Files for supporting the functioning of the component; Source code of the component; Detailed instructions;
The “Verification Code” file is available for download on the
Rede website (www.userede.com.br), via the links “VANTAGENS PARA
CLIENTES”>“Downloads”> Once in it, select Komerci and download the codver.
Any code provided is just a suggestion for development — the developer of the virtual store is responsible for tailoring it to his environment.
See the "Technical Support" topic for more information.
34 Integrated Komerci Developer Manual
Contents
13 Appendix C - Source Code Model
This is a source code model that the online store may use to communicate with the Komerci screen capture:
<HTML>
<HEAD>
<TITLE> Esta é a sua página de compras </TITLE>
<METAname=”description” content=””>
<METAname=”keywords”content=””>
<METAname=”generator”content=”XXXXHTML”>
<Scriptlanguage=”JavaScript”>
<!--
function Janela()
{
vpos=window.open(‘’,’vpos’,’toolbar=no,location=no,directories=no,status =no,menubar=no,scro llbars=auto,resizable=no,copyhistory=no,width=780,height=460’); document.form_card.submit();
}
//-->
</Script>
</HEAD> <BODY BGCOLOR=”#FFFFFF”TEXT=”#000000”LINK=”#000000”
VLINK=”#000000”>
<Center> <P><fontface=”Arial”color=”navy”size=”4”> Nesta página estará a tabela com as mercadorias,
custos, qtdes, frete, qtde parcelas, etc...</font></P>
<P> </P>
<P> </P>
<P><font face=”Arial”color=”BB0000”size=”4”><ahref=”JavaScript:Janela
();”>Comprar</A></
font></P>
35 Integrated Komerci Developer Manual
Contents
<formname=”form_card”method=”POST”target=”vpos”
action=”https://ecommerce.userede.com.br/pos_virtual/form_card.asp”>
<inputtype=”hidden”name=”TOTAL”value=”17.50”>
<inputtype=”hidden”name=”TRANSACAO”value=”04”>
<inputtype=”hidden”name=”PARCELAS”value=”00”>
<inputtype=”hidden”name=”FILIACAO”value=”000012345”>
<inputtype=”hidden”name=”DISTRIBUIDOR”value=”999999999”>
<inputtype=”hidden”name=”BANDEIRA”value=”MASTERCARD”>
<inputtype=”hidden”name=”NUMPEDIDO”value=”123456”>
<inputtype=”hidden”name=”PAX1”value=”XXXXXXX”>
<inputtype=”hidden”name=”CODVER”value=”XXXXXXXXXXXXXXXX-
XXX”>
<inputtype=”hidden”name=”URLBACK”value=”https://www.loja.com.br/c
gi-bin/retorna.cgi”>
<inputtype=”hidden”name=”URLCIMA”value=”https://www.loja.com.br/i
magem_cima.jpg”>
<inputtype=”hidden”name=”TARGET”value=”_nometarget”>
<center>
<inputtype= “submit”name= “enviar”value=“Prosseguir”>
</center></form>
</center>
</BODY>
</HTML>x
14 Appendix D - Capture Screens
The payment interfaces will be displayed according to the request that the virtual store makes in the "BANDEIRA" parameter, as per the following diagram:
Contents
35 Integrated Komerci Developer Manual
ManualdoDesenvolvedorKomerciIntegrado
MASTERCARD
VISA
The “Cardholder Name” is the only parameter of the capture screen
that is not validated together with the card issuer, for any of the logos.
This data is recorded in the merchant’s Transaction Report, in
accordance with the typing done by the purchaser on the Komerci
capture screen.
Contents
36 Integrated Komerci Developer Manual
DINERS
HIPERCARD
Contents
37 Integrated Komerci Developer Manual
HIPER
15 Appendix E - Table of Codes and Return Messages
Code Message
0 Transaction Approved
50,52,54,55,57,59,61,62,64, 66,67,68,70,71,73,75,78,79, 80,82,83,84,85,87,89,90,91 93,94,95,97,99
Transaction not authorized
51,92,98 Invalid Merchant
Please contact the merchant performing the sale.
53 Invalid Transaction
Please contact the merchant performing the sale.
(continued)
38 Integrated Komerci Developer Manual
Contents
Code Message
76,86 Redo the transaction
Your transaction cannot be completed. Please redo the transaction, mandatory data missing.
58,63,65,69,72,77,96 Problems with the card
Please check the data on your card. If the error persists, contact your card’s customer service center.
56,60 Invalid Data
Please contact the merchant that is performing the sale.
74 Institution without communication
16 Appendix F - Security Tips
These are examples of html source that may be generated by the developer
to ensure greater security in the electronic transactions of the virtual store.
The following excerpt contains a Javascript routine to disable the right
mouse button.
For more details about the possible causes of the errors described above, see
“Appendix I– Reasons for the Error Messages”.
39 Integrated Komerci Developer Manual
Contents
<script language =“Javascript”>
Functionright(e) {
If (navigator.appName==‘Netscape’&&
(e.which==3||e.which==2))
Return false; Else if (navigator.appName==‘MicrosoftInternetExplorer’&&
(event.button==2||event.button==3)){
Alert(“REDECARD ONLINE”);
Returnfalse;
}} Document.onmousedown=right;
Document.onmouseup=right;
if(document.layers)window.captureEvents(Event.MOUSEDOWN);
if(document.layers)window.captureEvents(Event.MOUSEUP);
Window.onmousedown=right;
Window.onmouseup=right;
</script>
The following excerpt contains a Javascript routine to disable the menu, the
scroll bar and other items on the page.
<Scriptlanguage=”JavaScript”>
<!--
Function Janela()
{
Vpos=window.open(‘’,’vpos’,’toolbar=no,location=no,directories=no,status =no,men ubar=no,scrollbars=auto, Resizable=no,copyhistory=no,width=600,height=460’);
document.form_pos.submit();
}
//-->
</Script>
Contents
40 Integrated Komerci Developer Manual
17 Appendix G - Test in the Virtual Store
To perform the tests in the Integrated Komerci platform before making available in
the virtual store, Rede recommends that the merchant performs transactions in the
production environment, cancelling them on the same day the transaction is
submitted, via the Rede website (www.userede.com.br), using the "CHARGEBACK"
option. In this case, the virtual store must have a valid accreditation no. and a valid
test card.
Another way to test is to make a transaction, in the production environment, with a
valid card, but for the amount of R$ 0.01. The transaction goes to the issuer, receives
the authorization, but does not generate credit for the merchant or a charge for the
Cardholder.
IMPORTANT The procedures that confirm the completion of the purchase by the client, such as the sending of an e-mail, confirmation by phone, monitoring procedures, and internal database queries, are complementary practices that must be performed by the merchant. These procedures can reduce the risk of fraud in commercial transactions conducted via the Internet and are already common practices adopted by most merchants. Also, they are particularly recommended when the purchase price is high.
Contents
41 Integrated Komerci Developer Manual
18 Appendix H - Confirmation / Undoing / Cancelling Pre-Authorization Confirmation / Komerci Transaction Report
The operations for confirmation, undoing, and cancelling pre-authorization
confirmation, are available on: the Rede website, whose URL is
www.userede.com.br; or via the WebService (see the WebServices Manual).
To access it, the user shall activate the "Komerci" menu and then select the desired
option.
ATTENTION • It is important to check the status of the transaction before starting the process of delivering the purchased product or performing the services contracted by the consumers. Only transactions with the "Confirmed" status (see Komerci “Transaction Report” via the Rede website) shall be considered to be successful, unless they have been subsequently canceled. • Always check the consummation of the transaction in the Komerci Transaction Report, before undertaking delivery of the product or service. • "UNDONE" transactions are not billed; that is, they are not credited by Rede. The status of the transaction can be found via the Komerci Transaction Report. • Recommendation of Hosting, developer, or monitoring companies, is not provided by Rede. These companies can be found through search engines. • The final decision to proceed with a sale is the sole responsibility of the virtual store. You must pay particular attention in the comparison of typed information, which may contain errors. The virtual store that uses the Internet as a sales channel shall accept the rules of Direct Marketing and will be subject to the contractual clauses for this type of marketing.
Contents
42 Integrated Komerci Developer Manual
PRE-AUTHORIZATION CONFIRMATION
The illustration below shows the screen for Pre-Authorization Confirmation.
Through this screen, it is possible to confirm a type 73 transaction related to Pre-Authorization. It is possible, in this process, to inform whether the amount will be paid in installments, via the option for payment method. After this
procedure, the pre-authorization transaction and its payment method are
confirmed for billing. The following data shall be entered so that the operation is successful:
• Sales Receipt no.,
• Authorization no.,
• Date on which the transaction was requested,
• Amount for the sale (in Reais),
• Payment method, and
• Installments (if the payment method chosen is
"Merchant Installment”).
Contents
43 Integrated Komerci Developer Manual
CANCEL THE PRE-AUTHORIZATION
The illustration below shows the screen for Cancelling Pre-
Authorization.
Through this screen, it is possible to cancel a pre-authorization (Transaction73). Thus, this pre-authorization transaction is cancelled and will not be billed.
The following data shall be entered so that the operation is successful:
• Sales Receipt no.,
• Authorization no.,
• Date on which the transaction was requested,
• Amount for the sale (in Reais).
Contents
44 Integrated Komerci Developer Manual
CANCELLING THE PRE-AUTHORIZATION
CONFIRMATION
The illustration below shows the screen for Cancelling Pre-Authorization
Confirmation.
After pre-authorization confirmation it is still possible to cancel it via this
screen.
The pre-authorization transaction is cancelled and will not be billed. The following data shall be entered so that the operation is successful:
• Sales Receipt no.,
• Authorization no.,
• Date on which the transaction was requested,
• Amount for the sale (in Reais).
Contents
45 Integrated Komerci Developer Manual
KOMERCI TRANSACTION REPORT
The illustration below shows the screen for the Komerci Transaction Report.
This report allows you to see the transactions made, as well as their status. It is
important to view the report to verify the transactions performed.
The maximum period for searching the reports is fifteen days from the date of
requesting the report. It is not possible to issue this report when the difference
between the end date and the start date is greater than the established
maximum limit of 15 days.
Contents
46 Integrated Komerci Developer Manual
19 Appendix I - Reasons for the
Error Messages
Code0–Transaction Approved:
When the corresponding code is returned, the information for authorization
number, receipt number, and sequence number (used as parameters for
monetary confirmation of the transaction — Step 2) will be sent to the
merchant.
Codes (50,52,54,55,57,59,61,62,64,66,67,68,70,71,73,75,78,
79,80,82,83,84,85,87,89,90,91,93,94,95,97,99) -Transaction not authorized:
The transaction was not authorized and cannot be followed by the Confirmation step.
Codes (76,86) - Redo the Transaction:
Problems occurred during the authorization and it must be sent
again.
Contents
47 Integrated Komerci Developer Manual
Codes (58,63,65,69,72,77,96) - Problems with the card:
Occurs when the card details are incorrect. In order for the card information to be validated, the following conditions must be respected:
• Cards with the Mastercard, Visa, Hipercard, and Hiper logos must be
numeric with 16 positions. • Diners cards must have between 14 and16 positions. The system validates the number of characters that the client enters and
will not accept less than 14 digits or more than 16. There is no automatic filling in with leading zeros, which must be programmed.
• The card numbers must be correct. • The expiration date of the card must be correct, in accordance with
what is informed on the card. • The security code must be correct, in accordance with what is informed
on the card. • This error occurs when some data on the card is incorrect. The response
is from the card issuer. Ask the client to verify that he correctly typed the card data. If the error persists, ask the cardholder to contact the card’s customer service center.
Codes (56,60) – Invalid Data:
Occur in the following cases:
The fields: TOTAL, TRANSACAO, PARCELAS, FILIACAO, NUMPEDIDO,
BANDEIRA are empty or null in the first stage of authorization.
• The TOTAL field is not in the correct format ("Without a separator for thousands and without a decimal separator "."). It must have a decimal
point separator and two decimal places.
• The DISTRIBUIDOR field, if filled in, does not correspond to a numeric field,
or it contains spaces.
Contents
48 Integrated Komerci Developer Manual
• The FILIACAO field is either not numeric, contains spaces, or does
not match a Filiação no. previously registered at Rede.
• The PARCELAS field: does not correspond to a numeric field or
contains spaces
• It has a value greater than "0" when the transaction type is "one whole
payment".
• It has no value above "1" when the transaction is "issuer installments",
"merchant installments" or "IATA installments", codes "06", "08", and "40"
respectively.
• The transaction type is incorrect. See types of valid transactions on page 7.
• The TAXAEMBARQUE field, if informed, does not correspond to a
numeric field with a decimal separator ("."), without a separator point for thousands, or contains spaces.
• The ENTRADA field, if informed, does not correspond to a numeric field
with a decimal separator ("."), without a separator point for thousands,
or contains spaces.