Page 1/22

API Integration Guide V1.0.4

Status: Published

Table Of Content

1. Version History Control

2. About This Document
3. Prerequisites
4.Merchant Integration
5. Payment Response Parameters
6. Security
7. Re-Query Transaction Status by CartID
8. Email Notification Disclaimer
9. Sample code in ASP
10. Check transaction History
11. Request for refunds
12. Common integration mistakes
Appendix A - Country Names - ISO 1366 Country Code
Appendix B - Currency Codes
Appendix C - Sample code to compare signature
Appendix D - Payment Status Code
Appendix E - Understanding LateStatus
Appendix F - China Bank ID
Appendix G - Thailand Bank List
Appendix H - Indonesia Bank List
Appendix I - Wechat Payment
Appendix J - Alipay Payment
Appendix K - QQCoin Payment
 Page 2/22

1. Version History Control

Version Date Remarks

1.0.0 2017-05-15 First version.

1.0.1 2017-09-29 Added Alipay and Wechat pay and QQCoin bv interface
example

1.0.2 2017-11-21 Corrected merchant site LoginURL at Section 5.2.1

1.0.3 2017-12-04 Section 6.2

Specifically highlight that Callback Signature Validation does not
need to be converted to uppercase before hashing

1.0.4 2018-09-25 Added returnURL to Section 4.2 Payment Request Parameters

2. About This Document

This document describes the following functionalities of Quicksilver Online Gateway

3. Prerequisites

Company ID
The CompanyID/Merchant Code provided by Quicksilver and use to uniquely identify the
Merchant.

Request URL
Merchant to provide Request URL to Quicksilver team ([email protected]).
Registered Request URL must be either IP or domain based.

Merchant Site Credential

Merchant can login to the Quicksilver BackEnd to check transactions and use other
management tools. The credential includes Login form URL, Login username and
Password.
 Page 3/22

4. Merchant Integration
4.1 URL
Post the following parameters to Quicksilver Post URL:
https://api.samopay.com/API/SamopayCheckCompany.asp

Direct Server to Server (get result in plain text)

https://api.samopay.com/API/s2sDirect.asp

4.2 Payment Request Parameters

Parameter Description Web-to-web Svr-to-svr Specification Example

requirement requirement

version version Required Required Numeric only According to the

number documentation
version number.
“2.3.7”

v_currency Currency Required Required Alphanumeric. “CNY”

code 3 characters.
Refer to
Appendix B

v_amount Amount to Required Required Numeric only 123.45

pay with 2
decimal.

v_firstname Buyer’s first Required Required Alphanumeric. “John”

name 18 characters.

v_lastname Buyer’s last Required Required Alphanumeric. “Sayor”

name 18 characters.

v_billemail Email Required Required Alphanumeric. “[email protected]

address 40 characters om”

v_billstreet Billing Street Required Required Alphanumeric. “No. 1 Stuart Road”

40 characters

v_billcity Billing City Required Required Alphanumeric. “Kuala Lumpur”

40 characters

v_billstate Billing State Optional Required Alphanumeric. “Wilayah

40 characters Persekutuan”

v_billpost Billing Optional Required Alphanumeric. “50000”

Postcode 40 characters
 Page 4/22

v_billcountry Billing Required Required Refer to “Malaysia”

Country Appendix A OR
“MY” (ISO 1366
Standard Country
Code)

v_billphone Phone Required Required Alphanumeric. “60388887777”

number 18 characters

v_bankid Direct To Optional Optional Alphanumeric. “ICBC”

Bank ID (For 5 characters
CNY CUP
gateway
only). Refer
to Appendix
E.

CID The Required Required Alphanumeric. “M104-C-100”

Merchant 50 characters
Code
provided by
Quicksilver
and
use to
uniquely
identify the
Merchant.

signature MD5 Required Required Alphanumeric. refer to 6.1 Posting

signature 100 characters Signature

v_CartID Unique Required Required Alphanumeric. Example:CartID001

merchant 255 characters
transaction
number /
Order ID

