payme_sdk_offical - Dart API docs

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 nhập, eKYC thông qua tài khoản ví PayME
Hỗ trợ app lấy thông tin số dư ví PayME
Chức năng nạp rút từ ví PayME.

Một số thuật ngữ

	Name	Giải thích
1	app	Là app mobile iOS/Android hoặc web sẽ tích hợp SDK vào để thực hiện chức năng thanh toán ví PayME.
2	SDK	Là bộ công cụ hỗ trợ tích hợp ví PayME vào hệ thống app.
3	backend	Là hệ thống tích hợp hỗ trợ cho app, server hoặc api hỗ trợ
4	AES	Hàm mã hóa dữ liệu AES256 PKCS5 . Tham khảo
5	RSA	Thuật toán mã hóa dữ liệu RSA.
6	IPN	Instant Payment Notification , dùng để thông báo giữa hệ thống backend của app và backend của PayME

Cách cài đặt:

Thêm dòng này vào pubspec.yaml:

dependencies:
  payme_sdk_offical: ^1.1.7

Sau đó chạy lệnh dart pub get để hoàn tất cài dặt

Info.plist

Update file Info.plist của app với những key như sau (giá trị của string có thể thay đổi, đây là các message hiển thị khi yêu cầu người dùng cấp quyền tương ứng):

<key>NSCameraUsageDescription</key>
<string>Need to access your camera to capture a photo add and update profile picture.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Need to access your library to add a photo or videoo off kyc video</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Need to access your photo library to select a photo add and update profile picture</string>
<key>NSContactsUsageDescription</key>
<string>Need to access your contact</string>

Nếu không sử dụng tính năng danh bạ thì thêm vào cuối podfile

post_install do |installer|
   installer.pods_project.targets.each do |target|
       if target.name == 'PayMESDK'
           target.build_configurations.each do |config|
             config.build_settings['SWIFT_ACTIVE_COMPILATION_CONDITIONS'] ||= '$(inherited)'
             config.build_settings['SWIFT_ACTIVE_COMPILATION_CONDITIONS'] << 'IGNORE_CONTACT'
           end
       end
   end
end

Cách sử dụng SDK:

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 : AppId 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. (không truyền vào SDK này )
AppPrivateKey: Sẽ truyền vào PayME SDK để thực hiện việc giải mã.

Chuẩn mã hóa: RSA-512bit. Có thể dùng tool sau để sinh ra tại đây

Khởi tạo PayME SDK:

Trước khi sử dụng PayME SDK cần gọi phương thức khởi tạo và đăng nhập để sử dụng SDK.

PaymeSdkFlutterConfig({
    required this.appToken,
    required this.publicKey,
    required this.privateKey,
    required this.secretKey,
    this.primaryColor = const Color(0xff75255b),
    this.secondaryColor = const Color(0xff9d455f),
    this.language = PaymeSdkFlutterLanguage.VN,
    this.env = PaymeSdkFlutterEnv.SANDBOX,
});
  
static Future<PaymeSdkFlutterKYCState> login(String userId, String phone, PaymeSdkFlutterConfig config);

Tham số	Bắt buộc	Giải thích
appPrivateKey	Yes	là private key của app tự sinh ra như trên
publicKey	Yes	là public key được PayME cung cấp cho mỗi app riêng biệt
configColor	Yes	là tham số màu để có thể thay đổi màu sắc giao dịch ví PayME, kiểu dữ liệu là chuỗi với định dạng #rrggbb. Nếu như truyền 2 màu thì giao diện PayME sẽ gradient theo 2 màu truyền vào
timestamp	Yes	Thời gian tạo ra connectToken theo định dạng iSO 8601 , Dùng để xác định thời gian timeout cùa connectToken. Ví dụ 2021-01-20T06:53:07.621Z
userId	Yes	là giá trị cố định duy nhất tương ứng với mỗi tài khoản khách hàng ở dịch vụ, thường giá trị này do server hệ thống được tích hợp cấp cho PayME SDK
phone	Yes	Số điện thoại của hệ thống tích hợp, nếu hệ thống không dùng số điện thoại thì có thể không cần truyền lên hoặc truyền null

Các tính năng như nạp tiền, rút tiền, pay chỉ thực hiện được khi đã kích hoạt ví và gửi định danh thành công. Tức là khi login sẽ được trả về enum KYCState với case là KYC_APPROVED.

Mã lỗi của PayME SDK

Hằng số	Mã lỗi	Giải thích
`EXPIRED`	`401`	token hết hạn sử dụng
`NETWORK`	`-1`	Kết nối mạng bị sự cố
`SYSTEM`	`-2`	Lỗi hệ thống
`LIMIT`	`-3`	Lỗi số dư không đủ để thực hiện giao dịch
`ACCOUNT_NOT_ACTIVATED`	`-4`	Lỗi tài khoản chưa kích hoạt
`ACCOUNT_NOT_KYC`	`-5`	Lỗi tài khoản chưa định danh
`PAYMENT_ERROR`	`-6`	Thanh toán thất bại
`ERROR_KEY_ENCODE`	`-7`	Lỗi mã hóa/giải mã dữ liệu
`USER_CANCELLED`	`-8`	Người dùng thao tác hủy
`ACCOUNT_NOT_LOGIN`	`-9`	Lỗi chưa đăng nhập tài khoản
`PAYMENT_PENDING`	`-11`	Thanh toán chờ xử lý
`ACCOUNT_ERROR`	`-12`	Lỗi tài khoản bị khóa

