Email: hotro@digipay.vn
Tài liệu này bao gồm những tài liệu kĩ thuật về API của DIGIPAY cũng như những hướng dẫn để tích hợp các dịch vụ của DIGIPAY
Mỗi merchant sử dụng API của DIGIPAY phải đăng ký với DIGIPAY IP của họ để kết nối với DIGIPAY, sau đó DIGIPAY sẽ cung cấp cho họ các thông tin dưới đây:
Protocol: Bảo mật HTTP sử dụng Phương pháp POST.
Option: Sử dụng Handshake Process : Merchant tiến hành các dịch vụ đã được xác minh & triển khai trên những URL riêng biệt, mà thông qua đó DIGIPAY gọi để xác nhận mỗi yêu cầu từ phía Merchant
Dữ liệu của mỗi tin nhắn từ phía Merchant gửi đến DIGIPAY và ngược lại sẽ phải được bảo mật bằng mật mã. Hãy tham khảo những ví dụ của chúng tôi để hỗ trợ việc triển khai việc tạo mã & giải mã dữ liệu từ tin nhắn
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;
public static string Encrypt(string key, string data)
{
data = data.Trim();
byte[] keydata = Encoding.ASCII.GetBytes(key);
string md5String = BitConverter.ToString(new MD5CryptoServiceProvider().ComputeHash(keydata)).Replace("-", "").ToLower();
byte[] tripleDesKey = Encoding.ASCII.GetBytes(md5String.Substring(0, 24));
TripleDES tripdes = TripleDESCryptoServiceProvider.Create();
tripdes.Mode = CipherMode.ECB;
tripdes.Padding = PaddingMode.PKCS7;
tripdes.Key = tripleDesKey;
tripdes.GenerateIV();
MemoryStream ms = new MemoryStream();
CryptoStream encStream = new CryptoStream(ms, tripdes.CreateEncryptor(),
CryptoStreamMode.Write);
encStream.Write(Encoding.ASCII.GetBytes(data), 0,
Encoding.ASCII.GetByteCount(data));
encStream.FlushFinalBlock();
byte[] cryptoByte = ms.ToArray();
ms.Close();
encStream.Close();
return Convert.ToBase64String(cryptoByte, 0, cryptoByte.GetLength(0)).Trim();
}
public static string Decrypt(string key, string dataen)
{
byte[] toEncryptArray = Convert.FromBase64String(dataen);
byte[] keydata = Encoding.ASCII.GetBytes(key);
string md5String = BitConverter.ToString(new MD5CryptoServiceProvider().ComputeHash(keydata)).Replace("-", "").ToLower();
byte[] tripleDesKey = Encoding.ASCII.GetBytes(md5String.Substring(0, 24));
TripleDES tripdes = TripleDESCryptoServiceProvider.Create();
tripdes.Mode = CipherMode.ECB;
tripdes.Padding = PaddingMode.PKCS7;
tripdes.Key = tripleDesKey;
tripdes.GenerateIV();
ICryptoTransform ict = tripdes.CreateDecryptor();
byte[] resultArray = ict.TransformFinalBlock(toEncryptArray, 0, toEncryptArray.Length);
tripdes.Clear();
return Encoding.ASCII.GetString(resultArray);
}
public static String getMD5(String sMessage)
{
byte[] defaultBytes = sMessage.getBytes();
try {
MessageDigest algorithm = MessageDigest.getInstance("MD5");
algorithm.reset();
algorithm.update(defaultBytes);
byte messageDigest[] = algorithm.digest();
StringBuffer hexString = new StringBuffer();
for (int i = 0; i < messageDigest.length; i++) {
String hex = Integer.toHexString(0xFF & messageDigest[i]);
if (hex.length() == 1) {
hexString.append('0');
}
hexString.append(hex);
}
return hexString.toString();
} catch (NoSuchAlgorithmException nsae) {
return null;
}
}
public static String Encrypt(String key,String data) throws Exception
{
Cipher cipher=Cipher.getInstance("TripleDES");
String keymd5 =getMD5(key).substring(0,24);
SecretKeySpec keyspec = new SecretKeySpec(keymd5.getBytes(),"TripleDES"); cipher.init(Cipher.ENCRYPT_MODE,keyspec);
byte[] stringBytes=data.getBytes();
byte[] raw=cipher.doFinal(stringBytes);
BASE64Encoder encoder = new BASE64Encoder();
String base64 = encoder.encode(raw);
return base64;
}
public static String Encrypt(String key,String data) throws Exception
{
Cipher cipher=Cipher.getInstance("TripleDES");
String keymd5 =getMD5(key).substring(0,24);
SecretKeySpec keyspec = new SecretKeySpec(keymd5.getBytes(),"TripleDES"); cipher.init(Cipher.ENCRYPT_MODE,keyspec);
byte[] stringBytes=data.getBytes();
byte[] raw=cipher.doFinal(stringBytes);
BASE64Encoder encoder = new BASE64Encoder();
String base64 = encoder.encode(raw);
return base64;
}
public static String Decrypt(String key,String data) throws Exception
{
Cipher cipher=Cipher.getInstance("TripleDES");
String keymd5 =getMD5(key).substring(0,24);
SecretKeySpec keyspec = new
SecretKeySpec(keymd5.getBytes(),"TripleDES");
cipher.init(Cipher.DECRYPT_MODE,keyspec);
BASE64Decoder decoder = new BASE64Decoder();
byte[] raw = decoder.decodeBuffer(data);
byte[] stringBytes = cipher.doFinal(raw);
String result = new String(stringBytes);
return result;
}
function Encrypt($input, $key_seed) {
$input = trim($input);
$block = mcrypt_get_block_size('tripledes', 'ecb');
$len = strlen($input);
$padding = $block - ($len % $block);
$input .= str_repeat(chr($padding), $padding);
// generate a 24 byte key from the md5 of the seed
$key = substr(md5($key_seed), 0, 24);
$iv_size = mcrypt_get_iv_size(MCRYPT_TRIPLEDES, MCRYPT_MODE_ECB);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
// encrypt
$encrypted_data = mcrypt_encrypt(MCRYPT_TRIPLEDES, $key, $input, MCRYPT_MODE_ECB, $iv);
// clean up output and return base64 encoded
return base64_encode($encrypted_data);
}
function Decrypt($input, $key_seed) {
$input = base64_decode($input);
$key = substr(md5($key_seed), 0, 24);
$text = mcrypt_decrypt(MCRYPT_TRIPLEDES, $key, $input, MCRYPT_MODE_ECB, '12345678');
$block = mcrypt_get_block_size('tripledes', 'ecb');
$packing = ord($text{strlen($text) - 1});
if ($packing and ( $packing < $block)) {
for ($P = strlen($text) - 1; $P >= strlen($text) - $packing; $P--) {
if (ord($text{$P}) != $packing) {
$packing = 0;
}
}
}
$text = substr($text, 0, strlen($text) - $packing);
return $text;
}
Từ sơ đồ phía trên, vì lý do bảo mật & nhất quán, IPS nên cung cấp cho DIGIPAY 2 API, bao gồm
IPS to publish service as Money Collector for IPS’s Merchant, we can suggest that IPS implement quite simple solution which mapped each transaction send to DIGIPAY to each IPS’s merchant requested.
No |
Function Name |
Description |
1 |
CreateDIGIPAYCheckout |
Để gửi yêu cầu tạo giao dịch checkout đến DIGIPAY, tiền thu sẽ đi đến tài khoản của IPS . |
2 |
CreatePrepaidCardCheckout |
Giao dịch checkout đặc biệt với nguồn tiền thanh toán là thẻ cào của nhà mạng Việt Nam. |
3 |
GetTransaction |
Để lấy thông tin giao dịch với Order_Code có sẵn . |
4 |
CreateWithdrawal |
Gửi yêu cầu đến DIGIPAY về việc rút tiền từ TK DIGIPAY của IPS đến TK ngân hàng hoặc thẻ ATM. |
5 |
GetTransactionWithdrawalStatus |
Gửi yêu cầu nhận thông tin về các giao dịch rút tiền mà IPS đã yêu cầu. |
![]() |
Request
Property |
Type |
Description |
fnc |
string |
CreateDIGIPAYCheckout |
mid |
string |
Merchant Id (provided by DIGIPAY.vn) |
uid |
String |
DIGIPAY merchant account Id (provided by DIGIPAY.vn) |
type |
int |
1 – Payment by DIGIPAY balanace; 2 – Payment by ATM card/ Bank account; |
data |
string |
Encoded by TripleDES algorithm, encryption key provided by DIGIPAY.vn; before encryption, JSON data into a string ENCODE. |
checksum |
string |
MD5 (fnc, mid, uid, type, data, $key), encryption key provided by DIGIPAY.vn. |
“data” is an array:
Property |
Type |
Description |
order_code |
String |
The code that generated by merchant, max 50 characters. |
amount |
Int |
Payment amount (VND), min: 10000 VND |
payer_fullname |
String |
The fullname of buyer/ payer, max 255 characters. |
payer_email |
String |
The email of buyer/ payer, max 255 characters. |
payer_mobile |
String |
The mobile of buyer/ payer, max 12 characters, example format: 84912345678. |
bank_id |
String |
If type = 1, bank_id = null (“”); if type = 2, reference to bank table. |
description |
String |
Description of order, max 255 characters. |
Response:
Property |
Type |
Description |
error_code |
String |
Processing code (reference to checkout error_code table). |
token_code |
String |
The unique code generated by DIGIPAY.vn, each checkout request. |
checkout_url |
String |
DIGIPAY checkout url. |
checksum |
String |
MD5 (error_code, token_code , checkout_url, $key), encryption key provided by DIGIPAY.vn. |
Checkout bank table reference
Id |
Short Name |
Full Name |
01 |
Vietcombank |
Ngân hàng TMCP Ngoại Thương Việt Nam |
02 |
Techcombank |
Ngân hàng TMCP Kỹ Thương Việt Nam |
03 |
VietinBank |
Ngân hàng TMCP Công Thương Việt Nam |
04 |
AgriBank |
Ngân hàng Nông nghiệp & Phát triển Nông thôn |
05 |
BIDV |
Ngân hàng TMCP Đầu tư & Phát triển Việt Nam |
06 |
ACB |
Ngân hàng TMCP Á Châu |
07 |
SacomBank |
Ngân hàng TMCP Sài Gòn Thương Tín |
08 |
EximBank |
Ngân Hàng TMCP Xuất Nhập Khẩu Việt Nam |
09 |
DongA Bank |
Ngân hàng TMCP Đông Á |
10 |
VPBank |
Ngân hàng TMCP Việt Nam Thịnh Vượng |
11 |
SeaBank |
Ngân hàng TMCP Đông Nam Á |
12 |
TienPhong Bank |
Ngân hàng TMCP Tiên Phong |
13 |
VIB |
Ngân hàng TMCP Quốc tế |
14 |
MB |
Ngân hàng TMCP Quân Đội |
15 |
SHB |
Ngân hàng TMCP Sài Gòn - Hà Nội |
16 |
OceanBank |
Ngân hàng TMCP Đại Dương |
17 |
PG Bank |
Ngân hàng TMCP Xăng dầu Petrolimex |
18 |
VietA Bank |
Ngân hàng TMCP Việt Á |
19 |
SaigonBank |
Ngân hàng TMCP Sài Gòn Công Thương |
20 |
Navibank |
Ngân hàng TMCP Quốc Dân Việt Nam |
21 |
DaiA Bank |
Ngân hàng TMCP Đại Á |
22 |
AnBinh Bank |
Ngân hàng TMCP An Bình |
23 |
HD Bank |
Ngân hàng Phát triển Nhà TP. Hồ Chí Minh |
24 |
Maritime Bank |
Ngân hàng TMCP Hàng Hải Việt Nam |
25 |
OCB |
Ngân hàng TMCP Phương Đông |
26 |
GPBank |
Ngân hàng TMCP Dầu khí Toàn Cầu |
27 |
NamA Bank |
Ngân hàng TMCP Nam Á |
28 |
BacA Bank |
Ngân hàng TMCP Bắc Á |
Request:
Property |
Type |
Description |
fnc |
string |
CreatePrepaidCardCheckout |
mid |
string |
Merchant Id (provided by DIGIPAY.vn) |
uid |
String |
DIGIPAY merchant account Id (provided by DIGIPAY.vn) |
data |
string |
Encoded by TripleDES algorithm, encryption key provided by DIGIPAY.vn; before encryption, JSON data into a string ENCODE. |
checksum |
string |
MD5 (fnc, mid, uid, data, $key), encryption key provided by DIGIPAY.vn. |
“data” is an array:
Property |
Type |
Description |
order_code |
String |
It’s the payment code, max 50 characters. |
telco_id |
String |
Reference to telco table |
card_code |
String |
Card code |
card_serial |
String |
Card serial |
Telco reference
Id |
Short Name |
01 |
Viettel |
02 |
MobiFone |
03 |
VinaPhone |
04 |
VietnamMobile |
05 |
Gate |
Response:
Property |
Type |
Description |
error_code |
string |
Processing code (reference to error_code table). |
card_price |
Int |
The price (or value) of card. |
DIGIPAY_transaction_id |
String |
DIGIPAY payment transaction id. |
checksum |
string |
MD5 (error_code, card_price, DIGIPAY_transaction_id, $key), encryption key provided by DIGIPAY.vn. |
Request:
Property |
Type |
Description |
fnc |
string |
GetTransaction |
mid |
string |
Merchant Id (provided by DIGIPAY.vn) |
uid |
String |
DIGIPAY merchant account Id (provided by DIGIPAY.vn) |
data |
string |
Encoded by TripleDES algorithm, encryption key provided by DIGIPAY.vn; before encryption, JSON data into a string ENCODE. |
checksum |
string |
MD5 (fnc, mid, uid, data, $key), encryption key provided by DIGIPAY.vn. |
“data” is an array:
Property |
Type |
Description |
payment_transaction_id |
String |
DIGIPAY payment transaction id. |
order_code |
String |
The code of original transaction which sent to DIGIPAY before, max 50 characters. |
amount |
Int |
Refund amount (VND), min: 20000 VND |
token_code |
string |
The unique code generated by DIGIPAY.vn, each checkout request. |
type |
Int |
1 – DIGIPAY Account 2 – ATM 3 – Prepaid card 4 – Refund |
Response:
Property |
Type |
Description |
error_code |
string |
Processing code (reference to refund error code table). |
checksum |
string |
MD5 (error_code, payment_transaction_id, amount, token_code, $key), encryption key provided by DIGIPAY.vn. |
error_description |
string |
Description error |
payment_transaction_id |
string |
DIGIPAY payment transaction id. |
amount |
string |
The payment amount |
token_code |
string |
The unique code generated by DIGIPAY.vn, each checkout request. |
Property |
Type |
Description |
fnc |
string |
CreateWithdrawal |
mid |
string |
Merchant Id (provided by DIGIPAY.vn) |
uid |
String |
DIGIPAY merchant account Id (provided by DIGIPAY.vn) |
type |
int |
2 – Send Money to a Bank Account; 3 - Send Money to a ATM card; |
data(*) |
string |
Encoded by TripleDES algorithm, encryption key provided by DIGIPAY.vn; before encryption, JSON data into a string ENCODE. |
checksum |
string |
MD5 (fnc, mid, uid, type, data, $key), encryption key provided by DIGIPAY.vn. |
Data is JSON array
For withdrawal to Bank’s Account - type = 2:
Property |
Type |
Description |
order_code |
String |
The code that generated by merchant, max 50 characters. |
amount |
Int |
Withdrawal amount (VND), min: 100000 |
bank_account |
string |
The bank account number of receiver, max 20 characters. |
bank_account_holder |
String |
Account holders, Vietnamese unsigned, max 20 characters. Example: NGUYEN VAN A. |
bank_id |
string |
Bank Id (reference to bank table). |
bank_branch |
string |
Bank branch is the place where customers can open accounts, which belong to that bank. Max 255 characters. |
description |
string |
Description of order, max 255 characters. |
For case withdrawal to ATM Card Number - type = 3:
Property |
Type |
Description |
order_code |
String |
The code that generated by merchant, max 50 characters. |
amount |
Int |
Withdrawal amount (VND), min: 100000 |
atm_card_number |
string |
The ATM number card, max 20 characters. |
atm_card_holder |
String |
This is the name of card_holder, which is released in Vietnam, max 20 characters. Example: NGUYEN VAN A. |
bank_id |
string |
Bank Id (reference to bank table). |
description |
string |
Description of order, max 255 characters. |
Property |
Type |
Description |
error_code |
string |
Processing code (reference to error_code table). |
DIGIPAY_transaction_id |
string |
DIGIPAY transaction id |
checksum |
string |
MD5 (error_code, DIGIPAY_transaction_id, $key), encryption key provided by DIGIPAY.vn. |
Id |
Short Name |
Fullname |
01 |
Vietcombank |
Ngân hàng TMCP Ngoại Thương Việt Nam |
02 |
Techcombank |
Ngân hàng TMCP Kỹ Thương Việt Nam |
03 |
VietinBank |
Ngân hàng TMCP Công Thương Việt Nam |
04 |
AgriBank |
Ngân hàng Nông nghiệp & Phát triển Nông thôn |
05 |
BIDV |
Ngân hàng TMCP Đầu tư & Phát triển Việt Nam |
06 |
ACB |
Ngân hàng TMCP Á Châu |
07 |
SacomBank |
Ngân hàng TMCP Sài Gòn Thương Tín |
08 |
EximBank |
Ngân Hàng TMCP Xuất Nhập Khẩu Việt Nam |
09 |
DongA Bank |
Ngân hàng TMCP Đông Á |
10 |
VPBank |
Ngân hàng TMCP Việt Nam Thịnh Vượng |
11 |
SeaBank |
Ngân hàng TMCP Đông Nam Á |
12 |
TienPhong Bank |
Ngân hàng TMCP Tiên Phong |
13 |
VIB |
Ngân hàng TMCP Quốc tế |
14 |
MB |
Ngân hàng TMCP Quân Đội |
15 |
SHB |
Ngân hàng TMCP Sài Gòn - Hà Nội |
16 |
OceanBank |
Ngân hàng TMCP Đại Dương |
17 |
PG Bank |
Ngân hàng TMCP Xăng dầu Petrolimex |
18 |
VietA Bank |
Ngân hàng TMCP Việt Á |
19 |
SaigonBank |
Ngân hàng TMCP Sài Gòn Công Thương |
20 |
Navibank |
Ngân hàng TMCP Quốc Dân Việt Nam |
21 |
DaiA Bank |
Ngân hàng TMCP Đại Á |
22 |
AnBinh Bank |
Ngân hàng TMCP An Bình |
23 |
HD Bank |
Ngân hàng Phát triển Nhà TP. Hồ Chí Minh |
24 |
Maritime Bank |
Ngân hàng TMCP Hàng Hải Việt Nam |
25 |
OCB |
Ngân hàng TMCP Phương Đông |
26 |
GPBank |
Ngân hàng TMCP Dầu khí Toàn Cầu |
27 |
NamA Bank |
Ngân hàng TMCP Nam Á |
28 |
BacA Bank |
Ngân hàng TMCP Bắc Á |
Property |
Type |
Description |
fnc |
string |
GetTransactionWithdrawalStatus |
mid |
string |
Merchant Id (provided by DIGIPAY.vn) |
uid |
String |
DIGIPAY merchant account Id (provided by DIGIPAY.vn) |
data |
string |
Encoded by TripleDES algorithm, encryption key provided by DIGIPAY.vn; before encryption, JSON data into a string ENCODE. |
checksum |
string |
MD5 (fnc, mid, uid, data, $key), encryption key provided by DIGIPAY.vn. |
“data” is an array:
Property |
Type |
Description |
order_code |
String |
The code that generated by merchant, max 50 characters. |
amount |
Int |
Withdrawal amount (VND), min: 100000 |
Property |
Type |
Description |
error_code |
string |
Processing code (reference to error_code table). |
withdrawal_transaction_id |
string |
Withdrawal transaction id |
refund_transaction_id |
String |
Refund transaction Id |
type |
int |
1 – Send Money to DIGIPAY account; 2 – Send Money to a Bank Account; 3 - Send Money to a ATM card; 4 – Cardless. |
bank_fee |
Int |
Amount of change bank |
checksum |
string |
MD5 (error_code, withdrawal_transaction_id, refund_transaction_id, type, $key), encryption key provided by DIGIPAY.vn. |
Error_code |
Description
|
00 |
Success |
01 |
Merchant Id is not exist (or not active) |
02 |
Merchant account Id is not exist (or not active) |
03 |
Checksum is invalid |
04 |
Data is invalid (data encryption error) |
05 |
IP is invalid or locked |
99 |
Unknown error, unable to perform transactions. Please try again or contact DIGIPAY for support |
10 |
Type of transaction is invalid |
11 |
Transaction id is not exist |
12 |
Transaction is failed |
13 |
Transaction is failed and refuned |
14 |
Transactions are being reconciled |
15 |
Transaction timeout, unable to perform transactions |
16 |
Transaction Information has been changed in progressing (send and receive) |
17 |
Transaction withdrawal is processing |
20 |
OTP is invalid or timeout |
201 |
Order code is invalid |
202 |
Order code is exist (or performed before) |
203 |
Order code is not exist |
300 |
Payment amount is invalid |
301 |
Checkout amount is invalid |
302 |
Withdrawal amount is invalid |
303 |
Refund amount is invalid |
400 |
Name is max 255 characters (full name of buyer/ seller) |
401 |
Email is invalid |
402 |
Mobile number is invalid |
403 |
Mobile number is not exist (or blockaded) |
404 |
Description of order, max 255 characters. |
500 |
Customer account is not exist (or blockaded) |
501 |
Account is blockaded (unable to get refund) |
502 |
Balance account is not enough |
600 |
Bank Id is invalid |
601 |
Bank system is error (unable to process transaction) |
602 |
Bank reject Transaction |
603 |
Bank transfer transaction is timeout (not received response) |
620 |
ATM card number is invalid |
621 |
ATM card number is not exist |
622 |
ATM Card number is not correct |
623 |
ATM Cardholder name is not correct |
624 |
ATM Card expiry / ATM card locked |
625 |
ATM Card is not registered the internet banking service |
626 |
ATM Cards exceeded payment limits |
640 |
Bank account number is invalid |
641 |
Bank account number is not exist |
642 |
Bank account holder is invalid |
643 |
Bank branch is invalid |
660 |
No Reply from Bank |
700 |
Telco id is invalid |
701 |
Scratch card code is invalid (format) |
702 |
Scratch card serial is invalid (format) |
703 |
Telco system are maintenance |
704 |
The scratch card does not exist or has been used |
705 |
Scratch card is locked |
706 |
Scratch card is expired |
707 |
Scratch card is not enabled or does not exist |
708 |
Scratch card code and serial number mismatch |
709 |
Scratch card unusable |
710 |
Transaction timeout (telco does not return the result) |