callBackURL transaction Required Required Alphanumeric. http://office.samopa

result will 255 y.com/samples/call
send to this characters. backURL.asp
URL

returnURL Payer will be Optional Not Alphanumeric. http://office.samopa

redirected Applicable 255 y.com/samples/retu
back to this characters. rnkURL.asp
URL

v_card_holder Card holder Not Required Required Alphanumeric. “John”

first name 50 characters.
 Page 5/22

v_card_holder Card holder Not Required Required Alphanumeric. “Sayor”

_last last name 50 characters.

v_cardnum Card number Not Required Required Alphanumeric. “111122223333444

16 characters. 4”
No spaces.

v_month Card Not Required Required Alphanumeric. “01”, “02” .. “12”

expiration 2 characters.
month

v_year Card Not Required Required Alphanumeric. “15” represent year

expiration 2 characters. 2015
year

v_cvv2 Card CVV Not Required Required Alphanumeric. “577”

number 4 characters.

EPKey Express Not Required Optional Alphanumeric.

Payment 128 characters
Key. If your
MID is
Express
Payments
enabled, an
EPKey is
returned to
you via
callbackURL
upon an
initial
successful
transaction
with all
parameters
provided. On
subsequent
transactions
using the
same card,
just post this
EPKey
parameter
and you can
omit the
credit card
details,
shipping and
billing info.
 Page 6/22

The EPKey is
valid for 40
days from
the date of
transaction
and it is
renewed for
another 40
days upon
subsequent
transactions
using this
key.

5. Payment Response Parameters

HTTPS POST response from Quicksilver after performing payment

5.1 Response Parameter (Response parameter for ReturnURL post and

callBack post)
Parameter name Title Description Example of data

mid Merchant ID This is the merchant ID of text “M104-C-196”

this transaction. This is
useful for our log files to
detect anomalies when we
try to debug the problem.

oid Order ID This is the unique order ID text “M104-PO-1234”

that identifies the
transaction.

cur Currency This is a 3 letter code of Example: USD

the currency.

amt Amount This is a numeric value of numeric “10000.00”

the transaction amount.
 Page 7/22

status Status “88 - Transferred” means text “88 - Transferred”

this transaction has been
successfully completed.
Other results mean
Declined or Failed
transaction status. Refer
to Appendix D.

latestatus latestatus This is the callback status text “88 - Transferred”

when a transaction
success after
30minute .(for web to web
gateway only)

cartid Cart ID This is the merchant text “12345678”

generated reference
number

signature signature This is MD5 signature that (refer to 6.1 Posting Signature
generate by our gateway Validation )

EPKey Express This parameter is only

Payment Key returned if you MID is
Express Payments enabled
and upon a successful
transaction with all the
required parameters
posted initially.

Descriptor Billing The billing descriptor

Descriptor

5.2 ReturnURL Post - Response via client browser

After processing the payment form, the server redirects the user back to the merchant’s site.
And show the payment result to user.
 Page 8/22

5.2.1 Merchants can set the URL in the merchant site.

Go to https://office.samopay.com.
Then login using the given merchant login ID and password.
Go to function “ReturnURL”.
Enter the full path where you want your customer to be redirected to and where you will
accept the payment status.

5.3 Callback Post - Response via backend

The callback POST is server to server where it does not depend on the user’s web browser
to return payment response data to merchant website. With this feature implemented, your
system still can get the payment status on the backend even if the merchant normal
response page fails to get status from Quicksilver which may be due to a closed web
browser, internet
connection timeout and etc.

On the request page, specify the callback post URL by using "callbackURL" parameter.

6. Security
● Signatures are used when posting a submission to Quicksilver. It is also used when
Quicksilver sends callback to the merchant.
● The callback page should implement checking signature checking, and etc to prevent
user hijack merchant system.
● · The callback page should not have session related code so that merchant
systems are still able accept payment status from Quicksilver even if the user
is logged out or the session is expired.
● · You need to implement a check to make sure
callback page to update the order so it won't update order status in
system more than 1 time.

6.1 Posting Signature Validation

