Trang chủ- PACIFIC MOBILE PAY SOLUTION
HTTP APIs > API giao dịch qua OTP

Các bước thực hiện

1 KH truy cập giao diện nạp tiền của Merchant. Submit yêu cầu thanh toán qua OTP
2 CPxử lý bật webform OTP của mPay9505 và truyền vào đó các tham số cần thiết
3 Trên webform OTP của mPay9505, KH nhập các thông tin: Số điện thoại, chọn mệnh giá thanh toán sau đó Submit yêu cầu gửi OTP
4 mPay9505 xử lý thông tin sau đó gửi SMS chứa mã OTP về điện thoại của KH
5 Với thuê bao Viettel: KH tiến hành nhập OTP ngay trên webform OTP của mPay9505 để xác thực. Với thuê bao MobiFone: KH soạn SMS chứa mã OTP gửi đến 9505
6 mPay tiến hành xác thực OTP

•Nếu không thành công, mPay9505 sẽ có thông báo tương ứng cho KH ngay trên webform OTP, KH sẽ không bị trừ cước.

•Nếu thành công, mPay9505 sẽ tiến hành giao dịch trừ cước trong tài khoản điện thoại của KH.

Nếu trừ cước thành công, kết quả sẽ được thông báo cho KH qua SMS và CPqua API

Nếu trừ cước không thành công, mPay9505 sẽ có thông báo và hướng dẫn đến KH

1.Api mPay9505 cung cấp

mPay9505 cung cấp một giao diện thanh toán qua OTP tập trung, giúp công việc tích hợp của các Đối tác được dễ dàng, thuận lợi nhất.

-Để thực hiện giao dịch thanh toán qua OTP, các đối tác chỉ cần gọi đến giao diện OTP tập trung này, và truyền vào các tham số cần thiết. Các thao tác nhận và xác thực OTP của KH sẽ được thực hiện trên giao diện này.

-Hình thức kết nối là HTTP, phương thức GET

-Địa chỉ giao diện là:
http://api.mpay9505.vn/otpcharging/otpform?data=stringEncode

+Trong đó: data là chuỗi được encode bằng thuật toán Base64String

+Chuỗi trước khi mã hóa có dạng như sau:
Plaintext=”cpCode|requestId|gameCode|returnUrl|account|accessKey|signature”

+Chuỗi sau khi encode: stringEncode = Base64String(Plaintext)

STT

Tên tham số

Kiểu dữ liệu

Ý nghĩa

1

  cpCode

String(5)

Mã CP

2

  requestId

String(50)

Do CP tự sinh ra, dùng để định danh giao dịch phía CP

3

  gameCode

String(3)

Mã game do CP cấu hình trong trang CMS

4

  returnUrl

String(255)

Địa chỉ Url mà CP muốn redirect KH đến sau khi nạp thành công (chỉ áp dụng với OTP VIETTEL)

5

  account

String(30)

Tài khoản game của KH

6

  accessKey

String(50)

Khóa truy cập CP api, CP phải check mã này trước khi check chữ ký(signature). Khóa này được mPay cấp cho CP, CP có thể vào CMS để xem

7

  signature

String

Chữ ký điện tử dùng để xác thực dữ liệu giữa MPAY và CP, thuật toán mã hóa là HMACSHA256

Cách sinh chữ ký:

plaintext="cpCode|requestId|gameCode|returnUrl|account|accessKey"

Ví dụ:
plaintext="CPC1|T123456|GC|http://abc.com/cde|doladola| abcdef12345ghijklmn"
signature = HMACSHA256(plaintext, secretKey)
-secretKey được mPay cấp cho CP, CP có thể vào CMS để xem

2.API CPcần xây dựng

-CPcần xây dựng API này để cổng mPay9505 gọi sau khi giao dịch thanh toán của KH thành công

-Hình thức kết nối qua giao thức HTTP, phương thức GET

-Địa chỉ API có dạng:
http://cpdomain/recivechangingresult?requestId={0}&cpCode={1}&gameCode={2}&totalAmount={3}&account={4}&provider={5}&channel={6}&isdn={7}&requestTime={8}&resultCode={9}&accessKey={10}&signature={11}

Tham số đầu vào:

STT

Tên tham số

Kiểu dữ liệu

Mô tả

1

  requestId

String(50)

Mã giao dịch do MPAY trả về

2

  cpCode

String(5)

Mã CP, mã này được mPay cấp cho CP, CP có thể vào CMS để xem

3

  gameCode

String(3)

Mã game, mã này được mPay cấp cho CP, CP có thể vào CMS để xem

4

  totalAmount

Int

Số tiền nạp, ví dụ: 10000, 20000, …

5

  account

String(30)

Tài khoản game của KH

6

  provider

String(10)

Nhà mạng (VIETTEL, MOBI)

7

  channel

String(10)

Kênh giao dịch(SMS, OTP)

8

  isdn

String(15)

Số điện thoại, ví dụ: 098123123, …

9

  requestTime

String(19)

Thời gian gửi giao dịch định dạng yyyy-MM-dd HH:mm:ss

10

  resultCode

String(2)

Kết quả giao dịch với resultCode=”00” là thành công

11

  accessKey

String(50)

Khóa truy cập CP api, CP phải check mã này trước khi check chữ ký(signature). Khóa này được mPay cấp cho CP, CP có thể vào CMS để xem

12

  signature

String

Chữ ký điện tử dùng để xác thực dữ liệu giữa MPAY và CP, thuật toán mã hóa là:

HMACSHA256

Cách sinh chữ ký:

plaintext="requestId={0}&cpCode={1}&gameCode={2}&totalAmount={3}
&account={4}&provider={5}&channel={6}&isdn={7}
&requestTime={8}&resultCode={9}&accessKey={10}"

