G2S - Secure Payment Page API.pdf - GetACoder

Secure Payment Page
Integration Guide
Preliminary pre-release version

CONTENTS
OVERVIEW ...........................................................................................................................................3
FLOW ...................................................................................................................................................3
MERCHANT WEBSITE INTEGRATION .........................................................................................4
INTEGRATION PART I - PRE PROCESSING INTEGRATION...................................................................4
INTEGRATION PART II - POST PROCESSING INTEGRATION................................................................6
INTEGRATION PART III - TRANSACTION VERIFICATION......................................................................6
APPENDICES ........................................................................................................................................8
1.URLS AND REQUIRED INFORMATION .............................................................................................8
2.CHECKSUM PARAMETER ALGORITHM – HOWTO ............................................................................8
3.RETURN OUTPUT ..........................................................................................................................10
4.INPUT PARAMETERS LIST ..............................................................................................................14
5.OUTPUT PARAMETERS LIST ..........................................................................................................16
© 2007 GTS Online Limited. All Rights Reserved.
2

Overview
The Gate2Shop Payment Page is a web page provided by Gate2Shop which
can be used by internet merchant to charge their customers. The Payment
Page provides all the functionality and interfaces needed for the charging and
processing.
Flow
The flow has four steps, the forth step is optional:
1. Redirecting - When the merchant business process reaches the stage
of charging of the end user the merchant is required to redirect the end
user, simply by a web form to the Payment Page.
2. Charging/Processing - The payment page receives the web form
request. It may collect some additional information from the end user
and then it will try to perform the charging.
At the end of the charging process the payment page will redirect the
end user back to the merchant site. It will be directed to one either two
pages provided by the merchant: one for success and one for failure.
3. Response - The merchant processes the response and proceeds with
its business process.
4. Verification - The fourth step is optional but highly recommended. In
this step the merchant will submit a very small request containing the
transaction ID returned by the Payment Page. This stage purpose is to
provide a final approval by the merchant in which he verifies the
transaction.
© 2007 GTS Online Limited. All Rights Reserved.
3

Merchant website Integration
The Gate2shop Secure payment page integration is divided into three parts
Pre Processing integration
Post processing integration
Transaction Verification
Integration Part I - Pre Processing Integration
The pre processing integration is best achieved by the merchant
implementing a web form on the page before the payment page. The form
contains either hidden or graphical input parameters which are to be
submitted by the form to the payment page.
The input parameters are either mandatory or optional.
Mandatory input parameters: Parameters must be provided each time by the
merchant since they can be originated only from the merchant. E.g. total
amount, currency, product-name and product-price.
Optional input parameters. Are parameters that if are not provided by the
merchant can be later collected, if necessary, by the Gate2shop Payment
Page. E.g. the consumer's names, addresses, etc.
Request Authentication - The Checksum Parameter
A unique "pre-processing" input parameter is the Checksum parameters. The
concept behind this parameter is to provide a safe and a certain way of
authenticating the merchant request to the Payment Page. The checksum is
actually a string value which is an Encryptologic Hashing calculated from
certain parameters. The checksum created is a value that cannot be spoof
or imitated by any hostile third party.
In order to generate the correct value the merchant should concatenate and
then hash using the MD5 hashing algorithm the parameters to follow. These
parameters are also mandatory parameters and should also be passed in
their regular form:
© 2007 GTS Online Limited. All Rights Reserved.
4

- Secret string. This is a secret value which will be provided by Gate2shop
and known only to Gate2shop and the merchant.
- Merchant ID. Uniquely identifying the merchant on the Gate2shop
system.
- Currency. Of the amount to charge.
- Amount. Of the transaction
- Time Stamp. Of the transaction.
Important Note: the checksum must be generated on the server side and never on the
client side (on the server script: php, jsp, servlet, asp, aspx, etc. not on the html page -
not by JavaScript). This in order to prevent exposing the algorithm and most
importantly the Secret value.
© 2007 GTS Online Limited. All Rights Reserved.
5