This signature must be included in the request of every transaction. This hash signature
comprises of five fields:
1. SignatureKey (please ask from Quicksilver Support if you don’t have it, this key only share
with Quicksilver and Merchant only)
2. CID (Company ID/Merchant Code)
 Page 9/22

3. CartID
4. Amount ( For the Amount value, remove the “.” and “,” is any.)
5. Currency

The fields must set in the following order, (add separator semicolon “;” in every each of
value)
(SignatureKey & “;” & CID & “;” & CartID & “;” & Amount & “;” & Currency)

For an example,
SignatureKey = “abcdef”
CID = “M104-C-123”
CartID= “CART001”
Amount = “45.00” (take out the “.” And “,”)
Currency = “CNY”

The hash would be calculated on the following string (Convert all characters to uppercase
before hashing)
ABCDEF;M104-C-123;CART001;4500;CNY
The resulting signature value equals to (calculate by MD5 algorithm)
51805653a9ca99464c3e7af40d85e68a

6.2 Callback Signature Validation

During callback a field call signature is include,merchant should validate the signature to
prevent the system being hack by outsider. The signature for the response is a hash of the
following fields:

1. SignatureKey (please request from Quicksilver Support, this key is shared between
Quicksilver and Merchant only)
2. CID (Company ID/Merchant Code)
3. OID (BillNo / ReferenceNo from Quicksilver)
4. CartID
5. Amount ( For the Amount value, remove the “.” and “,” is any.)
6. Currency
7. Status

