Tài liệu tích hợp website

1. Update history

Version	Date	Content	Editor
2.1	11/03/2021	Update and supplement information	Le Thanh Tung

2. Integrated demo

2.1. Introduction

This is a document describing the payment connection between the VTC Pay portal as a payment unit and Merchant Shop (partner's system) as a sales unit, using the online payment function of VTC Pay via VTC Pay Ewallet and bank accounts (domestic and international internet banking)

This document describes functions which are necessary for integration, information transmission between two parties’ systems

This document describes database stream that interacts between two systems in transaction process

Definition of data exchange standards, safety solutions as well as authenticating transaction source

2.2. Alpha Test Parameters

VTC Pay web address to register website integration, check transaction history:

https://alpha1.vtcpay.vn/wallet/

Url sending order payment information :

https://alpha1.vtcpay.vn/portalgateway/checkout.html

Merchant's receiving account

Account:  0963465816
Password: Aa@123456
OTP: 123456

2.3. Golive parameters

Website VTC Pay:

https://vtcpay.vn/

Url sending order payment information:

https://vtcpay.vn/bank-gateway/checkout.html

Note:Alpha test and Golive parameters are different, therefore, in this mode, Merchant need:
- Have a VTC Pay account to create an integrated website and use it as a Merchant's receiving account
- Created integrated website

3. Website Integration Registration Tutorials

3.1. Guide To Merchant Profile Registration

Step 1

Merchant log in to your receiving account, select "Website integration" in the "Payment integration" section.

Step 2

In "Integrated Website", fill all required information and select "Confirm"

Step 3

Now, your profile is pending status. Please contact support to have your profile reviewed as quickly as possible

3.2.Guide to WebsiteID Registration

To be able to integrate payment through the payment gateway VTC Pay, Merchant needs to register for website integration information. VTC Pay will manage the integrated websites of Merchants.

Here are the steps to create an integrated website:

Step 1

Merchant log in to your receiving account, select "Website integration" in the "Payment integration" section.

Step 2

Select "Add New" in the integrated list admin section

Step 3

Fill out website integration information.

Note:

Url Receiving: the address that receives order payment transaction result from VTC Pay according to POST. As in the example, it should be http://www.kidsplaza.vn/listen.html

If Url Redirect is not on order, VTC shall redirect customers to Url Receiving.

Website Secret Key: As information added when creating signature by SHA256 . Secret Key must include numbers, uppercase letter, lowercase letter, and have at least 16 characters.

Transaction Fees: Merchants choose either buyers or sellers to be charged. Ex: A $100 oder with fee of $3, in case:
- Sellers be charged: Buyers spend $100, Sellers get $(100-3).
- Buyers be charged: Buyers spend $(100+3), Sellers get $100.

For a Merchant account on the provided alpha test environment, profes are already available, so Merchant does not need to create a new profile for the account. However, when golive, Merchant needs to create a profile before you can proceed to create and sign up for website integration. Refer to the GUIDE TO CREATE PROFILE FOR MERCHANT ACCOUNT!

4. Open-source Integration

Integrating VTC Pay Ewallet and Payment Gateway for CMS system, open source: Allows displaying the payment button via the VTC Pay payment gateway on all products and services of the website created from platform after:

5. Programming Payment Integration

5.1. Payment Diagram using bank account

5.2. Merchant Request Parameters

5.2.1. Merchant request parameters

Field	Style	Compulsion (*)	Description
`amount`	`double`	Y	Total amount of payment: - VND: rounded to 1 - USD: take 2 numbers after the comma
`bill_to_address`	`String(100)`	N	Address of customer (number, street, etc.)
`bill_to_address_city`	`String(100)`	N	City
`bill_to_email`	`String(100)`	N	Email of customer
`bill_to_forename`	`String(50)`	N	Name (Ex: Hung)
`bill_to_phone`	`String(30)`	N	Phone number of customer
`bill_to_surname`	`String(50)`	N	Surname/Family name (Ex: Nguyen Van)
`country`	`String(5)`	N	Nation of Customers. Transmitting country code value is listed as appendix
`currency`	`string(5)`	Y	Payment currency: - VND - USD
`customerID`	`string`	N	The merchant's customer identification code in case the merchant wants to create a customer payment card link on the VTC Pay payment portal for the next payment. For details see section 5.2.2. Payment and save linked bank
`language`	`string`	N	Language displayed on VTC site. If not transmitted, Vietnamese is default: vi: Vietnam en: English
`payment_type`	`string`	N	Payment type. Transmitting the following: VTC Pay: payment by VTC Pay balance DomesticBank: payment with only domestic bank InternationalCard: payment with only international card. In case of payment with specific bank, transmitting Bank code value is listed as appendix
`postcode`	`String(50)`	N	Postcode of city or province’s customers
`reference_number`	`string(30)`	Y	Ref. number of integrating partner. This number is unique and is the base of reconciling and monitoring
`transaction_type`	`string`	N	Default value is: sale
`url_return`	`string`	N	Merchant’s Url that VTC shall redirect customers after finishing transaction. If not transmitted, Url when registering to create website
`website_id`	`int`	Y	Website ID code which is created by partner on VTC system
`signature`	`string`	Y	Signature (SHA-256, Uppercase). Text to create a signature includes the value of parameters (plaintext, non-encode) and SecretKey. In the order of alphabet and divide with “\|”. Ex: plaintext = string.Format("{0}\|{1}\|{2}\|{3}\|{4}", amount, currency, reference_number, website_id, Security_Key);
`state`	`String(5)`	N	State of Customers. Transmitting State code value is listed as appendix

(*). Compulsory Fields :
Y : Must transmit to url.
N : Maybe null, empty or no need.

Signature: This is an example with full parameters in the following order:


                        amount|bill_to_address|bill_to_address_city|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|country|currency|customerid|language|payment_type|postcode|reference_number|transaction_type|url_return|website_id|SecurityCode|state

SecurityCode: Passcode created in Website Integration Registration Process.
In case of missing some parameters (ex: bill_to_address_city, transaction_type, url_return), text to generate signature should be like that:


                        amount|bill_to_address|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|currency|customerid|language|payment_type|reference_number|website_id|SecurityCode

(*). Các tham số có trường Bắt buộc là:
Y : Phải truyền giá trị tham số này trên url
N : Có thể truyền null, empty hoặc không cần truyền trên url

Trường signature: Nếu truyền đủ hết các tham số thì text để tạo chữ ký sẽ như sau là giá trị các tham số và secreKey xếp lần lượt như sau:


                      
                        amount|bill_to_address|bill_to_address_city|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|country|currency|customerid|language|payment_type|postcode|reference_number|transaction_type|url_return|website_id|SecurityCode|state

SecurityCode(Mã bảo mật): Giá trị của trường Mã bảo mật lúc tạo website
Trường hợp có một số tham số không truyền trên url request thì text tạo chữ ký không có tham số đó.
Ví dụ, trên request thanh toán đơn hàng không có tham số bill_to_address_city, transaction_type, url_return. Khi đó text để ký sẽ như sau:


                      
                        amount|bill_to_address|bill_to_email|bill_to_forename|bill_to_phone|bill_to_surname|currency|customerid|language|payment_type|reference_number|website_id|SecurityCode

5.2.2. Payment and save linked bank

In case the merchant transmits an additional customer identification code (customerID), when the customer makes payment on the VTC payment portal for the first time, he or she will be able to choose to save the card link for future payments. From the second payment, customers do not need to re-enter card information but only need to authenticate OTP to complete payment.

- First payment:

- Payment interface from the second time the customer identifier is available:

5.3. Returned result

5.3.1. Returned result according to POST(server to server)

HTTP POST is the connection form of Server to Server. Data will be posted from VTC Pay server to receiving site at Merchant server that’s the site when creating website integration. VTC always posts transaction result to this receiving site:

=> It helps Merchant receive the result all time, avoid not receiving the result if using HTTP Get, in case customers turn off their browser in transaction process or problems of the internet connection.

=> It helps Merchant receive the final result, special with verified transactions that need to be approved by VTC admin.

=> It helps merchant compare with results by GET method to avoid risk

Parameters of order payment result that VTC Pay return to Merchant’s site:

Field	Style	Compulsion	Description
`data`	`string`	Y	amount\|message\|payment_type\|reference_number\| status\|trans_ref_no\|website_id
`signature`	`string`	Y	Encrypt SHA256(UTF8 Encoding) fields based on the following format: amount\|message\|payment_type\|reference_number\| status\|trans_ref_no\|website_id\|secret_key secret_key: Secret key you entered when creating website

Caution: Upon receiving the returned result, the merchant must verify that the returned amount matches the transferred amount. If there is no match, the returned result is not valid, you need to coordinate with VTC to check again

5.3.2. Returned result according to HTTP GET

After finishing checkout process, VTC Pay shall redirect customer to receving site of Merchant, and return the payment result to Merchant at the same time through parameters on Url.

Details of returned parameters:

Field	Style	Compulsion	Description
`amount`	`int`	Y	Value of order, is the amount money of order in Merchant’s system
`message`	`string`	N	Additional information
`payment_type`	`string`	N	Payment form that customer process transaction
`reference_number`	`string(50)`	Y	Order ref. that Merchant send
`status`	`int`	Y	As in Appendix
`trans_ref_no`			VTC ref. code
`website_id`	`int`	Y	Website’s code registered on VTC Pay, in Website integrating managing session on VTC Pay
`signature`	`string`	Y	Encrypt SHA256(UTF8 Encoding) fileds in the order of alphabet, and add secret_key in the end.Respectively: Amount\|message\|paymentType\|reference_number\| status\|trans_ref_no\|website_id\|secret_key secret_key: secret key you entered when creating website

Caution: Upon receiving the returned result, the merchant must verify that the returned amount matches the transferred amount. If there is no match, the returned result is not valid, you need to coordinate with VTC to check again.

6. MERCHANT API

6.1. API look up sales history information

-API information: Look up sales history information

 Alpha test:  https://vtcpay.vn/bank-gateway/api/AccountApi/MerchantSaleHistoryGetList
 Live:  https://vtcpay.vn/bank-gateway/api/AccountApi/MerchantSaleHistoryGetList
 Key sign:  1!2@3#4$5%
 Sign:  MD5
 Method:  POST

- Request Data:

 RevceiverAccount: VTC Pay account
 intergratedID:  AppID or WebsiteID
 merchantType:  WEBSITE or APP
 fromDate:  Start date to get information (2017-01-01)
 toDate:  End date to get information (2017-11-01)
 sign:  MD5(keysign + RevceiverAccount + intergratedID + merchantType + fromDate + toDate + secret key web/app)

- Response Data:

- Error description:

 ResponseCode = 1:  Get sales history successful
 ResponseCode != 1: Get sales history fail
 ResponseCode = -50: The account does not exist
 ResponseCode = -1002:  Wrong sign
 ResponseCode = -601/-602:  Incorrect integration parameters
 ResponseCode = -603:  Date invalid
 ResponseCode = -604:  Max 31 days
 ResponseCode = -605: Website does not exist with account
 OrderStatus = 1  Order successful
 OrderStatus = 2  Order failed
 OrderStatus = 3  Order awaiting approval

6.2. API look up transaction details

-API information: look up transaction details

 Alpha test:  https://vtcpay.vn/bank-gateway/api/AccountApi/VTCPayGetOrderStatus
 Live:  https://vtcpay.vn/bank-gateway/api/AccountApi/VTCPayGetOrderStatus
 Key sign:  1!2@3#4$5%
 Sign:  MD5
 Method:  POST

- Request Data:

 RevceiverAccount:  VTC Pay account
 intergratedID:  AppID or WebsiteID
 merchantType:  WEBSITE hoặc APP
 sign:  MD5(keysign + RevceiverAccount + intergratedID + merchantType + secret key web/app)

- Response Data:

- Error description:

 ResponseCode = 1:  Success
 ResponseCode != 1:  Fail
 ResponseCode = -50: The account does not exist
 ResponseCode = -1002:  Wrong sign
 ResponseCode = -600/-601/-602:  Incorrect integration parameters
 ResponseCode = -603:  List merchant order code is empty
 ResponseCode = -604:  App does not exist with account
 ResponseCode = -605: Website does not exist with account
 ResponseCode = -701/-703: Order not exists
 ResponseCode = -705: Merchant not exists this order
 Status = 1:  Success
 Status = 2:   Fail
 Status = 3: Pending
 Status = 4:  Refunded
 Status = 5:  Waiting for refund approval
 Status = 6:  Cancel a refund request
 Status <= 0:  Invalid partner code

6.3. API refund

-API information: Submit a refund request

 Alpha test:  https://vtcpay.vn/bank-gateway/api/AccountApi/RefundMoneyVTC
 Live:  https://vtcpay.vn/bank-gateway/api/AccountApi/RefundMoneyVTC
 Key sign:  1!2@3#4$5%
 Sign:  MD5
 Method:  POST

- Request Data:

 RevceiverAccount:  Tài khoản ví
 intergratedID:  ID tích hợp AppID hoặc WebsiteID
 merchantType:  WEBSITE hoặc APP
 sign:  MD5(keysign + RevceiverAccount + intergratedID + merchantType + secret key web/app)

- Response Data:

- Error description:

 ResponseCode = 100:  Successful, refunded
 ResponseCode = 10:  The request refund has submitted successfully. however we need to manual approve because towards the bank issue
 ResponseCode = 1:  Submit refund request successfully, waiting for approval
 ResponseCode = -1:  Failed to submit refund request
 ResponseCode = -2:  You have sent a refund request. Please wait for the administrator to process!
 ResponseCode = -3:  The order has been fully refunded, you cannot submit any further requests
 ResponseCode = -103:  The refund amount exceeds the order value
 ResponseCode = -101/-102/-104/-1001:  Submit refund request not successful. Please try again later
 ResponseCode = -99:  System error, please try again later
 ResponseCode = -50: The account does not exist
 ResponseCode = -1002:  Wrong sign
 ResponseCode = -600/-601/-602:  Incorrect integration parameters
 ResponseCode = -603:  List merchant order code is empty
 ResponseCode = -604:  App does not exist with account
 ResponseCode = -605: Website does not exist with account
 ResponseCode = -700:  Refund info invalid
 ResponseCode = -701/-703: Order not exists
 ResponseCode = -704: Refund amount invalid
 ResponseCode = -705: Merchant not exists this order
 ResponseCode <= 0:  System error

6.4. Returned result description

Parameters of order payment result that VTC Pay return to Merchant’s site:

Field	Style	Compulsion	Description
`orderID`	`long`	Y	VTC order ID
`ordercode`	`string`	Y	Order ref. that Merchant send
`partnerRefTransID`	`string`	Y	Order ref. that Merchant send
`transactionID`	`long`	Y	VTC transaction ID

7. Appendix

7.1. Payment alpha test account information

- VTC Pay account:

Account:  0357758300
Password: Abcd1234
OTP: 123456

- Visa card :

Card number: 4111 1111 1111 1111 
Zip/Postal Code:  123 
CardType:  Visa 
CVN:  123 
Exprition Date:  01/2030 
Other fields:Whatever in correct format

- Customer’s Techcombank Card test order payment by domestic card:

Card number: 9704 0000 0000 0018 
Card name:  NGUYEN VAN A 
OTP:  otp 
Open date:  03/07 (MM/YY)

7.2. Appendix of order payment

Status	Mean	Note
`0`		Transaction status of initializing
`1`	`SUCCESS`	Successful transaction
`7`	`REVIEW`	Payment account of customer is deducted but Merchant’s account is not credited.Payment admin department of VTC will approve to decide transaction is successful or failed.
`-1`	`FAIL`	Failed transaction
`-9`	`FAIL`	Customer cancel transaction
`-3`	`FAIL`	VTC admin cancel transaction
`-4`	`FAIL`	Account not eligible for transaction(Locked, not registered for online payment ...)
`-5`	`FAIL`	Customer account balance(VTC Pay ewallet, bank account) is not sufficient to make payment
`-6`	`FAIL`	Transaction error at VTC
`-7`	`FAIL`	Customer enter wrong payment information(account information or OTP)
`-8`	`FAIL`	Exceed day transaction limit
`-22`	`FAIL`	Order payment value is too small
`-24`	`FAIL`	Order payment currency is not valid
`-25`	`FAIL`	Merchant’s VTC Pay receiving account does not exist
`-28`	`FAIL`	Lack of compulsory parameters in one online payment order
`-29`	`FAIL`	Request parameter is not valid
`-21`	`CHECK`	Duplicating transaction reference.May be because of duplicating solving is not good, poor internet connection, customer enter F5, or poor transaction code generating, partner must check to get the final result of this transaction
`-23`	`CHECK`	WebsiteID does not exist
`-99`	`CHECK`	Undefined errors and transaction status.Must check to know if transaction is successful or not

7.3. Appendix of banks list

Bank code	Bank name
`VTCPAY`	VTC Pay E-Wallet
`BANKTRANSFERVIRTUAL`	Scan VietQR
`InternationalCard`	Payment by International Card (Visa\| Master\| JCB)
`DomesticBank`	Display all domestic bank
`Vietcombank`	JSC Bank for Foreign Trade of Vietnam - Vietcombank
`Techcombank`	Vietnam Technological and Commercial Joint- stock Bank - Techcombank
`MB`	Military Commercial Joint Stock Bank - MBBank
`Vietinbank`	Vietnam Joint Stock Commercial Bank for Industry and Trade - Vietinbank
`Agribank`	Vietnam Bank for Agriculture and Rural Development - Agribank
`DongABank`	DongA Joint Stock Commercial Bank - DongABank
`Oceanbank`	Ocean Commercial One Member Limited Liability Bank - Oceanbank
`BIDV`	Bank for Investment and Development of Vietnam - BIDV
`SHB`	Saigon – Hanoi Commercial Joint Stock Bank - SHB
`VIB`	Vietnam International Commercial Joint Stock Bank - VIB
`MaritimeBank`	Vietnam Maritime Commercial Joint Stock Bank - MaritimeBank
`Eximbank`	Vietnam Export Import Commercial Joint Stock Bank - Eximbank
`Master`	Master
`Visa`	Visa
`Jcb`	Jcb
`ACB`	Asia Commercial Joint Stock Bank - ACB
`HDBank`	Ho Chi Minh City Development Joint Stock Commercial Bank - HDBank
`NamABank`	Nam A Commercial Joint Stock Bank - NamABank
`SaigonBank`	Saigon Bank for Industry and Trade - SaigonBank
`Sacombank`	Saigon Thuong Tin Commercial Joint Stock Bank - Sacombank
`VietABank`	VietNam Asia Commercial Joint Stock Bank - VietABank
`VPBank`	Vietnam Prosperity Joint-Stock Commercial Bank - VPBank
`TienPhongBank`	Tien Phong Commercial Joint Stock Bank - TienPhongBank
`SeaABank`	Southeast Asia Commercial Joint Stock Bank - SeABank
`PGBank`	Petrolimex Group Commercial Joint Stock Bank - PGBank
`NCB`	National Citizen Bank - NCB
`GPBank`	Global Petro Commercial Joint Stock Bank - GPBank
`BACABANK`	Bac A Commercial Joint Stock Bank - BacABank
`OCB`	Orient Commercial Joint Stock Bank - OCB
`LienVietPostBank`	Lien Viet Post Joint Stock Commercial Bank - LienVietPostBank
`ABBANK`	An Binh Commercial Join Stock Bank - ABBank
`PVcomBank`	Vietnam Public Joint Stock Commercial Bank - PVcomBank
`BVB`	Bao Viet Joint Stock Commercial Bank - BaoVietBank
`SCBBank`	Sai Gon Joint Stock Commercial Bank - SCB
`KienLongBank`	Kien Long Commercial Joint Stock Bank - Kienlongbank
`VRB`	Vietnam - Russia Joint Venture Bank - VRB
`PublicBank`	Public Bank
`MoMo`	Momo
`ViettelPay`	Viettel Money
`ZaloPay`	Zalo Pay
`VNPAYQR`	VNPAYQR
`VNPTMoney`	VNPT Money
`AppotaPay`	Appota Pay
`ShopeePay`	Shopee Pay

7.4. Appendix of countries list

country code	country name
`AF`	Afghanistan AF
`AX`	Aland Islands AX
`AL`	Albania AL
`DZ`	Algeria DZ
`AS`	American Samoa (US) AS
`AD`	Andorra AD
`AO`	Angola AO
`AI`	Anguilla (UK) AI
`AQ`	Antarctica AQ
`AG`	Antigua and Barbuda AG
`AR`	Argentina AR
`AM`	Armenia AM
`AW`	Aruba AW
`AU`	Australia AU
`AT`	Austria AT
`AZ`	Azerbaijan AZ
`BS`	Bahamas BS
`BH`	Bahrain BH
`BD`	Bangladesh BD
`BB`	Barbados BB
`BY`	Belarus BY
`BE`	Belgium BE
`BZ`	Belize BZ
`BJ`	Benin BJ
`BM`	Bermuda (UK) BM
`BT`	Bhutan BT
`BO`	Bolivia BO
`BQ`	Bonaire, Sint Eustatius and Saba BQ
`BA`	Bosnia and Herzegovina BA
`BW`	Botswana BW
`BV`	Bouvet Island BV
`BR`	Brazil BR
`IO`	British Indian Ocean Territory IO
`VG`	British Virgin Islands (UK) VG
`BN`	Brunei Darussalam BN
`BG`	Bulgaria BG
`BF`	Burkina Faso BF
`BI`	Burundi BI
`KH`	Cambodia KH
`CM`	Cameroon CM
`CA`	Canada CA
`CV`	Cape Verde CV
`KY`	Cayman Islands (UK) KY
`CF`	Central African Republic CF
`TD`	Chad TD
`CL`	Chile CL
`CN`	China CN
`CX`	Christmas Island (AU) CX
`CC`	Cocos (Keeling) Islands (AU) CC
`CO`	Colombia CO
`KM`	Comoros KM
`CD`	Congo, Democratic Republic of the CD
`CG`	Congo, Republic of the CG
`CK`	Cook Islands (NZ) CK
`CR`	Costa Rica CR
`CI`	Côte D'Ivoire CI
`HR`	Croatia HR
`CU`	Cuba CU
`CW`	Curaçao CW
`CY`	Cyprus CY
`CZ`	Czech Republic CZ
`DK`	Denmark DK
`DJ`	Djibouti DJ
`DM`	Dominica DM
`DO`	Dominican Republic DO
`EC`	Ecuador EC
`EG`	Egypt EG
`SV`	El Salvador SV
`GQ`	Equatorial Guinea GQ
`ER`	Eritrea ER
`EE`	Estonia EE
`ET`	Ethiopia ET
`FK`	Falkland Islands (UK) FK
`FO`	Faroe Islands (DK) FO
`FJ`	Fiji FJ
`FI`	Finland FI
`FR`	France FR
`GF`	French Guiana (FR) GF
`PF`	French Polynesia (FR) PF
`TF`	French Southern Territories TF
`GA`	Gabon GA
`GM`	Gambia GM
`GE`	Georgia GE
`DE`	Germany DE
`GH`	Ghana GH
`GI`	Gibraltar (UK) GI
`GR`	Greece GR
`GL`	Greenland (DK) GL
`GD`	Grenada GD
`GP`	Guadeloupe (FR) GP
`GU`	Guam (US) GU
`GT`	Guatemala GT
`GG`	Guernsey GG
`GN`	Guinea GN
`GW`	Guinea-Bissau GW
`GY`	Guyana GY
`HT`	Haiti HT
`HM`	Heard Island and McDonald Islands HM
`VA`	Holy See (Vatican City) VA
`HN`	Honduras HN
`HK`	Hong Kong (CN) HK
`HU`	Hungary HU
`IS`	Iceland IS
`IN`	India IN
`ID`	Indonesia ID
`IR`	Iran IR
`IQ`	Iraq IQ
`IE`	Ireland IE
`IM`	Isle of Man IM
`IL`	Israel IL
`IT`	Italy IT
`JM`	Jamaica JM
`JP`	Japan JP
`JE`	Jersey JE
`JO`	Jordan JO
`KZ`	Kazakhstan KZ
`KE`	Kenya KE
`KI`	Kiribati KI
`KP`	Korea, Democratic People's Republic (North) KP
`KR`	Korea, Republic of (South) KR
`KW`	Kuwait KW
`KG`	Kyrgyzstan KG
`LA`	Laos LA
`LV`	Latvia LV
`LB`	Lebanon LB
`LS`	Lesotho LS
`LR`	Liberia LR
`LY`	Libya LY
`LI`	Liechtenstein LI
`LT`	Lithuania LT
`LU`	Luxembourg LU
`MO`	Macau (CN) MO
`MK`	Macedonia MK
`MG`	Madagascar MG
`MW`	Malawi MW
`MY`	Malaysia MY
`MV`	Maldives MV
`ML`	Mali ML
`MT`	Malta MT
`MH`	Marshall Islands MH
`MQ`	Martinique (FR) MQ
`MR`	Mauritania MR
`MU`	Mauritius MU
`YT`	Mayotte (FR) YT
`MX`	Mexico MX
`FM`	Micronesia, Federated States of FM
`MD`	Moldova Republic of MD
`MC`	Monaco MC
`MN`	Mongolia MN
`ME`	Montenegro ME
`MS`	Montserrat (UK) MS
`MA`	Morocco MA
`MZ`	Mozambique MZ
`MM`	Myanmar MM
`NA`	Namibia NA
`NR`	Nauru NR
`NP`	Nepal NP
`NL`	Netherlands NL
`AN`	Netherlands Antilles (NL) AN
`NC`	New Caledonia (FR) NC
`NZ`	New Zealand NZ
`NI`	Nicaragua NI
`NE`	Niger NE
`NG`	Nigeria NG
`NU`	Niue NU
`NF`	Norfolk Island (AU) NF
`MP`	Northern Mariana Islands (US) MP
`NO`	Norway NO
`OM`	Oman OM
`PK`	Pakistan PK
`PW`	Palau PW
`PS`	Palestinian Territories PS
`PA`	Panama PA
`PG`	Papua New Guinea PG
`PY`	Paraguay PY
`PE`	Peru PE
`PH`	Philippines PH
`PN`	Pitcairn Islands (UK) PN
`PL`	Poland PL
`PT`	Portugal PT
`PR`	Puerto Rico (US) PR
`QA`	Qatar QA
`RE`	Reunion (FR) RE
`RO`	Romania RO
`RU`	Russia RU
`RW`	Rwanda RW
`BL`	Saint Barthelemy BL
`SH`	Saint Helena (UK) SH
`KN`	Saint Kitts and Nevis KN
`LC`	Saint Lucia LC
`MF`	Saint Martin (French Part) MF
`PM`	Saint Pierre & Miquelon (FR) PM
`VC`	Saint Vincent and the Grenadines VC
`WS`	Samoa WS
`SM`	San Marino SM
`ST`	Sao Tome and Principe ST
`SA`	Saudi Arabia SA
`SN`	Senegal SN
`RS`	Serbia RS
`SC`	Seychelles SC
`SL`	Sierra Leone SL
`SG`	Singapore SG
`SX`	Sint Maarten (Dutch Part) SX
`SK`	Slovakia SK
`SI`	Slovenia SI
`SB`	Solomon Islands SB
`SO`	Somalia SO
`ZA`	South Africa ZA
`GS`	South Georgia & South Sandwich Islands (UK) GS
`SS`	South Sudan SS
`ES`	Spain ES
`LK`	Sri Lanka LK
`SD`	Sudan SD
`SR`	Suriname SR
`SJ`	Svalbard and Jan Mayen SJ
`SZ`	Swaziland SZ
`SE`	Sweden SE
`CH`	Switzerland CH
`SY`	Syria SY
`TW`	Taiwan TW
`TJ`	Taj ikistan TJ
`TZ`	Tanzania TZ
`TH`	Thailand TH
`TL`	Timor-Leste TL
`TG`	Togo TG
`TK`	Tokelau TK
`TO`	Tonga TO
`TT`	Trinidad and Tobago TT
`TN`	Tunisia TN
`TR`	Turkey TR
`TM`	Turkmenistan TM
`TC`	Turks and Caicos Islands (UK) TC
`TV`	Tuvalu TV
`UG`	Uganda UG
`UA`	Ukraine UA
`AE`	United Arab Emirates AE
`GB`	United Kingdom GB
`US`	United States US
`UM`	United States Minor Outlying Islands UM
`UY`	Uruguay UY
`UZ`	Uzbekistan UZ
`VU`	Vanuatu VU
`VE`	Venezuela VE
`VN`	Vietnam VN
`VI`	Virgin Islands (US) VI
`WF`	Wallis and Futuna (FR) WF
`EH`	Western Sahara EH
`YE`	Yemen YE
`ZM`	Zambia ZM
`ZW`	Zimbabwe ZW

7.5. Appendix of states list

state code	state name
`AL`	Alabama
`AK`	Alaska
`AS`	American Samoa
`AZ`	Arizona
`AR`	Arkansas
`CA`	California
`CO`	Colorado
`CT`	Connecticut
`DE`	Delaware
`DC`	District of Columbia
`FM`	Federated States of Micronesia
`FL`	Florida
`GA`	Georgia
`GU`	Guam
`HI`	Hawaii
`ID`	Idaho
`IL`	Illinois
`IN`	Indiana
`IA`	Iowa
`KS`	Kansas
`KY`	Kentucky
`LA`	Louisiana
`ME`	Maine
`MH`	Marshall Islands
`MD`	Maryland
`MA`	Massachusetts
`MI`	Michigan
`MN`	Minnesota
`MS`	Mississippi
`MO`	Missouri
`MT`	Montana
`NE`	Nebraska
`NV`	Nevada
`NH`	New Hampshire
`NJ`	New Jersey
`NM`	New Mexico
`NY`	New York
`NC`	North Carolina
`ND`	North Dakota
`MP`	Northern Mariana Islands
`OH`	Ohio
`OK`	Oklahoma
`OR`	Oregon
`PW`	Palau
`PA`	Pennsylvania
`PR`	Puerto Rico
`RI`	Rhode Island
`SC`	South Carolina
`SD`	South Dakota
`TN`	Tennessee
`TX`	Texas
`UT`	Utah
`VT`	Vermont
`VI`	Virgin Islands
`VA`	Virginia
`WA`	Washington
`WV`	West Virginia
`WI`	Wisconsin
`WY`	Wyoming
`AB`	Alberta
`BC`	British Columbia
`MB`	Manitoba
`NB`	New Brunswick
`NL`	Newfoundland and Labrador
`NT`	Northwest Territories
`NS`	Nova Scotia
`NU`	Nunavut
`ON`	Ontario
`PE`	Prince Edward Island
`QC`	Quebec
`SK`	Saskatchewan
`YT`	Yukon