Integration Part II - Post Processing Integration
The post processing integration is achieved by the merchant implementing
two web pages that receive the Payment Page processing result and react to
it according to the merchant business process. Three pages stand, one for
success and the other one for failure. The third back page is called by the
Payment Page when the end user press back.
When the Payment Page finishes its process it will redirect the end user either
to the success or failure pages, providing all the transactions output
information by HTTP parameters string.
The HTTP output information includes:
- Transaction status information. E.g. transaction result, declining
reason in case of decline, authorization number in case of approval,
Gate2shop transaction ID and so on.
- End user Information that were collected by the Payment Page. Such
as the end user's names, addresses, payment method information and
so on.
The back page is intended to allow the end user to return to the merchant
website. Since pressing the browser “Back” button will not necessarily
maintain the end user’s session on the merchant’s site we provide this page
to allow this functionality.
Integration Part III - Transaction Verification
After the transaction response was received by the merchant on his success
page, there is one more optional step to complete the whole Payment
process. In this Transaction verification step the merchant will verify to
Gate2shop that he received the charge and approves it. This step can be a
strong tool for preventing mismatching between the merchant and Gate2shop
in real time, and in the long run this is an important chargeback preventing
feature.
In order to perform the verification the merchant needs sending an approving
HTTP request to a Payment Page specific URL. The Verification URL will be
© 2007 GTS Online Limited. All Rights Reserved.
6

processed by the Payment Page and finalized the transaction and then it will
retrieve a pixel image to the requester. This way the merchant is able to
simply add a pixel image to his success page, which will practically be
invisible and this way to achieve the verification.
© 2007 GTS Online Limited. All Rights Reserved.
7

Appendices
1. URLs and required information
1.1. To be provided by the merchant
- Success page URL
- Failure page URL
- Back page URL.
1.2. to be provided by Gate2shop
- Payment Page URL: https://secure.gate2shop.com/ppp/purchase.do
- Checksum secret input parameter value
- Merchant ID. Identifies the merchant to the Payment Page
- Merchant Site ID. Identifies the merchant website to the
Payment Page.
2. Checksum parameter Algorithm - Howto
Step I: concatenate the hashed values
The checksum is concatenating the following parameters, in the following
order
- secret - a password string which will provided to by Gate2shop. This
is the only parameter which is not also an input parameter.
- merchant_id The same as the input parameter with the same name.
Provided by Gate2shop
- Currency. The currency of the transaction
- total_amount. The amount of the transaction
- Product Array. This array contains the relevant information
regarding the products of the transaction (name, price &
quantity): item_name_X, item_amount_X, quantity_X, where ‘X’
stand for the product index in the array. (please see formula
bellow)
- Time_stamp. The date/time of the transaction. The timestamp format
is YYYY-MM-DD.hh:mm:ss
© 2007 GTS Online Limited. All Rights Reserved.
8

Comments:
* The concatenation must be in the mentioned order
* Values are case sensitive and should be identical to the equivalent
parameter in the http request.
* No delimiter between the concatenated values
* Formula: string before MD5 hashing should be concatenated as follows
secret + merchant_id + currency + total_amount +
item_name_1 + item_amount_1 + quantity_1 +
item_name_2 + item_amount_2 + quantity_2 +
. . .
item_name_N + item_amount_N + quantity_N +
time_stamp
Step I: hash the concatenated value
After the values were concatenated you will need to run the value through an
MD5 algorithm function, the result will be the checksum value – a
hexadecimal value you will have to submit to the payment page.
Examples
Example 1 – single item request
Parameters participating in the checksum:
secret=IA9jhabxRVg0kGTDLm0pFKOqoI6eJ8xnUJifRIOy2U79aykdOhfwJ4croJO4Iu
xH
merchant_id=1
currency=USD
total_amount=1.00
(note the when doing the hash sum (MD5) there is difference between 1
and 1.00, because the hash is performed over the string
representation of the number)
item_name_1=test item
(note that items names supported character set is only ISO-8859-1
encoding. This is mainly the Latin alphabet)
item_amount_1=1.00
© 2007 GTS Online Limited. All Rights Reserved.
9