There fields must be set in the following order. Add separator semicolon “;” in every each of
value. (Does not need to be converted to uppercase before hashing
(SignatureKey & ";" & CID & ";" & OID & ";" & CartID & ";" & Amount & ";" & Currency &
";" & Status)
 Page 10/22

Example:
SignatureKey= “ABCDEF”
CID = “M104-C-123”
OID = “M104-PO-9999”
CartID = “CART001”
Amount = “45.00” (take out the “.” And “,”)
Currency = “CNY”
Status = “88 - Transferred”
The hash would be calculated on the following string:
ABCDEF;M104-C-123;M104-PO-9999;CART001;4500;CNY;88 - Transferred

The resulting has signature value equals to (using MD5 algorithm)

d5ac480eaf69a53e17912565f627cfb9

6.3 WHITELIST Server IP (COMPULSORY STEP)

It is COMPULSORY that you only accept callbacks from our given server IP address.(please
request the valid address from our Quicksilver support)

7. Query Transaction Status (COMPULSORY STEP)

IT IS COMPULSORY that merchant perform query status after
getting our callback
Merchant can get Payment Status by CartID in some cases if some transaction are not
confirm
To check transaction
https://api.samopay.com/api/getpaymentstatus.asp?cartID=cart12345&companyID=M104-C-
277&merchantKey=DSAS213&amount=1000.00

Example return result :

mid=M104-C-277&oid=M104-PO-4890&cur=CNY&amt=1000.00&status=66 -
Failed&cartid=6407333&createdDateTime=2013-03-20 14:36:13
 Page 11/22

8. Email Notification Disclaimer

Note: Email notifications are NOT guaranteed by Quicksilver as it is ISP dependent. E-mail
transmissions cannot be guaranteed to be secure or error-free as information could be
intercepted, corrupted, lost, destroyed, arrive late or incomplete.

9. Sample code in ASP

https://office.samopay.com/download/samopaySampleCode.zip

10. Check transaction History

If the merchant wishes to check the transaction status manually, the Purchase Clearance
listing shows the status of each transaction. Two way to check transaction
1. Login to Merchant site.
Go to https://office.samopay.com
and login using the Login ID and Password provided by Quicksilver.
After you have logged in, go to function “Transaction History” Page.
2. Login to eComm site.
Go to https://office.samopay.com/eCommLogin.asp
and login using the Company ID, Login ID and Password provided by Quicksilver.
After you have logged in, go to function “Purchase Clearance” Page. This is an optional
function. By default, this is not available. If you wish to have this option, then you can
request for it.

11. Request for refunds

Quicksilver allows merchant to request for refunds through the merchant site. Due to
different bank policies, only some refunds can be done this way. The refund process can be
immediate or as long as 24 hours, during normal banking hours. All refunds are full payment
amount.
Steps to initiate a refund using Quicksilver merchant site.
1. Login to Merchant Site (https://office.samopay.com)
2. Open Transaction History
3. Click on “Request refund” in the Refund Status column.
4. Enter reason of refund. This is optional.
5. Enter merchant password for confirmation.
6. Click on Request button.
7. The status of the refund will change to “Pending”.
8. When the request for refund process has been completed, the status will change to
“Completed”.
 Page 12/22

11.1 Refund API

Quicksilver allows you to request refunds via API. You can post your refund requests to this
API via the URL https://office.samopay.com/api/refund.asp. Prior to using this API, make
sure that the server IP address that you are posting from is in the Whitelist IP Addresses list
in the Quicksilver backoffice. To do this, login to Quicksilver backoffice and click on Whitelist
IP Addresses. Below are the parameters for this API:

Parameter Title Description Example of data

name

cid Merchant This is the merchant ID of this transaction. This text “M104-C-
ID identifies you as a merchant in the system. 196”

oid Order ID This is the unique order ID that identifies the text “M104-PO-
transaction. 1234”

cur Currency This is a 3 letter code of the currency. Example: USD

amt Amount This is a numeric value of the transaction amount. numeric

“10000.00”

cartid Cart ID This is the merchant generated reference number text

“12345678”

signature signature This is MD5 signature that is generated as below: text

MD5(UCase(SignatureKey & ";" & cid & ";" & oid
& ";" & cartid & ";" &
Replace(Replace(FormatNumber(CDbl(amt), 2),
",", ""), ".", "") & ";" & cur))
You will need to obtain the SignatureKey from
Quicksilver.

This API returns the following statuses:

1. FAILED - <description>
a. This error is returned when you post invalid parameters to the API
2. Status=Pending
a. This status means that your API request is successful and the
transaction is in the process of being refunded

3. Status=00 – Refund Successful

a. This status means your transaction has been refunded successfully
 Page 13/22

4. Status=01 – Refund Failed

a. This status means that refund has failed for your transaction
If you receive the status “Status=Pending”, a callback will be made to the same callbackURL
that you specified when posting the transaction. The status will be as in (3) or (4) above. The
following are the parameters for the callback:

Parameter Title Description Example of data

name

cid Merchant This is the merchant ID of this transaction. This text “M106-C-
ID identifies you as a merchant in the system. 196”

status Refund This is the status of the refund. 00 – Refund

Status Successful
Or
01 – Refund
Failed

oid Order ID This is the unique order ID that identifies the text “M106-PO-
transaction. 1234”

cur Currency This is a 3 letter code of the currency. Example: USD

amt Amount This is a numeric value of the transaction amount. numeric

“10000.00”

cartid Cart ID This is the merchant generated reference number text

“12345678”

signature signature This is MD5 signature that is generated as below: text

MD5(UCase(SignatureKey & ";" & cid & ";" & oid
& ";" & cartid & ";" &
Replace(Replace(FormatNumber(CDbl(amt), 2),
",", ""), ".", "") & ";" & cur & ";" & status))
You will need to obtain the SignatureKey from
Quicksilver.

12. Common integration mistakes

1) Expiry year format
The expiry year is 2-digit, not 4-digit.
Example, “2014” is not correct. It should be “14”
2) Cart ID is required and should be unique
 Page 14/22

Appendix A - Country Names

These country names can be used in the selection options for the payment form. Please
take note of the spaces and “.” and brackets. They have to be exactly the same.

ALBANIA CAMBODIA FAEROE ISLANDS

