DigiPay.vn

API Specification & Integration

Giới thiệu API document Thuật toán mã hóa

Tiếng Việt

Enlish

Giới thiệu

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

Các dịch vụ được đề xuất

Mặc dù DIGIPAY cung cấp tất cả cách dịch vụ liên quan đến thanh toán điện tử & ví điện tử trên di động. Trong khuôn khổ tài liệu này, chúng tôi đề xuất dịch vụ Rút tiền từ 1 tài khoản Master, tài khoản này cho phép các Merchant thực hiện rút tiền tới các số thẻ ATM và tài khoản ngân hàng nội địa.

Môi trường tích hợp & Test

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:

API locate
DIGIPAY’s Account ID
Authentication Key
Merchant ID
Encryption Key

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

1.1. By .NET C#


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);
}

1.2. By Java


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;
}

1.3. By PHP


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;
}

Test Account information 0942567890 / 123123 0942567891 / 123123 ATM Card information in DIGIPAY Test Environment 07: Sacombank (SAI CON THUONG TIN COMMERCIAL JOINT STOCK BANK) Card code: 9704030098841957 Released: 03/2013 05: BIDV (BANK FOR INVESTMENT AND DEVELOPMENT OF VIETNAM JSC) Card code: 9703089913568765 Released: 06/2011

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

Một để xác nhận mỗi lệnh là chính xác
Hai để DIGIPAY gửi thông báo cho mỗi giao dịch đã được thực hiện.

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.

API List

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.

Checkout API

Create Checkout

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 Á

Telco Prepaid Card Checkout

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.

Get Transaction Detail

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.

Withdrawal API

Create Withdrawal

Request Message Format

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.

Response message format

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.

Bank Reference

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 Á

Get Withdrawal Transaction Status API

Request Message Format

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

Response Message Format

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 Definition

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)

CÔNG TY CỔ PHẦN THANH TOÁN DIGIPAY

Số 28 Liễu Giai,Phường Cống Vị,Quận Ba Đình, Thành phố Hà Nội, Việt Nam

Mã số doanh nghiệp: 0107986498