web-payme-sdk v1.4.27

PayME SDK là bộ thư viện để các app có thể tương tác với PayME Platform. PayME SDK bao gồm các chức năng chính như sau:

• Hệ thống đăng ký, đăng nhập, eKYC thông qua tài khoản ví PayME
• Chức năng nạp rút chuyển tiền từ ví PayME.
• Tích hợp các dịch vụ của PayME Platform.

Một số thuật ngữ

Cài đặt

• npm: npm install web-payme-sdk

• yarn: yarn add web-payme-sdk

Usage

Hệ thống PayME sẽ cung cấp cho app tích hợp các thông tin sau:

• PublicKey : Dùng để mã hóa dữ liệu, app tích hợp cần truyền cho SDK để mã hóa.
• AppToken : AppToken cấp riêng định danh cho mỗi app, cần truyền cho SDK để mã hóa
• SecretKey : Dùng đã mã hóa và xác thực dữ liệu ở hệ thống backend cho app tích hợp.

Bên App sẽ cung cấp cho hệ thống PayME các thông tin sau:

• AppPublicKey : Sẽ gửi qua hệ thống backend của PayME dùng để mã hóa.
• AppPrivateKey: Sẽ truyền vào PayME SDK để thực hiện việc giải mã.

Chuẩn mã hóa: RSA-512bit.

Khởi tạo thư viện

Trước khi sử dụng PayME SDK cần import component SDK và ref để sử dụng các chức năng.

• Khi sử dụng tài khoản khác cần cập nhật lại param configs

import React, { Component, useRef } from 'react'
import WebPaymeSDK from 'web-payme-sdk'

class Example extends Component {
  const refWebPaymeSDK = useRef(null)
  const configs = {
      appToken,
      deviceId,
      publicKey,
      privateKey,
      env, 
      appId,
      partner,
      configColor
   }
  render() {
    return <WebPaymeSDK configs={configs} ref={refWebPaymeSDK} propStyle={propStyle} />
  }
}

Parameters

Mã lỗi của PayME SDK

Các chức năng của PayME SDK

login()

Có 2 trường hợp

• Dùng để login lần đầu tiên ngay sau khi khởi tạo PayME.

• Dùng khi accessToken hết hạn, khi gọi hàm của SDK mà trả về mã lỗi ERROR_CODE.EXPIRED hoặc ERROR_CODE.ACCOUNT_LOCK, lúc này app cần gọi login lại để lấy accessToken dùng cho các chức năng khác.

Sau khi gọi login() thành công rồi thì mới gọi các chức năng khác của SDK ( openWallet, pay, ... )