time_stamp=2007-09-05.08:50:13
After concatenation:
IA9jhabxRVg0kGTDLm0pFKOqoI6eJ8xnUJifRIOy2U79aykdOhfwJ4croJO4IuxH1USD1
.00test item1.002007-09-05.08:50:13
After MD5 Hash:
65d4b2c8b768b9dda556eb846a28f328
An example HTTP GET request corresponding to the above checksum. Note,
that values are URL Encoded if you are doing HTTP GET.
https://securehost/ppp/purchase.do?checksum=65d4b2c8b768b9dda556eb846
a28f328&time_stamp=2007-09-
05.08%3A50%3A13&merchant_site_id=2302&merchant_id=1&item_amount_1=1.0
0&item_name_1=test%20item&total_amount=1.00&currency=USD
Example 2 – multiple items example
There is no major difference on how you do single item or multiple items
request. You just need to include all of the item names and amount in the
checksum. It is important to note that the numberofitems parameter is now
mandatory but it is included only in the HTTP GET or POST - but not in the
checksum itself.
Parameters participating in the checksum:
secret=IA9jhabxRVg0kGTDLm0pFKOqoI6eJ8xnUJifRIOy2U79aykdOhfwJ4croJO4Iu
xH
merchant_id=1
currency=USD
total_amount=2.00
(note the when doing the hash sum (MD5) there is difference between 2
and 2.00, because the hash is performed over the string
representation of the number)
item_name_1=test item
(note that items names supported character set is only ISO-8859-1
encoding. This is mainly the Latin alphabet)
item_amount_1=1.00
item_name_2=test item 2
item_amount_2=1.00
© 2007 GTS Online Limited. All Rights Reserved.
10

time_stamp=2007-09-05.09:16:02
After concatenation:
IA9jhabxRVg0kGTDLm0pFKOqoI6eJ8xnUJifRIOy2U79aykdOhfwJ4croJO4IuxH1USD2
.00test item1.00test item 21.002007-09-05.09:16:02
After MD5 Hash:
fc654595755ab9af18bed95714fb6423
An example HTTP GET request corresponding to the above checksum. Note,
that values are URL Encoded if you are doing HTTP GET.
https://securehost/ppp/purchase.do?checksum=fc654595755ab9af18bed9571
4fb6423&time_stamp=2007-09-
05.09%3A16%3A02&merchant_site_id=2302&merchant_id=1&item_amount_1=1.0
0&item_name_1=test+item&total_amount=2.00&currency=USD&numberofitems=
2&item_amount_2=1.00&item_name_2=test+item+2
© 2007 GTS Online Limited. All Rights Reserved.
11

Return output
Once the payment process is completed by either of the following ways:
• Transaction approved and completed usefully. The end user is
redirected by the Payment Page to the Merchant Success URL.
• Transaction was cancelled by the end user, which triggered the
Payment Page system to redirect the end user to the Merchant
Cancel Page.
• Transaction failed and redirected to the Merchant Cancel Page.
The redirection to either of the merchant URLs are redirected with HTTP GET
parameters which are divided to four following groups (for the full list please
refer to 4. Input parameters list):
1. Transaction parameters. Information regarding the parameter itself:
transaction id, amount, statuses & errors fields.
2. Payment method information. Information regarding the payment
method chosen by the end user. E.g. for Credit Card number it will be
his name on card, expiration date and four last digits of the card
number.
3. Personal information. End user personal information such as names,
address & contact details.
In addition to these parameters there is also a Returned Checksum
Parameter. Similar to the Checksum Input parameter it is an MD5 hash of
several concatenated parameters, this time output parameters.
The importance of this checksum is to make sure that curtail information passed from
the Payment Page back to the merchant site are not compromised by the end user for
his own benefit.
Checksum generation how to
Step I: concatenate the hashed values
The checksum is concatenating the following parameters, in the following
order:
© 2007 GTS Online Limited. All Rights Reserved.
12

- secret - a password string which will provided to by Gate2shop. This
is the only parameter which is not also an input parameter.
- TransactionID.
- ErrCode
- ExErrCode
- Status
Comments:
* The concatenation must be in the mentioned order
* Values are case sensitive and should be identical to the equivalent
parameter in the http request.
* No delimiter between the concatenated values
* Formula: string before MD5 hashing should be concatenated as follows
secret + transactionID + ErrCode + ExErrCode + Status
Step I: hash the concatenated value
After the values were concatenated you will need to run the value through an
MD5 algorithm function, the result will be the checksum value – a
hexadecimal value you will have to submit to the payment page.
© 2007 GTS Online Limited. All Rights Reserved.
13

