ALIGNET MERCHANT SOLUTION
Virtual POS (V-POS)
Merchant Integration Guide
Technical-functional document that describes
the process of integration of new commerce
through the Virtual Point Of Sale (V-POS) to the
AMS platform
Version 2.4.0
Updated: 19 de July de 2012
© 2008 - 2012 ALIGNET. All Rights reserved.
This document is confidential. The contents and concepts developed in the document cannot be used by natural or
legal entities to whom this information has not been sent explicitly to.
Review History
Date
2005-08-25
2005-09-02
Version
0.1
0.2
2005-09-15
0.8
2005-09-19
0.9
Description
Initial production of the document
Definition of the objectives in the
document
Sequence diagram, several
improvements
Technical specifications
2005-09-19
2005-09-30
2005-11-30
2005-11-30
2005-12-06
2006-03-27
2006-05-30
1.0
1.2
1.3
1.3
1.4
1.5
1.5
Final review
Key generation for the security outline
Update on points 7, 8 , 9
Final review
Update on points 7, 8 and appendixes
Update on points 7, 8 and appendixes
Review and control
2006-06-26
1.5
Payroll modification
2008-06-30
2009-01-20
2010-12-01
2.0.1
2.0.1
2.2.0
2012-07-19
2.4.0
General review
General review
Update definition of
authorizationResult and errorCode
fields. List of error codes
Update of testing URL
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Author
R. Barturen
H. Alosilla
R. Barturén
J. Botta y
D. Cruz
D. Cruz
D. Cruz
R. Barturén
D. Cruz
R. Barturén
R. Barturén
T. J.
Carrasco
T. J.
Carrasco
M. Alcalá
G. Quispe
J. Bautista
J. Bautista
Page 1
Contents
CONTENTS .....................................................................................................2
1. INTRODUCTION .......................................................................................3
1.1. OBJECTIVES .......................................................................................3
1.2. GLOSSARY .........................................................................................3
1.3. PURCHASE FLOW ...............................................................................3
1.4. PURCHASE EXPERIENCE .....................................................................5
2. WHAT IS V-POS? .....................................................................................8
2.1. DESCRIPTION .....................................................................................8
2.2. ARCHITECTURE ..................................................................................8
2.3. REQUEST AND RESPONSE OF THE PAYMENT FLOW ..............................9
3. V-POS INTEGRATION............................................................................10
3.1. V-POS INTEGRATION PROCESS ........................................................10
3.2. ADMINISTRATION OF CRYPTOGRAPHIC KEYS .......................................11
3.3. PAYMENT REQUEST ..........................................................................12
3.4. PAYMENT RESPONSE ..........................................................................1
4. INTEGRATION WITH THE PLUG-IN .......................................................1
5. FREQUENTLY ASKED QUESTIONS ......................................................2
6. ADDITIONAL DATA .................................................................................3
7. APPENDIX 1: INTEGRATION WITH THE PLUG-IN FOR .NET C# ........4
INSTALLATION OF THE PLUG-IN C#................................................................4
USING THE PLUG-IN C# TO SEND INFORMATION TO V-POS ............................5
USING THE PLUG-IN C# TO RECEIVE INFORMATION FROM THE V-POS ............6
KEY GENERATION IN C#...............................................................................7
8. APPENDIX 2: INTEGRATION WITH THE PLUG-IN AND KEY
GENERATOR ON JAVA .................................................................................9
8.1. JAVA PLUGIN SETUP ...........................................................................9
8.2. PLUGIN DE JAVA 2.0.1 COMPONENTS ..................................................9
8.3. USING JAVA PLUG-IN TO SEND INFORMATION TO VPOS........................9
8.4. USING JAVA PLUG-IN JAVA TO RECEIVE INFORMATION FROM V-POS ...11
8.5. KEY GENERATION IN JAVA .................................................................12
9. APPENDIX 3: INTEGRATION WITH THE PLUG-IN FOR PHP 5 ON
LINUX ............................................................................................................14
PRINCIPAL REQUIREMENTS: .......................................................................14
INSTALACIÓN DEL PLUG-IN EN PHP5 ..........................................................15
USING PLUG-IN EN PHP TO SEND INFORMATION TO THE VPOS....................22
USING PLUG-IN ON PHP TO RECEIVE INFORMATION FROM THE V-POS .........26
KEY GENERATION ......................................................................................27
10. ERROR CODE LIST GIVEN BY VPOS ..................................................28
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 2
1. Introduction
In order to make electronic transactions merchants require a
platform that will allow them to connect with the transactional
world of virtual payments.
Nowadays, the payment flow is made up by two main processes.
The first is the authentication; this allows the cardholder to be
more secure when placing a purchase online. The Authentication
Process consists of three principal domains: Buyer with the
Merchant Plug-in (MPI) service, Issuer with the Access Control
Server (ACS) and Interoperability with the Directory Server service.
The second main process is the authorization that allows the
payment request of an electronic purchase.
These processes will be taken care of by the V-POS, a centralized
service that will allow all companies to easily integrate themselves
with the payment process.
1.1. Objectives
This document has the following objectives:
•
•
Describe the V-POS functionalities.
Describe the necessary steps for the V-POS integration.
1.2. Glossary
In this document the following terms are used and defined as
follows:
•
•
•
•
•
•
Authentication Process: Cardholder verification service.
Authorization Process: Payment authorization service.
MPI: Merchant Plug-In. Authentication Service for the buyer
and merchants.
ACS: Access Control Server. Authentication Service for the
Issuer.
V-POS: Virtual Point Of Sale. Interface of the transactional
world of virtual payments.
Cardholder: one who possess a card.
1.3. Purchase Flow
The purchase flow begins when a cardholder wants to purchase
something in an electronic merchant.
The cardholder chooses the products he wishes to purchase adding
them to the merchant’s shopping cart. Next, the steps in the
purchase flow will be detailed (see Image 1. Purchase Flow):
1. The Merchant, using an application, sends the data of the
purchase to the V-POS using the plug-in given by ALIGNET,
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 3
2.
3.
4.
5.
6.
7.
8.
9.
the data does not include the Credit Card number,
expiration date and the CVV2.
A screen will appear where the cardholder will be able to
register his credit card number, expiration date and the
CVV2 value. V-POS will show said webpage.
The user will register the requested information on the
previous page.
V-POS will send the corresponding information to the MPI in
order to begin the authentication process.
If the card is enrolled with Verified by Visa/MasterCard
SecureCode, another page will pop up and request a
password in order for the purchase to be authenticated.
When finalizing the authentication process, the MPI returns
the information of the authentication to V-POS.
V-POS, after analyzing the information returned by the MPI,
sends a payment request to the V-Payment system that
initiates the authorization process.
V-Payment returns the information to V-POS after carrying
out the authorization process for the posterior analysis of
the purchase process.
V-POS returns the purchase result to the merchant. The
merchant using the plug-in (see Appendixes) gets the
response information, which finally shows the cardholder the
purchase result.
MERCHANT
Image 1: Purchase Flow
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 4
1.4. Purchase Experience
Next we will see the purchase experience that a cardholder has
when making an electronic purchase using the platform:
1. The cardholder enters the merchant’s commercial web side.
Image 2: Screenshot of Merchant’s Homepage
2. The cardholder fills the shopping cart, and then enters their
purchase data which will begin the purchase flow.
Image 3: Screenshot of the Merchant’s Shopping Cart
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 5
3. Then the cardholder will see a centralized V-POS screen, this
screen will ask for the credit card information.
Image 4: Centralized V-POS screenshot for credit card
data entry.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 6
4. If the cardholder is enrolled or affiliated to Verified by Visa
(process which is requested by the cardholder to the Issuer
of the credit card) then the authentication screen will
appear.
Image 5: Screenshot of Cardholder’s authentication.
5. Finally, the cardholder will see a screen with the result of
their purchase.
Figura 6: Screenshot with the purchase result.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 7
2. What is V-POS?
V-POS is a system that tends to the payment requests sent from
virtual merchants and its main functions are to concentrate and
process all payment requests. It centralizes two main processes of
the purchase flow (authentication and authorization); it also
preprocesses because it processes the validation data of the credit
card before it begins the authentication and authorization process.
2.1. Description
The main function is to concentrate purchase transactions through
an electronic merchant in order to validate general purchase data,
as well as centralizing security when obtaining sensitive data from
the cardholder (credit card number, expiration date and CVV2),
initiating the payment process – Authentication and Authorization
Process – in order to finally give the transaction response to the
requesting merchant.
2.2. Architecture
The merchant will contact V-POS via Internet through a secure
channel (HTTPS) in order to send the purchase data from a form
through the cardholder’s navigator. Then, the cardholder will see a
screen presented by V-POS to enter sensitive data so that later the
payment
processes
can
commence:
Authentication
and
Authorization. Finally, V-POS will send from the form the
merchant’s transaction result via Internet using a secure channel
(HTTPS).
The V-POS general architecture is displayed in the following chart:
Authentication
Process
Cardholder
Authorization
Process
Merchant
Image 7: Architecture with V-POS
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 8
2.3. Request and Response of the Payment Flow
The merchant will send an application or payment request to V-POS
which will handle carrying out the authentication and authorization
process and will receive a response to the two processes as it is
shown in the previous image.
Tarjeta
Habiente
Sitio Web
Comercio
V-POS
Autenticación
V-Payment
Autorización
1: Completa Datos de Compra
2: Envía datos de Compra
3: muestra página centralizada
4: Ingresa datos de tarjeta
5: Solicita Autenticación
6: Solicita clave VbV
7: Ingresa su clave VbV
8: envía resultado de Autenticación
9: Solicita Autorización
10: envía resultado de Autorización
11: resultado a la página de respuesta
12: Muestra resultado
Image 8: Diagram of the sequence of request and response of the
payment flow
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 9
3. V-POS Integration
3.1. V-POS Integration Process
Initially, the integration is done in a Test environment and then is
transferred to a Production environment.
Test Environment:
The principal steps for the integration of a merchant to V-POS in a
test environment are:
1. The merchant is given a platform document of the website, said
document must be returned with all the requested data.
2. The document is approved and the security KIT is handed in.
The KIT is made up of a Security Component (plug-in),
cryptographic key generator and the digital signature which will
be used during the purchase process.
3. The merchant will review and evaluate the Merchant Integration
Guide, the Security Component (plug-in), as well as the
cryptographic key generator and the digital signature for the
necessary development that will have to be made.
4. The merchant will confirm the completion date of their
development and request the authorization of the test
environment.
5. The merchant will be registered in the authentication and
authorization systems before initiating a purchase trial process.
In this phase of the merchant’s registry, the necessary data will
be requested for its integration in the different systems involved
(Directory Server, MPI, V-Payment).
6. References o the contact people responsible of the tests and of
initiating the exchange of the cryptographic keys and the digital
signature between ALIGNET and the merchant.
7. The merchant will be given the configuration values
(IDACQUIRER, IDECOMMERCE) required for the Security
Component (plug-in).
8. The merchant will use the Cryptographic Key Generator and
digital signature that it was given (see cryptographic key
administration).
The public test keys generated for the
merchant will be sent to ALIGNET through a secure channel
(secure mail). The V-POS public keys will be sent since they are
a requirement for the security component (plug-in). The
merchant will give a value for the initialization vector which will
be sent using the same channel.
9. The merchant and ALIGNET will confirm by mail to the Buyer
that his keys have been configured in the test environment.
10. The merchant will receive the test data and the Access route to
V-POS in the test environment.
11. The business will agree on a date and time to carry out the
tests. The people responsible for the tests are defined for
ALIGNET as well as for the merchant.
12. The tests are carried out.
13. ALIGNET informs the Buyer of the completion and result of the
tests in the Test Environment.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 10
14. The Buyer may carry out additional validation tests.
Note: According to the Buyer procedure, the merchant can register
in Verified by Visa when it sees fit to do so.
Production Environment:
The main steps for the merchant integration to V-POS in the
production environment are:
1. The merchant is asked for the required production data for the
V-POS integration. The format will be given by ALIGNET. The
Merchant will be registered in the systems of Authentication and
Authorization of Production.
2. References or contact people of the merchant will be sent in
order to start the cryptographic key and digital signature
exchange between ALIGNET and the Merchant as well as the
delivery
of
the
configuration
values
(IDACQUIRER,
IDECOMMERCE) to the merchant.
3. Again, the merchant will use the Cryptographic Key Generator
and digital signature that it was given (see cryptographic key
administration).
The new public keys generated by the
merchant will be sent to ALIGNET through a secure channel
(secure mail). The V-POS public keys will be sent since they are
a requirement for the security component (plug-in). The
merchant will give a value for the initialization vector which will
be sent through the same channel.
4. Both the merchant and ALIGNET will confirm via mail to the
Buyer that the keys are configured in the Production
Environment.
5. The merchant sends the access route and the necessary data to
the V-POS Production to carry out the production tests.
6. The merchant will set a date and time to carry out the tests.
Both the merchant and ALIGNET will determine the people
responsible for carrying out the tests.
7. The tests are carried out.
8. ALIGNET informs the Buyer of the completion of the tests in the
production environment.
9. The Buyer may want to carry out additional validation tests.
Note: According to the Buyer procedure, the merchant can register
in Verified by Visa when it sees fit to do so.
3.2. Administration of cryptographic keys
With the purpose that the information transmission between the
merchant and V-POS be made in a secure manner, maintaining the
three main security principles: Protection, Integrity and
Authenticity of data, the merchant will generate a set of keys
(public and private) to encode the information and a set of keys
(public and private) for the creation of a digital signature of the
payment request. The public keys will be sent by the merchant to
V-POS during the merchant’s integration stage (see V-POS
Integration). V-POS will also generate a set of keys for the
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 11
encoding and another set of keys for the digital signature creation
of the payment response. The public keys will be sent through VPOS to the merchant during the its integration stage (see V-POS
Integration).
Once the keys have been generated, both the merchant as well as
V-POS will exchange their respective public keys and send them
through secure e-mail. Additionally, the merchant will define a
value for the initialization vector that will be used for the
cryptography and will also be sent. Said value will be a
hexadecimal of 16 characters, for example: d412589745df36fa. It
is the merchant’s responsibility to store the keys in a safe
environment.
Next we will present a chart that sums up the key exchange
between the merchant and ALIGNET’s V-POS:
COMERCIO
Merchant
V-POS
Set
Set
ofof
RSA
keys
keys
RSA
1024
PAR
DE
LLAVES
RSA
BITS
1024
forBITS
the
digital
for the
1024
BITS
PARA
FIRMA
signature
digital signature
DIGITAL
PAR
LLAVES
Set DE
of RSA
keys RSA
1024
BITS
PARA
1024
BITS
for the
CIFRADO
encoded RSA
RSA
KEY
GENERACION
GENERATION
DE
LLAVES
Set of
keys 1024
PAR
DERSA
LLAVES
RSA
BITSBITS
for the
digital
1024
PARA
FIRMA
signature
DIGITAL
Set of
keys 1024
PAR
DERSA
LLAVES
RSA
BITSBITS
for the
encoded
1024
PARA
RSA
CIFRADO RSA
Set of PUBLICA
RSA keys
LLAVE
1024BITS
BITSPARA
for the
1024
digital signature
FIRMA DIGITAL
CORREO
SECURE
E-MAIL
SEGURO
LLAVE
Set of PUBLICA
RSA keys
1024
1024BITS
BITSPARA
for the
CIFRADO
encoded RSA
RSA
KEY EXCHANGE
INTERCAMBIO
DE LLAVES
SEBothe
ENVIAN
AMBAS
public
keys
LLAVES
PUBLICAS
generated
by the
GENERADAS
merchant arePOR
sentEL
COMERCIO
CORREO
SECURE
E-MAIL
SEGURO
Image 9: Merchant key exchange and V-POS
3.3. Payment Request
A payment request is defined as data that needs V-POS in order to
generate the authentication as well as the authorization application.
To initiate the payment request, the merchant must prepare a
POST HTTPS petition in which the security component (plug-in) will
be used in order to send the petition securely to V-POS.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 12
Dispatch Parameters
The parameters that the merchant will send to V-POS in order to
initiate the payment request are:
Field
IDACQUIRER
IDCOMMERCE
XMLREQ
DIGITALSIGN
SESSIONKEY
Description
The Buyer’s fixed identification which allows VPOS to recognize the buying entity of the
merchant. This value is generated by ALIGNET.
Fixed identification of the merchant or virtual
store that allows V-POS to recognize the
merchant that is sending the payment request.
Message of the payment request that contains
the purchase data. This message is generated by
the plug-in, that is in charge of encoding the
message for it to be sent to V-POS.
Digital signature of the message XMLREQ that
insures the authenticity of the issuer and
recipient, as well as the integrity of the
information. This digital signature is generated by
the plug-in.
Session key with which the message XMLREQ will
be encoded. This key is generated by the plug-in.
In order to dispatch the payment request a POST HTTPS request
must be generated using a HTML form, implemented in the
merchant or virtual store programming language. This form must
have the following form:
<form name=”frmSolicitudPago” method=”post”
action=”https://test2.alignetsac.com/VPOS/MM/transactionStart20.do”>
<input type=”hidden” name=”IDACQUIRER” value=”2”>
<input type=”hidden” name=”IDCOMMERCE” value=”359”>
<input type=”hidden” name=”XMLREQ” value=”D2ZQMEg4c9qlxJE3r2u3Y8PXT7vZ
5JNkrY84pEg4c94c9hS14k9OUWk4Y1”>
<input type=”hidden” name=”DIGITALSIGN” value=”hS14k9OUWk4c9qldiN2vfBdjg4jB9
Wk4D2ZQMEg4c94c9qlOxVUg4yj2Q9atvfByY”>
<input type=”hidden” name=”SESSIONKEY” value=”S14k9OUWk”>
</form>
Necessary parameters for the Security Component
In order for the Security Component (plug-in) to generate the
message parameter XMLREQ, the merchant must fill in the
following parameters with the respective values:
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 13
Plug-in Field
Type
acquirerId
NUMERIC
commerceId
NUMERIC
commerceMallId
purchaseOperationNumber
NUMERIC
12
ALPHANUMERIC
12
purchaseAmount
NUMERIC
12
Only identification for each transaction, given by the
merchant (1)
Total value of the purchase, given by the Merchant. The
amount must not be spaced by decimals (if the amount
is 100.30 dollars the amount sent is 10030) (1)
15
IP Address of the cardholder
12
Currency according to the numeric ISO standard
Alphanumeric type, 3 characters long (it must be in the
currency that the merchant allows) (1)
Language used, there must be two possible values:
Spanish (SP), English (if no value is sent then the
language by default will be Spanish)
purchaseIPAddress
Maximum
Width
purchaseCurrencyCode
ALPHANUMERIC
NUMERIC
language
ALPHANUMERIC
2
billingFirstName
ALPHANUMERIC
30
billingLastName
ALPHANUMERIC
50
billingEMail
billingAddress
billingZIP
billingCity
billingState
billingCountry
ALPHANUMERIC
50
50
10
50
15
2
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
Observations
Buyer’s code assigned by Alignet. Fixed value equal to
the IDACQUIRER parameter (1)
Merchant’s only code assigned by Alignet. Fixed value
equal to the IDCOMMERCE parameter (1)
Value of ID del Mall to which the merchant belongs
Name of the cardholder. (as it appears on the credit
card)
Last name of the cardholder (as it appears on the credit
card)
E-mail address of the cardholder
Address of the cardholder
Cardholder’s zip code
Name of the cardholder’s city.
Name of the cardholder’s state.
Name of the cardholder’s country.
© 2008 - 2012 ALIGNET. All Rights reserved.
This document is confidential. The contents and concepts developed in the document cannot be used by natural or legal entities to whom this information has not been sent explicitly to.
billingPhone
shippingAddress
ALPHANUMERIC
shippingZIP
shippingCity
shippingState
shippingCountry
shippingPhone
shippingFirstName
shippingLastName
HTTPSessionId
ALPHANUMERIC
additionalObservations
terminalCode
reserved1
.
.
.
reserved40
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
ALPHANUMERIC
15
50
Cardholder’s telephone number.
Delivery address of the cardholder’s order.
10
50
15
2
15
30
50
30
Shipping zip code.
Name of the shipping city.
Name of the state/region or department of shipment.
Name of the shipping country.
Shipping phone number.
Name of the person who will receive the products.
Last name of the person who will receive the products.
HTTP session, only in the case when the merchant
requires it.
Additional observations of the purchase.
Purchase terminal code.
Additional fields not reviewed by the VPOS (2)
50
12
30
(1) Fields required by VPOS
(2) What is sent in these fields will be returned with a response
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 1
Security Parameters necessary for the Plug-in
As well as the values or given fields, the values or necessary fields
will have to be entered in the plug-in in order to encode the
message XMLREQ and the same goes for the digital signature
creation of the same message. These values are described as
follows:
Field
Initialization
Vector
Plug-in Field
VectorInicializacion
(Initialization Vector)
Private
LlavePrivadaFirmaRSA
Signature Key (PrivateSignatureKeyRS
A)
Public
Encoded Key
LlavePublicaCifradoRSA
(PublicEncodedKeyRSA)
Observations
Necessary value to encode the
XMLREQ message. This value is to be
generated at the time of the
merchant’s registry to V-POS.
Private key of the merchant with which
the digital signature will be created of
the XMLREQ message. This private key
is created and stored by the merchant.
Public key with which the message
XMLREQ will be encoded. This public
key is created by ALIGNET and must
be stored by the merchant.
© 2008 - 2012 ALIGNET. All Rights reserved.
This document is confidential. The contents and concepts developed in the document cannot be used by natural or
legal entities to whom this information has not been sent explicitly to.
3.4. Payment Response
Receipt Parameters
The payment response that V-POS will be sent to the merchant and
will be made up of the following fields:
Field
IDACQUIRER
IDCOMMERCE
XMLRES
DIGITALSIGN
SESSIONKEY
Description
Buyer’s fixed identification with which V-POS will
be able to identify the buying entity of the
merchant. This value will be created by ALIGNET
during the Buyer’s configuration.
Identification of the merchant or virtual store that
will allow V-POS to recognize the merchant that is
sending a payment request. This value is created
by ALIGNET during the merchant’s configuration.
This is the payment response that contains the
authorization result data.
This is the digital signature of the XMLRES
message and it also insures the authenticity of
the issuer and recipient as well as the integrity of
the information. This digital signature is created
by V-POS.
This is the session key with which the XMLRES
message will be deciphered.
In order to receive a payment response from V-POS it is necessary
that the merchant implement a dynamic page where the values of
the parameters will be extracted as shown in the previous table.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 1
Response parameters obtained from the Plug-in
The XMLRES will return the same fields sent in the XMLREQ which were sent when the purchase commenced and will also
add the following fields:
Plug-in Field
Type
authorizationResult
NUMERIC
authorizationCode
ALPHANUMERIC
errorCode
ALPHANUMERIC
errorMessage
ALPHANUMERIC
Maximum
Width
2
4
Observations
This field contains the authorization result. There are three
possible values sent through V-POS:
00, indicates the transaction has been authorized,
01, indicates the transaction has been denied in the Issuing
Bank, and
05, indicates the transaction has been rejected by VPOS, when
the transaction is cancelled, not sent to the authorization
process for pre authorization rules application or reversed for
post authorization rules application.
IMPORTANT NOTE: The merchant will show the result
messages to the cardholder according to the following three
codes. For example:
“Authorized Operation”.
“Denied Operation”.
“Rejected Operation” (1)
When the transaction has been authorized, this field will
contain the transaction authorization code. (1)
When the transaction has been denied or rejected this field will
contain the respective error code that will indicate the rejected
amount. The list of codes can increase or decrease according to
the improvements carried out in THE V-Payment and/or new
specifications of the brand.
IMPORTANT NOTE: The cardholder must not see this
response code.
This field contains the description of the error code in case a
rejection has occurred.
IMPORTANT NOTE: The cardholder must not see this error
© 2008 - 2012 ALIGNET. All Rights reserved.
This document is confidential. The contents and concepts developed in the document cannot be used by natural or legal entities to whom this information has not been sent explicitly to.
message. The Buyer must coordinate with the merchant so that
a group of messages be shown.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 1
Besides these fields, the payment response or XMLRES, contains all
the sent fields to V-POS that were entered in the XMLREQ of the
payment request and will be recuperated using the security
component (plug-in).
Necessary parameters in order to obtain the XMLRES data
In order to decipher the XMLRES message, the necessary values or
cryptographic fields will have to be configured in the plug-in, as
well as the digital signature confirmation of the same message.
These values are described as follows:
Field
Initialization
Vector
Public Key
Signature
Private Encoded
Key
Plug-in Field
VectorInicializacion
(Initialization
Vector)
Observations
Necessary value to decipher the
XMLRES message. This value is
created
when
the
merchant
registers in V-POS.
LlavePublicaVerificac This is the V-POS public key with
ionFirma
which the validity of the digital
(SignatureVerificatio signature of the XMLRES message
nPublicKey)
will be confirmed. This key is
generated by V-POS and stored by
the merchant.
LlavePrivadaCifrado This is the private key with which
(PrivatedEncodedKe the XMLRES will be deciphered.
y)
This key is generated and stored
by the merchant.
© 2008 - 2012 ALIGNET. All Rights reserved.
This document is confidential. The contents and concepts developed in the document cannot be used by natural or
legal entities to whom this information has not been sent explicitly to.
4. Integration with the Plug-in
The merchant will receive the Security Component (plug-in) that
will be connected to a Web solution in order for it to be activated at
the time of the final purchase request (normally when clicking on
the “Shop” button).
The Security Component (plug-in) is available for the following
programming languages:
•
•
•
Plug-in .Net (C#)
Plug-in .Java
Plug-in .PHP
A plug-in will be given according to the merchant’s platform. For
more details regarding the integration see the corresponding
Appendix of the required programming language.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 1
5. Frequently Asked Questions
What languages does the Security Component (plug-in) support?
Right now the plug-in has a version for each of the following
languages: : Microsoft .Net (C#), Java and PHP. According to
the merchant’s Website platform, a corresponding version will
be sent.
The document says that merchants must generate encrypted keys
and digital signatures. How will the generation of said items occur?
Besides the Security Component (plug-in) an application will be
given for the merchant’s platform through which said keys will
be generated.
The document says that we should exchange encrypted keys and
digital signatures. How will the exchange take place?
The key exchange will be carried out through a safe channel
between the merchant and ALIGNET. One of the possibilities to
carry out the exchange of the keys is to request the safe e-mail
address of your supplier.
Is there a merchant shopping cart that can be integrated to the
plug-in?
No. There are various Websites that offer shopping carts or
Websites for merchants, but in order to carry out the
integration the support of a programmer is necessary or a
developer so that he can integrate into the merchant’s platform
the plug-in code.
If the merchant supports the English language, why does the entry
page of the Verified by Visa/MasterCard Secure Code appear in
Spanish?
The entry page of the Verified by Visa/MasterCard Secure Code
password is a page that belongs to the credit card Issuer and
does not belong to the Buyer nor the Merchant. The language of
the page will be the one the Issuer has decided to configure for
its cardholders.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 2
6. Additional Data
The specified keys in every form differs according to the
environment where the merchant is integrated, so the URLs of
VPOS.
Here is listed the URLs:
-TESTING URL VPOS:
https://test2.alignetsac.com/VPOS/MM/transactionStart20.do
-PRODUCTION URL VPOS:
https://vpayment.verifika.com/VPOS/MM/transactionStart20.do
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 3
• Appendix 1: Integration with the Plug-in for .Net C#
Installation of the Plug-in C#
The merchant will be given a dll VERIFIK_PROTOCOL.dll that will
have to be connected to their web solution; next we will present
the steps in the plug-in integration:
2.Examinar
2. Browse
1.Click
1. Right derecho
click: Add :
Agregar
referencia
Reference
3. 3. Choose
Escoger
VERIFIK_PROTOC
VPOS20_PLUGIN.
OL.dll
y Abrir
dll and
Open
o
o
Reference to the plug-in in l a References folder of the Web
application
In
the
Add
Reference
window
search
for
the
VPOS20_PLUGIN.dll component
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 4
Using the Plug-in C# to send information to V-POS
Keys to send information:
Testing:
ALIGNET.TESTING.NOPHP.CRYPTO.PUBLIC.txt
Signature private key of the merchant
Producción:
ALIGNET.PRODUCCION.NOPHP.CRYPTO.PUBLIC.txt
Signature private key of the merchant
Next we will show an example of the plug-in using C#:
//Asemblies adicionales a usar
using System.IO;
using VERIFIK_PROTOCOL;
//Instanciando e inicializando
VPOSBean oVPOSBean = new VPOSBean();
oVPOSBean.acquirerId = "2";
oVPOSBean.commerceId = "359";
oVPOSBean.purchaseCurrencyCode = "840";
oVPOSBean.purchaseAmount = "10000";
oVPOSBean.purchaseOperationNumber = "40";
oVPOSBean.language = "EN";
StreamReader
srVPOSLlaveCifradoPublica
=
new
StreamReader("D:/LLAVE.VPOS.CRYPTO.1024.txt");
StreamReader
srComercioLlaveFirmaPrivada
=
new
StreamReader("D:/LlaveFirmaComercioPrivada.txt");
VPOSSend
oVPOSSend
=
new
VPOSSend(srVPOSLlaveCifradoPublica,
srComercioLlaveFirmaPrivada, "0000000000000000");
oVPOSSend.execute(ref oVPOSBean);
//Recuperando datos cifrados
String sCipheredSessionKey = oVPOSBean.cipheredSessionKey;
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 5
String sCipheredXML = oVPOSBean.cipheredXML;
String sCipheredSignature = oVPOSBean.cipheredSignature;
Using the Plug-in C# to receive information from the V-POS
Keys to receive information:
Testing:
ALIGNET.TESTING.NOPHP.SIGNATURE.PUBLIC.txt
Private encryption key of the merchant
Production:
ALIGNET.PRODUCCION.NOPHP.SIGNATURE.PUBLIC.txt
Private encryption key of the merchant
Next we will show an example of the code implemented in the C#
in order to decipher the data and the verification of the digital
signature:
using System.IO;
using System.Collections.Specialized;
using VERIFIK_PROTOCOL;
NameValueCollection coll = new NameValueCollection();
coll = Request.Params;
String sIDACQUIRER = coll.Get("IDACQUIRER");
String sIDCOMMERCE = coll.Get("IDCOMMERCE");
String sXMLRES = coll.Get("XMLRES");
String sSESSIONKEY = coll.Get("SESSIONKEY");
String sDIGITALSIGN = coll.Get("DIGITALSIGN");
VPOSBean oVPOSBean = new VPOSBean();
oVPOSBean.cipheredXML = sXMLRES;
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 6
oVPOSBean.cipheredSessionKey = sSESSIONKEY;
oVPOSBean.cipheredSignature = sDIGITALSIGN;
StreamReader
srVPOSLlaveFirmaPublica
=
new
StreamReader("D:/LLAVE.VPOS.FIRMA.1024.txt");
StreamReader
srComercioLlaveCifradoPrivada
=
new
StreamReader("D:/LlaveCifradoComercioPrivada.txt");
VPOSReceive oVPOSReceive = new VPOSReceive(srVPOSLlaveFirmaPublica,
srComercioLlaveCifradoPrivada, "0000000000000000");
oVPOSReceive.execute(ref oVPOSBean);
if ( oVPOSBean.validSign == true )
{
//El descifrado fue correcto y la firma digital es correcta
//Luego
evaluar
oVPOSBean.authorizationResult
para
saber
si
la
transacción fue aceptada o denegada
}
Key Generation in C#
In order to generate keys the following application is used:
KeyGeneratorVerifika.exe, to execute it, it needs to be installed in
the .net Framework of a PC with Windows 98, XP, 2000, etc. and
the VERIFIK_PROTOCOL.dl library must be placed in the same
folder as the one where the exe file will executed from.
1. Execute the KeyGeneratorVerifika.exe
Generate Keys button.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
file
and
press
the
Page 7
PRIVATE KEY
PUBLIC KEY
Generate
Keys
PRIVATE KEY
PUBLIC KEY
2. Once the keys are generated save the private keys in a secure
device and the public keys will be sent through a secure
environment.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 8
7. Appendix 2: Integration with the Plug-in and Key
Generator on Java
7.1. Java Plugin setup
The merchant will receive a .jar file that must be installed in its
web project. Next, it is presented the steps for the Java plugin
integration with the merchant:
•
•
In case the application is a stand alone, configure in the
classpath variable, the plugin-vpos-1.2.jar library
In case the application is a Web project, include in the folder
library WEB-INF\lib the file plugin-vpos-1.2.jar
7.2. Plugin de Java 2.0.1 Components
• VPOS Data bean (com.alignet.bean.VPOS20Bean), which
contains the data to be sent to VPOS and data to be received
from VPOS.
7.3. Using Java Plug-in to send information to VPOS
Keys for sending information:
Testing:
ALIGNET.TESTING.NOPHP.CRYPTO.PUBLIC.txt
Private signature key of the merchant
Production:
ALIGNET.PRODUCCION.NOPHP.CRYPTO.PUBLIC.txt
Private signature key of the merchant
Next, it is presented Java code for sending information to VPOS:
// referencing the componen
import com.alignet.bean.*;
import com.alignet.exception.*;
import com.alignet.plugin.*;
//Create an instance of VPOSBean class of the package com.alignet.bean
VPOS20Bean bean = new VPOS20Bean();
//Set parametersinside the Plugin object properties
try
{
bean.setAcquirerId (“34”);
bean.setCommerceId (“588425”);
bean.setPurchaseAmount (“15000”);
bean.setPurchaseCurrencyCode (“840”);
bean.setPurchaseOperationNumber (“5646554”);
// Set the other parameters.
}
catch(InvalidVPOSParameterException e)
{
//errors setting mandatory data
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 9
e.printStackTrace();
}
// set optional fields, if it is necessary
// set reserved fields, if its necessary
bean.setReserved1(“5646554”);
// set the plugin with encryption values
try
{
//instance Send class, with parameters the public
//encryption key, privada signature key and
//initialization vector
Send20 send= new Send20(
new FileReader("c:\\LLAVE.VPOS.CRYPTO.1024.txt"),
new FileReader("c:\\LlavePruebaFirmaComercioPriv.txt"),
"0000000000000000");
//encrypt
send.execute(bean);
}
catch(PlugInVPOSException e)
{
//handle encryption errors
e.printStackTrace();
}
catch(FileNotFoundException e)
{
//handle reading the keys errors
e.printStackTrace();
}
//get encrypted values to set them in the sending form to VPOS
bean.getCipheredSessionKey ();
bean.getCipheredXML ();
bean.getCipheredSignature ();
To get the SESSIONKEY, XMLREQ y DIGITALSIGN fields that must
be set in the payment request form, first, it must be requestd the
execute method of the plug-in object:
send.execute(bean);
For the SESSIONKEY field that must be set in the payment request
form, first, the following method must be called:
String SESSIONKEY = bean.getCipheredSessionKey();
For the XMLREQ field that must be set in the payment request
form, first, the following method must be called:
String XMLREQ = bean.getCipheredXML();
For the DIGITALSIGN field that must be set in the payment request
form, first, the following method must be called:
String DIGITALSIGN = bean.getCipheredSignature();
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 10
The XMLREQ, SESSIONKEY y DIGITALSIGN values must
captured in the form (page 13).
be
7.4. Using Java Plug-in Java to receive information from V-POS
Keys to receive information:
Testing:
ALIGNET.TESTING.NOPHP.SIGNATURE.PUBLIC.txt
Private encryption key of the merchant
Producción:
ALIGNET.PRODUCCION.NOPHP.SIGNATURE.PUBLIC.txt
Private encryption key of the merchant
Next it is presented a Java code sample for data and digital
signature verification:
//Reference the component
import com.alignet.bean.*;
import com.alignet.exception.*;
import com.alignet.plugin.*;
//Create an instance of VPOSBean class com.alignet.bean package
VPOSBean bean = new VPOSBean();
//Set the parameters in Plugin object properties:
try
{
bean.setCipheredSessionKey (llaveSessionCifrada);
bean.setCipheredXML(xmlreq);
bean.setCipheredSignature(firma);
}
catch(InvalidVPOSParameterException e)
{
//handle parameters setting errors
e.printStackTrace();
}
//Invoke the execute method, which decrypts the xml
try
{
Receive receive= new Receive(
new FileReader("c:\\LLAVE.VPOS.FIRMA.1024.txt"),
new FileReader("c:\\LlavePruebaCifradoComercioPriv.txt"),
"0000000000000000");
receive.execute(vPOSBean);
}
catch(PlugInVPOSException e)
{
//handle decryption errors
e.printStackTrace();
}
catch(FileNotFoundException e)
{
//handle key reading errors
//if the signature is invalid, the exception is thrown
e.printStackTrace();
}
//Verifying the digital signature, that allowed data interity verification
bolean esFirmaValida = vPOSBean.isValidSign();
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 11
Next, it is presented a Java sample code to get the data using the
plug-in:
//Set decryptedvalues to variables
//In case the transaction is approved
String codigoAutorizacion = bean.getAuthorizationCode ();
//In case the transaction is denied
String codigoError = bean.getErrorCode();
String mensajeError = bean.getErrorMessage();
//Extracting other data
String variable1 = bean.getAcquirerId();
String variable2 = bean.getCommerceId();
...
String variable17 = bean.getReserved1();
7.5. Key generation in Java
To execute the Java key generator, it is required a JDK installation
and invoke the next command:
java –jar
keygeneratorverifika.jar
To generate the keys, press GenerarLlaves
When the keys are generated, with copy and paste functions, save
the private keys in an electronic device and secure it physically, or
in a secure device. The public keys must be sent through a secure
way for the VPOS integration.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 12
It is important to mention, that the keys are critic and while the
keys are very secured, it will be preserved the security of all the
system for processing transactions of the merchant.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 13
8. Appendix 3: Integration with the Plug-in for PHP 5
on Linux
Principal Requirements:
To use the PHP component on Linux is necessary have installed the
following libraries
PHP5 installed with functionalities --with-openssl and --with-expatdir (from 4.0.5)
• OpenSSL 0.9.7 en herinafter
• Library libmcrypt intalled
Checking to see if PHP libraries have been installed properly
Should generate a page containing the following PHP sentence
phpinfo();
Which generates a page like this:
See highlighted words to note that PHP now has the characteristics
required
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 14
Now, we have to look if PHP have the necessary modules installed,
for this we have to search if the following libraries exists in the
Information PHP page
•
•
•
MCRYPT
OPENSSL
XML
This way we can note that PHP is ready to used the compiled PHP
script
Instalación del Plug-in en PHP5
Download the Zend Optimizer (check this Zend Oprtimizer is
correct for the PHP version) according with the platform
(Windows, Linux, BSD, others)
URL download Zend Optimizer (choose version 3.0.2):
http://www.zend.com/free_download/optimizer
•
•
Extract the downloaded Zend Optimizer file, if the machine
architecture is i386, you have to used the following
command:
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 15
tar –zxvf ZendOptimizer-3.0.2-linux-glibc21-xxx.tar.gz
Where xxx means the machine architecture (i386 o x86_64)
•
It creates a directory called ZendOptimizer-2.6.2-linuxglibc21-i386 so we have to enter to the directory newly
created
cd ZendOptimizer-3.0.2-linux-glibc21-xxx
•
As user root is necessary install Zend Optmizer using this
command:
./install
•
It shows an screen indicating how to install the Zend
Optimizer, follow the next steps just like shows in the
screens below
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 16
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 17
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 18
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 19
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 20
•
•
At the end everything correctly Zend optimizar has been
installed, so
Al finalizar todo correctamente ya ha sido instalado el Zend
Optimizer so you can execute ofuscadas pages.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 21
Using Plug-in en PHP to send information to the VPOS
To use Plug-In it’s necessary to do the following indications:
1. Should create an entry array with all the fields that will be
send to the Plug-In.
2. The Plug-in returns an array with all the fields encrypted
and encoded ready to be send to the VPOS
a. XMLREQ
b. SESSIONKEY
c. DIGITALSIGN
3. The pages have to include the vpos_plugin.php file in the
code using the following PHP sentence:
<?php include("vpos_plugin.php");?>
Next, it will show an example about the use of the plug-in using
PHP:
array_send is the array that contains the parameters to be send to
the VPOS Plug-In
array_get is the array that contains the returns parameters of the
Plug-In to be send to the VPOS
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 22
//arraySend is the array that contents the parameter given by
the plug in ready to sent them to VPOS
//Every parameter are places in a string array
//which index field is the name of the parameter
$array_send['acquirerId']=$CodigoAdquirente;
$array_send['commerceId']=$CodigoComercio;
$array_send['purchaseAmount ']=$Monto;
$array_send['purchaseCurrencyCode']=$CodigoMoneda;
$array_send['purchaseOperationNumber']=$CodigoOperacion;
$array_send['billingAddress']=$direccionCobranza;
$array_send['billingCity']=$ciudadCobranza;
$array_send['billingState']=$estadoCobranza;
$array_send['billingCountry']=$paisCobranza;
$array_send['billingZIP']=$codigoPostalCobranza;
$array_send['billingPhone']=$telefonoCobranza;
$array_send['billingEMail']=$correoElectronicoCobranza;
$array_send['billingFirstName']=$primerNombreTarjetaH;
$array_send['billingLastName']=$ segundoNombreTarjetaH;
$array_send['language']=’SP’; //in Spanish
//Set a string array with the parameters that will be given
by the plugin
$array_get['XMLREQ']="";
$array_get['DIGITALSIGN']="";
$array_get['SESSIONKEY']="";
The keys can be write in the code:
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 23
//Example of a hard code key
//Notice that \n are placed athe the end of the lines, are
line jump hended for the PEM format
$llavePub
=
"-----BEGIN
PUBLIC
KEY-----\n".
"MIGJAoGBAKkJKIAJgm8/zA10FIpGUMAF6WTuTTKd1nqFHUokyXCNYn1oZAz6
vVqy\n".
"BfJjWxL0o8r8ooBKQ/jKIVm4mFtVgQ5EamzYQFxsmU1dFfuBZdm7o3eId7xh
mSnD\n".
"ZNiwGv7xmTybY4QH7VMqPAgaeKN9cPAnN1+F2Jzw/WVWtD7E7xXhAgMBAAE=
\n".
"-----END RSA PUBLIC KEY-----";
The keys can be read it from a flat text existing in the S.O, too.
//Initialization Vector
$vector = "0000000000000000";
//Example of a key that is read from a plain text file
$llavePriv = "file://camino_archivo_completo";
To execute the component, is necessary invocated the function
VPOSSend with all the fields to send, the exit parameters of the
function , the SESSIONKEY, el DIGITALSIGN y el XMLREQ will be
returned in the exit array, in this case the array_get
VPOSSend($array_send,$array_get,$llaveVPOSCryptoPub,$llaveComercioFirma
Priv,$VI);
Read the values incide of the array $array_get and send them by a
form to the VPOS.
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 24
<INPUT
TYPE="hidden"
NAME="IDACQUIRER"
$CodigoAdquirente; ?>">
<INPUT
TYPE="hidden"
NAME="IDCOMMERCE"
$CodigoComercio; ?>">
<INPUT
TYPE="hidden"
NAME="XMLREQ"
$array_get['XMLREQ'];?>">
<INPUT
TYPE="hidden"
NAME="DIGITALSIGN"
$array_get['DIGITALSIGN'];?>">
<INPUT
TYPE="hidden"
NAME="SESSIONKEY"
$array_get['SESSIONKEY'];?>">
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
value="<?php
echo
value="<?php
echo
value="<?php
echo
value="<?php
echo
value="<?php
echo
Page 25
Using Plug-in on PHP to receive information from the V-POS
An example of the code already implemented in PHP for deciphered
information and the check of the digital sign:
$vector = "0000000000000000";
$llavePriv
=
“file:///var/llaves/LlavePruebaCifradoComercioPriv.txt”;
$llavePriv = "file:/// var/llaves/LLAVE.VPOS.FIRMA.1024.txt";
Must be prepared the data to be enter in the function
VPOSResponse, the end of the function is true or false which
indicates if the send values of the VPOS has been deciphered and
validated correctly
if(VPOSResponse($arrayIn,$arrayOut,$llavePublicaFirma,$llavePriv
adaCifrado,$VI)){
//The output is in $arrayOut eith every deciphered parameter
parámetros given by VPOS
$ resultadoAutorizacion = $arrayOut['authorizationResult'];
$codigoAutorizacion = $arrayOut['authorizationCode'];
...
}else{
//It could be a problem of keys or vector misconfiguration
//or el VPOS has not sent correct values.
}
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 26
Key Generation
To generate the keys must use OpenSSL by command lines
Befote start the generation of the keys is preferable keep the
standars about the generation of keys, the standar is the follow:
GENERADORA.USO.TIPO.pem
Where:
GENERADORA:is the entity which generated the keys. For example
if the commerce name is “Panaderia Miga” then, could be MIGA
USO: Couldbe two values(CRYPTO or SIGNATURE) depending if the
keys works in the digital sign or in the asimetric ciphered of values.
TIPO:Indicates the key type (PUBLIC or PRIVATE)
Now Hill be indicate the steps to generate each key:
1.- First generated the Private Key by this line
openssl genrsa –out MIGA.CIFRADO.PRIVADA.pem 1024
This generate a private key of 1024 bits in the file
MIGA.CIFRADO.PRIVADA.pem
2.- Now from the private key has to extract the public key
openssl rsa –in MIGA.CIFRADO.PRIVADA.pem –out
MIGA.CIFRADO.PUBLICA.pem –pubout
This
colocate
the
public
MIGA.CIFRADO.PUBLICA.pem
key
in
the
file
3.- Repeat the same process to the other pair of keys
4.- Send to your Acquirer the public keys like this:
MIGA.CIFRADO.PUBLICA.pem
MIGA.FIRMA.PUBLICA.pem
5.- The initialization Vector value could be generate from an
random form, here are the conditions for the Vector:
a. Have to have a 16 characters maximum of length.
b. Only have to contain numbers or letter from A to F
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 27
9. Error code list given by VPOS
authorizationResult
00
01
01
01
01
01
01
01
errorCode
00
01
02
03
04
05
06
07
01
00
01
01
01
01
01
01
01
10
11
12
13
14
15
19
21
25
01
01
01
01
01
01
01
01
01
01
01
28
41
43
51
52
53
54
55
57
58
61
01
01
01
01
01
62
63
65
75
76
01
77
01
80
01
81
01
01
82
83
errorMessage
Successful approval/completion
Refer to card issuer
Refer to card issuer, special condition
Invalid merchant/service provider
Pickup card
Do not honor
Error
Pick up card, special condition (other than
lost/stolen card)
Partial approval
VIP approval
Invalid transaction
Invalid amount
Invalid account number (no such number)
No such issuer
Re-enter transaction
No action taken
Unable to locate record in file, or account number is
missing from the inquiry
File is temporarily unavailable
Pickup card (lost card)
Pickup card (stolen card)
Not sufficient funds
No checking account
No saving account
Expired card
Incorrect PIN
Transaction not permitted to cardholder
Transaction not allowed at terminal
Exceeds withdrawal amount limit (activity amount
limit exceeded)
Restricted card
Security violation
Activity count limit exceeded
Allowable number of PIN-entry tries exceeded
Unable to locate previous message (no match on
Retrieval Reference number)
Previous message located for a repeat or reversal,
but repeat or reversal data are inconsistent with
original message
Invalid date (For use in private label card
transactions and check acceptance transactions)
PIN or CVV cryptographic error found (Used by VIC
for error condition found by security module during
PIN decryptation/CVV processing
Incorrect CVV
Unable to verify PIN
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 28
01
85
01
91
01
01
01
92
93
96
01
01
01
01
01
01
01
01
01
01
01
01
01
01
05
05
05
05
01
01
01
05
05
01
05
05
05
05
05
05
N0
N3
N4
N7
P2
P5
P6
R0
R1
R3
Z3
XA
XD
Q1
1001
1002
1003
1004
1101
1102
1103
1104
1107
1114
1115
1117
2003
2100
2101
2102
05
05
05
05
05
05
05
2200
2201
2202
2300
2301
2302
2303
05
05
05
05
2305
2306
2307
2308
No reason to decline a request for account number
verification or address verification, or CVV2
verification
Issuer or switch inoperative (stand-in not applicable
or available for this transaction)
Destination cannot be found for routing
Transaction cannot be completed; violation of law
System malfunction/System malfunction or certain
field error conditions
Force STIP
Cash service not available
Cash request exceeds issuer limit
Decline for CVV2 failure
Invalid biller information
PIN Change/Unblock request declined
Unsafe PIN
Stop Payment Order
Revocation of Authorization Order
Revocation of All Authorizations Order
Unable to go online; declined
Forward to issuer
Forward to issuer
Card Authentication failed
Invalid Data sent by Commerce
Invalid Currency for Commerce
Invalid Commerce Code
Duplicated order number
Communication Problem
Processing Problem
Communication Problem
Invalid Data
Invalid VCI
Card Number does not belong to selected brand
Reverse rejected
Automatic reverse approved
Action code doesn't exist
Implementor Class not existent
Default Plan Quotas inexistent
Existing BIN for the acquirer but does not have Plan
Quotas assigned
Acquirer must need more data sent in the Plug-In
Plan Quotas not sent by Commerce
Duplicated order number
User Cancelled in PASS 1
User Cancelled in PASS 2
User Cancelled in PASS 3
CodigoOperacion Field must not be greater than 12
characters
Commerce is not active
Acquirer is not active
Transaction has been processed
Card Brand is not correct
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 29
05
05
05
05
05
05
05
2309
2310
2311
2312
2313
2314
2315
05
2316
05
2317
05
2318
05
2319
05
2320
05
2400
05
05
05
2401
2402
2403
05
2404
05
05
05
2405
2406
2407
05
05
05
05
05
05
2410
2411
2412
2413
2414
2415
05
05
2500
2501
05
05
05
3001
3002
3003
Card Number is not correct
Card Expiry Date is not correct
Card Security Code is not correct
Card Number is not present and is required
Commerce not well configured
Acquirer not well configured
Will not go to authorization due to Pre-Authorization
Rules
Transaction has been authorized but PostAuthentication Rules refused it
Transaction has been authorized but has been
reversed by Post-Authentication Rules
PurchaseOperationNumber is greater than 8
characters (Maximum for Associated Commerce)
PurchaseOperationNumber is greater than 12
characters
Commerce has not been authorized to send PAN
number
Transaction is rejected and will not be authorized
due to pre-authorization rules
Pre Authentication rules not approved
Post Authentication rules not approved
Maximum Monthly accumulated amount has been
reached
Maximum Daily accumulated amount has been
reached
Maximum Daily order number has been reached
Maximum Monthly order number has been reached
Transaction is rejected and will not be authorized
due to post-authorization rules
Mall cannot start transactions
Shipper is needed but not found
Shipping amount is not valid
Purchase amount is not valid
Associated Commerce amount is not valid
Purchase Amount and Associated Commerce
amount are not valid
Invalid amount format
Entered data is too large, please check and try
again
Rejected by Ecommerce rule
Rejected by Ecommerce rule Error
Rejected by Ecommerce rule Comm. Error
Merchant Integration Guide
Virtual POS (V-POS)
ALIGNET Merchant Solution [Confidential – ALIGNET]
Page 30