const configsLogin = {
   ...configs,
   connectToken,
   phone,
   userId
}
refWebPaymeSDK.current.login(
   configsLogin,
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

Constant

Parameters

Cách tạo connectToken:

connectToken cần để truyền gọi api từ tới PayME và sẽ được tạo từ hệ thống backend của app tích hợp. Cấu trúc như sau:

import forge from 'node-forge'

function encryptAES(text, secretKey) {
  // parse data into base64
  const iv = Buffer.from(ivbyte);
  const algorithm = determineAlthorithm(secretKey);
  const cipher = crypto.createCipheriv(algorithm, secretKey, iv);
  let encrypted = cipher.update(text, 'utf8', 'base64');
  encrypted += cipher.final('base64');
  return encrypted;
}

const data = {
  timestamp: "2021-01-20T06:53:07.621Z",
  userId : "abc",
  phone : "0123456789"
};

const connectToken = encryptAES(JSON.stringify(data), appSecretkey)

Tạo connectToken bao gồm thông tin KYC (Dành cho các đối tác có hệ thống KYC riêng)

const data = {
  timestamp: "2021-01-20T06:53:07.621Z",
  userId : "abc",
  phone : "0123456789",
  kycInfo: {
    fullname: "Nguyễn Văn A",
    gender: "MALE",
    birthday: "1995-01-20T06:53:07.621Z",
    address: "15 Nguyễn cơ thạch",
    identifyType: "CMND",
    identifyNumber: "142744332",
    issuedAt: "2013-01-20T06:53:07.621Z",
    placeOfIssue: "Hồ Chí Minh",
    video: "https://file-examples-com.github.io/uploads/2017/04/file_example_MP4_480_1_5MG.mp4",
    face: "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
    image: {
      front: "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg",
      back: "https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885__480.jpg"
    }
  }
};

const connectToken = encryptAES(JSON.stringify(data), appSecretkey)

Trong đó AES là hàm mã hóa theo thuật toán AES. Tùy vào ngôn ngữ ở server mà bên hệ thống dùng thư viện tương ứng. Xem thêm tại đây https://en.wikipedia.org/wiki/Advanced_Encryption_Standard

Tham số KycInfo

logout

⚠️⚠️⚠️ version 1.4.12 trở đi

Clear cache thông tin tài khoản đã login. Sau khi logout thì cần thực hiện login lại để thực hiện các chức năng.

refWebPaymeSDK.current.logout(
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

getAccountInfo

App có thể dùng thuộc tính này sau khi khởi tạo SDK để biết được trạng thái liên kết tới ví PayME.

refWebPaymeSDK.current.getAccountInfo(
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

openWallet - Mở UI chức năng PayME tổng hợp

Hàm này được gọi khi từ app tích hợp khi muốn gọi 1 chức năng PayME bằng cách truyền vào tham số Action như trên.

refWebPaymeSDK.current.openWallet(
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

openHistory

Hàm này được gọi khi từ app tích hợp khi muốn mở lịch sử giao dịch từ ví.

** Yêu cầu tài khoản đã kích hoạt và định danh để mở lịc sử Ví

⚠️⚠️⚠️ version 1.4.10 trở đi

refWebPaymeSDK.current.openHistory(
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

scanQR

Mở chức năng quét mã QR để thanh toán

⚠️⚠️⚠️ version 1.4.1 trở đi

refWebPaymeSDK.current.scanQR(
   {
      payCode: String
   },
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

Định dạng QR:

const qrString = "{$type}|${storeId}|${action}|${amount}|${note}|${orderId}|${userName}"

• action: loại giao dịch ('PAYMENT' => thanh toán)
• amount: số tiền thanh toán
• note: Mô tả giao dịch từ phía đối tác
• orderId: mã giao dịch của đối tác, cần duy nhất trên mỗi giao dịch. Tối đa 22 kí tự.
• storeId: ID của store phía công thanh toán thực hiên giao dịch thanh toán
• userName: Tên tài khoản
• type: OPENEWALLET

Ví dụ :

const qrString = "OPENEWALLET|54938607|PAYMENT|20000|Chuyentien|2445562323|taikhoan"

payQRCode

Hàm dùng để thanh toán mã QR code do đối tác cung cấp

⚠️⚠️⚠️ version 1.4.1 trở đi

refWebPaymeSDK.current.payQRCode(
   {
      qrContent: String,
      payCode: String,
      isShowResultUI: Boolean
   },
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

deposit - Nạp tiền

refWebPaymeSDK.current?.deposit(
   {
      amount: Number,
      closeWhenDone: Boolean
   },
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
);

withdraw - Rút tiền

refWebPaymeSDK.current?.withdraw(
   {
      amount: Number,
      closeWhenDone: Boolean
   },
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
);

transfer - Chuyển tiền

refWebPaymeSDK.current?.transfer(
   {
      amount: Number,
      description: String
   },
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
);

getListService

App có thể dùng thược tính này sau khi khởi tạo SDK để biết danh sách các dịch vụ mà PayME đang cung cấp

refWebPaymeSDK.current.getListService(
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

openService

Hàm này được gọi khi từ app tích hợp khi muốn gọi 1 dịch vụ mà PayME cũng cấp bằng cách truyền vào tham số serviceCode như sau

refWebPaymeSDK.current.openService(
   serviceCode,
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

getListPaymentMethod - ⚠️⚠️⚠️ Đã remove từ version 1.4.1 trở đi

Hàm này được gọi khi từ app tích hợp khi muốn lấy danh sách các phương thức thanh toán mà PayME cung cấp vs từng tài khoản sau khi tài khoản đã kích hoạt và định danh thành công, dùng để truyền vào hàm pay() để chọn trực tiếp phương thức thanh toán mà app đối tác muốn

refWebPaymeSDK.current.getListPaymentMethod(
   { 
      storeId
   },
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
)

pay - Thanh toán

Hàm này được dùng khi app cần thanh toán 1 khoản tiền từ ví PayME đã được kích hoạt.

• Khi thanh toán bằng ví PayME thì yêu cầu tài khoản đã kích hoạt,định danh và số dư trong ví phải lớn hơn số tiền thanh toán
• Thông tin tài khoản lấy qua hàm getAccountInfo()
• Thông tin số dư lấy qua hàm getWalletInfo()

⚠️⚠️⚠️ version 1.4.1 trở đi

const  data = {
  amount:  Number,
  orderId:  String,
  storeId:  Number?,
  extractData: String,
  note:  String,
  userName: String?,
  payCode: String,
  isShowResultUI: Boolean?,
}
refWebPaymeSDK.current.pay(
   data,
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
);

getWalletInfo - Lấy các thông tin của ví

refWebPaymeSDK.current.getWalletInfo(response => {
   (response) => {
      // onSuccess
   },
   (error) => {
      // onError
   }
})

{
   "balance":  111,
   "cash":  1,
   "lockCash":  2
}

balance: App tích hợp có thể sử dụng giá trị trong key balance để hiển thị, các field khác hiện tại chưa dùng.

detail.cash: Tiền có thể dùng.

detail.lockCash: Tiền bị lock.

Danh sách phương thức thanh toán

License

Copyright 2020 @ PayME