ALGERIA CAMEROON FIJI
AMERICAN SAMOA CANADA FINLAND
ANDORRA CANARY ISLANDS FRANCE
ANGOLA CAPE VERDE FRENCH GUIANA
ANGUILLA CAYMAN ISLANDS FRENCH POLYNESIA
ANTIGUA & BARBUDA CENTRAL AFRICAN REPUBLIC GABON
ARGENTINA CHAD GAMBIA
ARMENIA CHILE GEORGIA
ARUBA CHINA GERMANY
AUSTRALIA COLOMBIA GHANA
AUSTRIA CONGO GIBRALTAR
AZERBAIJAN COOK ISLAND GREECE
AZORES COSTA RICA GREENLAND
BAHAMAS COTE D'IVOIRE (IVORY COAST) GRENADA
BAHRAIN CROATIA GUADELOUPE
BANGLADESH CURACAO GUAM
BARBADOS CYPRUS GUATEMALA
BELARUS CZECH REPUBLIC GUERNSEY
BELGIUM DENMARK GUINEA
BELIZE DJIBOUTI GUINEA-BISSAU
BENIN DOMINICA GUYANA
BERMUDA DOMINICAN REPUBLIC HAITI
BOLIVIA ECUADOR HOLLAND
BONAIRE EGYPT HONDURAS
BOSNIA EL SALVADOR HONG KONG
BOTSWANA ENGLAND HUNGARY
BRAZIL EQUATORIAL GUINEA ICELAND
BRITISH VIRGIN ISLES ERITREA INDIA
BRUNEI ESTONIA INDONESIA
BULGARIA ETHIOPIA IRELAND
BURKINA FASO ISRAEL
BURUNDI ITALY

...continue
 Page 15/22

JAMAICA MONACO RUSSIA

JAPAN MONGOLIA RWANDA
JERSEY MONTSERRAT SABA
JORDAN MOROCCO SAIPAN
KAZAKHSTAN MOZAMBIQUE SAN MARINO
KENYA N. MARIANA ISLANDS SAUDI ARABIA
KIRIBATI NAMIBIA SCOTLAND
KOSRAE NEPAL SENEGAL
KUWAIT NETHERLANDS SEYCHELLES
KYRGYZSTAN NETHERLANDS ANTILLES SIERRA LEONE
LAOS NEW CALEDONIA SINGAPORE
LATVIA NEW ZEALAND SLOVAKIA
LEBANON NICARAGUA SLOVENIA
LESOTHO NIGER SOLOMAN ISLANDS
LIBERIA NIGERIA SOUTH AFRICA
LIECHTENSTEIN NORFOLK ISLAND SOUTH KOREA
LITHUANA NORTHERN IRELAND SPAIN
LUXEMBOURG NORWAY SRI LANKA
MACAU OMAN ST. CHRISTOPHER
MACEDONIA PAKISTAN ST. CROIX
MADAGASCAR PALAU ST. EUSTATIUS
MADEIRA PANAMA ST. JOHN
MALAWI PAPUA NEW GUINEA ST. KITTS & NEVIS
MALAYSIA PARAGUAY ST. LUCIA
MALDIVES PERU ST. MAARTEN
MALI PHILIPPINES ST. MARTIN
MALTA POLAND ST. THOMAS
MARSHALL ISLANDS PONAPE ST. VINCENT/GRENADINE
MARTINIQUE PORTUGAL ST.BARTHELEMY
MAURITANIA PUERTO RICO SURINAME
MAURITIUS QATAR SWAZILAND
MEXICO REUNION SWEDEN
MICRONESIA ROMANIA SWITZERLAND
MOLDOVA ROTA SYRIA

… continue

TAHITI YEMEN VANUATU

TAIWAN TURKMENISTAN VATICAN CITY STATE
 Page 16/22

TAJIKISTAN TURKS & CAICOS ISLANDS VENEZUELA

TANZANIA TUVALU VIETNAM
THAILAND UGANDA VIRGIN GORDAWALES
TINIAN UKRAINE WALLIS & FUTUNA ISLANDS
TOGO UNION ISLAND WESTERN SAMOA
TONGA UNITED ARAB EMIRATES YAPYUGOSLAVIA
TORTOLA UNITED KINGDOM ZAMBIA
TRINIDAD & TOBAGO UNITED STATES ZIMBABWE
TRUK URUGUAY MYANMAR
TUNISIA US VIRGIN ISLANDS OTHERS
TURKEY UZBEKISTAN