Các chức năng của PayME SDK (Static Method)

logout()

logout() -> Future<void>

Dùng để đăng xuất ra khỏi phiên làm việc trên SDK

close() - Đóng SDK

Hàm này được dùng để app tích hợp đóng lại UI của SDK khi đang pay() hoặc openWallet()

close() -> Future<void>

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

openWallet() -> Future<dynamic>

Hàm này được gọi khi từ app tích hợp khi muốn gọi chức năng của sdk PayME

deposit() - Nạp tiền

deposit({int? amount}) -> Future<dynamic>

withdraw() - Rút tiền

withdraw({int? amount}) -> Future<dynamic>

transfer() - Chuyển tiền

transfer({int? amount, String note = ""}) -> Future<dynamic>

openHistory() - Mở lịch sử giao dịch

openHistory() -> Future<dynamic>

Hàm này có ý nghĩa giống như gọi openWallet với action là Action.OPEN_HISTORY

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.

pay(
    int amount,
    String orderId,
    PaymeSdkFlutterPayCode payCode, 
    {
    	String? storeId,
    	String? userName,
    	String? note,
    	String? extraData,
    	bool isShowResultUI = true,
    }
) -> Future<dynamic>

Tham số	Bắt buộc	Giá trị
`payCode`	Yes	`PAYME` `ATM` `CREDIT` `MANUAL_BANK`
`userName`	No	Tên tài khoản
`storeId`	No	ID của store phía công thanh toán thực hiên giao dịch thanh toán

Lưu ý : Chỉ có userName hoặc storeId, nếu dùng userName thì để storeId = null và ngược lại

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

scanQR(payCode: String) -> Future<dynamic>

Định dạng QR :

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

Ví dụ :

final qrString = "OPENEWALLET|54938607|PAYMENT|20000|Chuyentien|2445562323|DEMO)"

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
storeId: ID của store phía hiện giao dịch thanh toán
type: OPENEWALLET

payQRCode() - thanh toán mã QR code

payQRCode(
	qr: String,
	payCode: String,
	isShowResultUI: Bool
) -> Future<dynamic>

qr: Mã QR để thanh toán ( Định dạng QR như hàm scanQR() )
isShowResultUI: Có muốn hiển thị UI kết quả giao dịch hay không

Hàm này được gọi khi từ app tích hợp khi muốn mở modal định danh tài khoản ( yêu cầu tài khoản phải chưa định danh )

openKYC() -> Future<dynamic>

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

getWalletInfo() -> Future<dynamic>

Trong trường hợp lỗi thì hàm sẽ trả về message lỗi tại hàm onError , khi đó app có thể hiển thị balance là 0.
Trong trường hợp thành công SDK trả về thông tin như sau:

{
  "walletBalance": {
    "balance": 111,
    "detail": {
      "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

getAccountInfo()

App có thể dùng đượ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.

getAccountInfo() -> Future<dynamic>

getSupportedServices()

Dùng để xác định các dịch vụ có thể dùng SDK để thanh toán (điện, nước, học phí...).

getSupportedServices() -> Future<dynamic>

openService()

Mở WebSDK để thanh toán dịch vụ. ( Tính năng đang được xây dựng )

openService(String serviceCode, String serviceDescription) -> Future<dynamic>

setLanguage()

Chuyển đổi ngôn ngữ của sdk

setLanguage(PaymeSdkFlutterLanguage lang) -> Future<dynamic>

Ghi chú

Làm việc với use_framework!

react-native-permission: https://github.com/zoontek/react-native-permissions#workaround-for-use_frameworks-issues
Google Map iOS Util: https://github.com/googlemaps/google-maps-ios-utils/blob/b721e95a500d0c9a4fd93738e83fc86c2a57ac89/Swift.md

Cách cài đặt:

Cách sử dụng SDK:

Khởi tạo PayME SDK:

Mã lỗi của PayME SDK

Các chức năng của PayME SDK (Static Method)

logout()

close() - Đóng SDK

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

deposit() - Nạp tiền

withdraw() - Rút tiền

transfer() - Chuyển tiền

openHistory() - Mở lịch sử giao dịch

pay() - Thanh toán

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

payQRCode() - thanh toán mã QR code

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

getAccountInfo()

getSupportedServices()

openService()

setLanguage()

Ghi chú

Làm việc với use_framework!

Libraries

payme_sdk_offical package

Cách cài đặt:

Cách sử dụng SDK:

Khởi tạo PayME SDK:

Mã lỗi của PayME SDK

Các chức năng của PayME SDK (Static Method)

logout()

close() - Đóng SDK

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

deposit() - Nạp tiền

withdraw() - Rút tiền

transfer() - Chuyển tiền

openHistory() - Mở lịch sử giao dịch

pay() - Thanh toán

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

payQRCode() - thanh toán mã QR code

openKYC() - Mở modal định danh tài khoản

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

getAccountInfo()

getSupportedServices()

openService()

setLanguage()

Ghi chú

Làm việc với use_framework!

Libraries

payme_sdk_offical package