Hotline: Thuê bao MobiFone 9090 (24/7- 200đ/phút) - Thuê bao mạng khác 1900-20-79 (8h30-22h - 1000đ/phút )

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 Vimo cũng như những hướng dẫn để tích hợp các dịch vụ của Vimo


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

Mặc dù Vimo 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

Merchant sử dụng API của Vimo

  • API locate
  • Vimo’s Account ID
  • Authentication Key
  • Merchant ID
  • Encryption Key

Protocol: Bảo mật HTTP sử dụng Phương pháp POST.

Dữ liệu của mỗi tin nhắn từ phía Merchant gửi đến Vimo 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;
}

                            
http://14.177.64.231/vimo_enhancement/web/checkout_api/payment/v1/checkout.php Test Account information 0942567890 / 123123 0942567891 / 123123 ATM Card information in VIMO 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

Vì lý do bảo mật & nhất quán, Merchant nên cung cấp cho Vimo 2 API, bao gồm

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

API List

No

Function Name

Description

1

CreateVimoCheckout

Để gửi yêu cầu tạo giao dịch checkout đến Vimo, tiền thu sẽ đi đến tài khoản của Merchant .

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 Vimo về việc rút tiền từ TK Vimo của Merchant đế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à Merchant đã yêu cầu.

 

 

Checkout API

Create Checkout

 

 
 

 

 

 

Request

Property

Type

Description

fnc

string

CreateVimoCheckout

mid

string

Merchant Id (provided by Vimo.vn)

uid

String

Vimo merchant account Id (provided by Vimo.vn)

type

int

1 – Payment by Vimo balanace;

2 – Payment by ATM card/ Bank account;

data

string

Encoded by TripleDES algorithm, encryption key provided by Vimo.vn; before encryption, JSON data into a string ENCODE.

checksum

string

MD5 (fnc, mid, uid, type, data, $key), encryption key provided by Vimo.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 Vimo.vn,  each checkout request.

checkout_url

String

Vimo checkout url.

checksum

String

MD5 (error_code, token_code , checkout_url, $key), encryption key provided by Vimo.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 Vimo.vn)

uid

String

Vimo merchant account Id (provided by Vimo.vn)

data

string

Encoded by TripleDES algorithm, encryption key provided by Vimo.vn; before encryption, JSON data into a string ENCODE.

checksum

string

MD5 (fnc, mid, uid, data, $key), encryption key provided by Vimo.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.

vimo_transaction_id

String

Vimo payment transaction id.

checksum

string

MD5 (error_code, card_price, vimo_transaction_id, $key), encryption key provided by Vimo.vn.

 

Get Transaction Detail

Request:

Property

Type

Description

fnc

string

GetTransaction

mid

string

Merchant Id (provided by Vimo.vn)

uid

String

Vimo merchant account Id (provided by Vimo.vn)

data

string

Encoded by TripleDES algorithm, encryption key provided by Vimo.vn; before encryption, JSON data into a string ENCODE.

checksum

string

MD5 (fnc, mid, uid, data, $key), encryption key provided by Vimo.vn.

 

“data” is an array:

Property

Type

Description

payment_transaction_id

String

Vimo payment transaction id.

order_code

String

The code of original transaction which sent to Vimo before, max 50 characters.

amount

Int

Refund amount (VND), min: 20000 VND

token_code

string

The unique code generated by Vimo.vn,  each checkout request.

type

Int

1 – Vimo 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 Vimo.vn.

error_description

string

Description error

payment_transaction_id

string

Vimo payment transaction id.

amount

string

The payment amount

token_code

string

The unique code generated by Vimo.vn,  each checkout request.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Withdrawal API

 

 

Create Withdrawal

 

  1. Request Message Format

Property

Type

Description

fnc

string

CreateWithdrawal

mid

string

Merchant Id (provided by Vimo.vn)

uid

String

Vimo merchant account Id (provided by Vimo.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 Vimo.vn; before encryption, JSON data into a string ENCODE.

checksum

string

MD5 (fnc, mid, uid, type, data, $key), encryption key provided by Vimo.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.

 

 

 

  1. Response message format

Property

Type

Description

error_code

string

Processing code (reference to error_code table).

vimo_transaction_id

string

Vimo transaction id

checksum

string

MD5 (error_code, vimo_transaction_id, $key), encryption key provided by Vimo.vn.

 

  1. 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

 

  1. Request Message Format

Property

Type

Description

fnc

string

GetTransactionWithdrawalStatus

mid

string

Merchant Id (provided by Vimo.vn)

uid

String

Vimo merchant account Id (provided by Vimo.vn)

data

string

Encoded by TripleDES algorithm, encryption key provided by Vimo.vn; before encryption, JSON data into a string ENCODE.

checksum

string

MD5 (fnc, mid, uid, data, $key), encryption key provided by Vimo.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

 

  1. 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 Vimo 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 Vimo.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 VIMO 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)

 

Hỗ trợ thanh toán