ISO 1366 Country Code

Quicksilver also support standard ISO 1366, 2-alphabet country code
Example :
1. “AF” is same as “AFGHANISTAN” Country
2. “AL” is same as “ALBANIA” Country
Standard Country Code please refer to :
http://www.iso.org/iso/home/standards/country_codes/country_names_and_code_elements.
htm
 Page 17/22

Appendix B - Currency Codes

USD United States - Dollar

CNY China - Renminbi

MYR Malaysia - Ringgit

SGD Singapore - Dollar

IDR Indonesia - Rupiah

THB Thailand - Baht

EUR Europe - Euro dollar

GBP United Kingdom - Sterling pound

JPY Japan - Yen

AUD Australia - Dollar

NOK Norwegia - Krone

CAD Canada - Dollar

SEK Sweden - Krona

 Page 18/22

Appendix D - Payment Status Code

Code Status Description

0 Payment Declined

2 Card IP EMAIL-BLACK LIST

3 Transaction amount limit

5 IP Duplicate

6 Email Duplicate

7 Card Duplicate

8 Browser Duplicate

9 High risk transaction

10 MID haven register

12 Invalid Currency code

13 Invalid Md5info

15 MID not open

16 MID channel not open

17 Card bin blacklisted

18 Browser Duplicate

19 Transaction processing, please check status in later

22 (web-to-web) Pending

25 Message error

26 Amount over limit

30 (svr-to-svr) Phone more than 1 times.Daily limit reached

30 (web-to-web) Browser Time Out

66 (web-to-web) Failed

11 Pending

88 Transferred

70 Timeout
 Page 19/22

Appendix E - Understanding LateStatus

This appliess to China eBanking only
When a user is directed to Quicksilver China eBanking site, the status of the transaction is
“22 - Pending”. When the user completed the payment process at the bank site, the status
of the transaction changes to “88 - Transferred”.

However, what happen when the user’s internet connection failed, or the bank site is down
or the user decided to discontinue the payment process? We cannot allow the transaction
status to remain as “22 - Pending” forever. Therefore, we have created a timeout function.
When a transaction status remains as “22 - Pending” longer than the timeout period, it will
automatically be changed to “66 - Failed”. Please note that this is an assumption that the
transaction has failed.

In exceptional circumstances, a transaction may change to “88 - Transferred” after the

timeout period. This is called LateStatus. We have 2 additional column in our Transaction
History reports. They are LateStatus and LateStatusDateTime. When a LateStatus occurs,
no Callback will be sent to the merchant server. But a ReturnURL may happen.
 Page 20/22

Appendix F - China Bank ID

Bank ID China Bank Name

ICBC 工商银行

ABC 农业银行

BOC 中国银行

CCB 建设银行

CMB 招商银行

SPDB 浦发银行

BCOM 交通银行

PSBC 邮政储蓄银行

ECITIC 中信银行

CMBC 民生银行

CEBB 光大银行

HXB 华夏银行

CIB 兴业银行

SHB 上海银行

SPABANK 平安银行

BOB 北京银行

NBB 宁波银行

WECHAT 微信支付
 Page 21/22

Appendix G - Thailand Bank List

Thailand banks are selected via web. Pre-selection is not possible. The following banks are
available in the web selection.

1. SCB
2. Krungthai
3. Krungsri
4. Bangkok Bank
5. UOB

Appendix H - Indonesia Bank List

1. Mandiri
2. Permata ATM
3. Permata Netpay

Appendix I - Wechat Gateway

Wechat gateway interface (interface might change in future)

 Page 22/22

Appendix J - Alipay Gateway

Alipay gateway interface (interface might change in future)

Appendix K - QQCoin Gateway

QQcoin gateway interface (interface might change in future)

The number of active banks can be increased or reduced without prior notice. As of the
publishing of this document, the banks listed above are active.

---End of document ---