3. Input parameters list
All numeric input parameters, should be presented as Strings, when making the actual
HTTP request to Gate2shop.
IMPORTANT: All parameters are lower case an are case sensitive!
Input Parameter Type Size Mandatory Explanation
merchant_site_id Number 64bits
merchantIp String Char(15)
merchant_id Number 64bits
checksum String Char(102
400)
time_stamp String Char(19)
currency String Char(3)
total_amount Double 64 bits
numberofitems Number 32bits
merchant_unique_id String Char(64)
invoice_id String Char(400)
total_tax Double 64 bits
yes
no
yes
Yes
Yes
Yes
Yes
depends
No
No
No
The ID, provided by Gate2shop,
which uniquely defines a particular
merchant customization.
The IP address of the merchant site. If
this IP address is not allowed for the
merchant site, the request is canceled.
The unique merchant id supplied by
Gate2shop.
Checksum of the transaction. See the
examples and the Integration guide.
Time stamp of the request.
Format is yyyy-MM-dd.HH:mm:ss
and the time zone is GMT.
The currency (USD, EUR) of the
transaction.
This is the total amount of money for
the transaction. This is the actual
amount that user will be charged
with.
Number of items that will be processed.
If you are submitting just one item, this
parameter can be omitted, because it
has a default value of 1. If you are
submitting more than one item, you
need to specify exactly the count of
your items.
Merchant supplied ID, which identifies
the transaction on merchant side. If the
Merchant does not have a system,
which tracks transactions, this could be
just a random number.
This parameter is used to identify
uniquely each invoice. If merchant
cannot supply such id, it can be just a
random number.
Total amount for taxes. Used only for
statistics purposes.
item_name_N String Char(400)
Yes
The name of the current item.
Currently only ISO-8859-1 character
set encoding is supported for the item
© 2007 GTS Online Limited. All Rights Reserved.
14

names.
item_number_N String Char(400) No Current item number.
quantity_N Number 64 bits
No
How many pieces of this item. If you
do not specify this parameter, the
system considers that the quantity is 1
item_amount_N Double 64 bits Yes The cost of the item. Statistics only.
shipping_N Double 64 bits No Shipping per item – statistics only.
payment_method String Char(256)
No
The payment method such as visa,
maestro, ach etc.
Credit Card Data
Token String Char(512) No Credit card token.
cc_card_number String Char(20) Only When token
is being used – the
masked card
number
Credit card number.
cc_name_on_card String Char(70) No Name on credit card.
cc_exp_year Number 2 digits
cc_exp_month Number 2 digits
cc_cvv2 Number 3 or 4
digits
No
No
No
Credit card expiration year in YY
format.
Credit card expiration month in MM
format.
CVV2 number of the credit card.
© 2007 GTS Online Limited. All Rights Reserved.
15

4. Output parameters list
Parameter name
Status
TransactionID
ClientUniqueID
ExErrCode
ErrCode
AuthCode
error
Reason
Explanation
Status of the executed transaction: APPROVED, DECLINED, etc. See
Gate2shop gateway specification.
The ID of the executed transaction assigned by Gate2shop.
Matches to the merchant_unique_id, supplied by Merchant in the initial request.
Extended error code if an error occurred while the transaction has been
executed.
Error code if an error occurred while the transaction has been executed.
Gateway authentication code..
Error (text) provided by the PPP system.
A reason that the gateway has returned if the transaction fails.
Payment parameters
Token
nameOnCard
cardNumber
expMonth
expYear
cvv2
Credit card token.
The name on the credit card used for the payment transaction.
The masked number of the credit card used for the payment transaction.
The expiration month(format MM) of the credit card used for the payment
transaction.
The expiration year(format YY) of the credit card used for the payment
transaction.
The masked CVV2 of the credit card used for the payment transaction.
Personal info parameters
first_name
last_name
email
address1
city
country
zip
phone1
First name.
Last name.
Email address.
Address.
City
Country
ZIP code.
Primary phone number
© 2007 GTS Online Limited. All Rights Reserved.
16