Ví dụ: plaintext =

"requestId=T123456 &cpCode=CPC1&gameCode=GC&
totalAmount=10000&account=doladola&
provider=VIETTEL&channel=SMS&isdn=0988888888&requestTime=2017-03-03 00:00:00&resultCode=00&accessKey= abcdef12345ghijklmn"

signature = HMACSHA256(plaintext, secretKey)
secretKey được mPay cấp cho CP, CP có thể vào CMS để xem

Kết quả trả về

Kết quả trả về theo format sau: resultCode|Text_mo_ta

STT

Tên tham số

Kiểu dữ liệu

Mô tả

1

 resultCode

 String(2)

 Mã lỗi: “00” là thành công, khác “00” là lỗi

2

 Text_mo_ta

 String(200)

 Text mô tả ngắn cho resultCode

Lưu ý:
-Thời gian timeout cho lệnh gọi API này là 15s
-Trường hợp lỗi mạng, mPay không gọi được API này của CP để báo kết quả giao dịch, mPay sẽ retry lệnh gọi, tối đa 3 lần, mỗi lệnh gọi cách nhau 1 phút.
-Do đó CP cần check requestId trong lệnh gọi, nếu requestId đã được update trong hệ thống của CP thì CP cần có xử lý thích hợp, tránh double giao dịch cho KH

 

File MpayHelper.zip download tại đây

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Test
{
    public class MpayHelper
    {
        //Mã duy nhất do MPAY cung cấp, ví dụ: CPC
        public string cpCode { get; set; }

        //Mã game do CP đăng ký, ví dụ: GC
        public string gameCode { get; set; }

        //Liên kết khi nạp OTP thành công hoặc hủy sẽ redirect đến
        public string returnUrl { get; set; }

        //Tài khoản của user nạp tiền
        public string account { get; set; }

        //Key truy cập API do MPAY cung cấp
        public string accessKey { get; set; }

        //Request Id do CP tự sinh ra
        public string requestId { get; set; }

        //Key dùng để ký dữ liệu khi gửi lên hệ thống MPAY hoặc khi CP nhận dữ liệu từ MPAY
        public string secretKey { get; set; }

        public string getUrl()
        {
            var data = this.getData();
            var domain = "http://api.mpay9505.vn";
            var otpFormUrl = string.Format("{0}?{1}", domain + "/otpcharging/otpform", "data=" + data);
            //url để chuyển liên kết đến form nạp OTP chung của MPAY
            return otpFormUrl;
        }

        private string getData()
        {

            string plainText = string.Format("{0}|{1}|{2}|{3}|{4}|{5}",
                this.cpCode, this.requestId, this.gameCode,
                this.returnUrl, this.account, this.accessKey
                );

            //Ký dữ liệu sử dụng thuật toán HMACSHA256
            var sha = new HmacSha256();
            var signature = sha.hash(plainText, secretKey);
            plainText += "|" + signature;

            //encode dữ liệu trước khi gửi đến MPAY sử dụng thuật toán Base64 encode string
            byte[] toBytes = Encoding.UTF8.GetBytes(plainText);
            var strBase64Encode = Convert.ToBase64String(toBytes);

            return strBase64Encode;
        }
    }
}

 

File HmacSha256.zip download tại đây

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

namespace Test
{
    public class HmacSha256
    {
        public string hash(string data, string secretKey)
        {
            var byteKey = Encoding.UTF8.GetBytes(secretKey);
            var byteData = Encoding.UTF8.GetBytes(data);
            HMACSHA256 hmacSHA256 = new HMACSHA256(byteKey);
            var hashDataByte = hmacSHA256.ComputeHash(byteData);
            var encrypted = this.ByteToString(hashDataByte);
            return encrypted.ToLower();
        }

        private string ByteToString(byte[] buff)
        {
            string sbinary = "";

            for (int i = 0; i < buff.Length; i++)
            {
                sbinary += buff[i].ToString("X2"); // hex format
            }
            return (sbinary);
        }
    }
}

 

File MpayHelperPHP.zip download tại đây

<?php
/**
 * Created by PhpStorm.
 * User: kaka
 * Date: 3/9/2017
 * Time: 2:07 PM
 */

namespace app\models;


class MpayHelper
{
    //Mã duy nhất do MPAY cung cấp, ví dụ: CPC
    public $cpCode;

    //Mã game do CP đăng ký, ví dụ: GC
    public $gameCode;

    //Liên kết khi nạp OTP thành công hoặc hủy sẽ redirect đến
    public $returnUrl;

    //Tài khoản của user nạp tiền
    public $account;

    //Key truy cập API do MPAY cung cấp
    public $accessKey;

    //Request Id do CP tự sinh ra
    public $requestId;

    //Key dùng để ký dữ liệu khi gửi lên hệ thống MPAY hoặc khi CP nhận dữ liệu từ MPAY
    public $secretKey;

    public function getUrl()
    {
        $data = $this->getData();
        $domain = "http://api.mpay9505.vn";
        $otpFormUrl = $domain . "/otpcharging/otpform?data=" . $data;

        //url để chuyển liên kết đến form nạp OTP chung của MPAY
        return $otpFormUrl;
    }

    private function getData()
    {
        $plainText = $this->cpCode . "|" . $this->requestId . "|" . $this->gameCode . "|" . $this->returnUrl . "|" . $this->account . "|" . $this->accessKey;
        $signature = hash_hmac("sha256", $plainText, $this->secretKey);
        $plainText = $plainText . "|" . $signature;

        $strBase64Encode = base64_encode($plainText);
        return $strBase64Encode;
    }
}