Hướng dẫn tích hợp

Hướng dẫn tích hợp SDK 9Pay iOS

1. Thêm thư viện

Cài đặt SDK qua Cocoapods. Thêm dòng code pod 'NPayFrameworkMC', '~> 2.0.5' vào file Podfile sau đó chạy lệnh pod install trên terminal.

use_frameworks!
pod 'NPayFrameworkMC', '~> 2.0.5'

Cấu hình quyền sử dụng Camera (dùng cho chức năng eKYC) trong Info.plist

<key>NSCameraUsageDescription</key>
<string>Cho phép ứng dụng truy cập máy ảnh, để có thể chụp hình khi xác thực tài khoản và quét mã vạch thanh toán</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Cho phép ứng dụng ảnh để chọn ảnh mã QR hoặc chụp giấy tờ xác thực</string>

2. Khởi tạo SDK

Params	Chú thích
merchantCode	Đây là mã của đối tác khi tích hợp SDK
secretKey	Đây là khoá để kết nối API với 9pay
uid	Định danh người dùng sử dụng tài khoản của merchant, không bắt buộc, có thể truyền null
env	Môi trường sử dụng, có 2 môi trường là sandbox (môi trường test code) và production (môi trường chạy thực tế), xem bảng dưới để biết cấu hình.
brandColor	Mã màu mà merchant muốn sử dụng ở các button trong SDK, mã màu hex và không chứa ký tự #, ví dụ 15AE62
phoneNumber	SDK yêu cầu cung cấp số điện thoại hợp lệ theo định dạng của Việt Nam để có thể sử dụng

3. Bảng hằng số sử dụng cấu hình trong hàm SDK

Params	Explain
EnvironmentKey.SANBOX	flavorEnv môi trường Sandbox
EnvironmentKey.PRODUCTION	flavorEnv môi trường Production
PaymentMethod.WALLET	Thanh toán bằng ví điện tử 9Pay (sử dụng trong hàm openPaymentOnSDK).
PaymentMethod.ATM_CARD	Thanh toán bằng thẻ ATM nội địa (sử dụng trong hàm openPaymentOnSDK).
PaymentMethod.CREDIT_CARD	Thanh toán bằng credit card ((sử dụng trong hàm openPaymentOnSDK).
PaymentMethod.DEFAULT	Thanh toán bằng tất cả hình thức (sử dụng trong hàm openPaymentOnSDK).

4. Luồng kỹ thuật

4.1 Code mẫu khởi tạo

let merchantCode = "merchant_code" // Contact 9pay
let secretKey = "secret_key" // Contact 9pay
let uID = "0975998989" // can nullable
let brandColor = "15AE62"
let flavorEnv = EnvironmentKey.SANDBOX //  or PRODUCTION
let phoneNumber = "0912365431" // Required
let nLib = NPayManager(vController: self, sdkCfgs: SDKConfigs(merchantCode: merchantCode, secretKey: secretKey, uid: uID, brandColor: brandColor, env: flavorEnv, phoneNumber: phoneNumber))

Hãy nhớ thêm giao thức LibListener bên trong ViewController

class ViewControllerDemo: UIViewController, LibListener {

    func sdkDidComplete(action: String, status: Bool?, param: [String : Any]?) {
        // Thông báo chức năng nào của SDK đã hoàn thành, trạng thái thành công 
        // hoặc thất bại thông qua key status tham số kèm theo (nếu có)
    }
    
    func onLogoutSuccessful() {
        // SDK logout 
    }
    
    func onCloseSDK() {
        // SDK đóng
    }
    
    func getInfoSuccess(user: String) {
       // Trả về User Info
       
    }
    
    func backToAppFrom(action: String) {
       // User back screen
    }
    
    func onError(errorCode: Int, message: String) {
        // Error contain code and message
    }
}

// Json example callback getInfoSuccess:

{
  "balance": "1505549",
  "phone": "0912365431",
  "name": "NGUYEN VAN A",
  "statusKyc": "2"
}

4.2 Mở chức năng 9Pay cung cấp

Các hàm SDK được cung cấp sẽ được gọi thông qua hàm openSDKWithAction với tham số action kèm theo. Ví dụ: SDK mở chức năng đăng nhập.

nLib?.openSDKWithAction(action: ServiceAction.LOGIN, vController: self)
//vController : in class viewcontroller open SDK

Name action	Function
LOGIN	Đăng nhập Ví 9pay
HISTORY	Lịch sử giao dịch
TRANSFER	Chức năng chuyển tiền, rút tiền
DEPOSIT	Nạp tiền vào Ví 9pay
QR	Quét mã QR thanh toán
BILLING	Hoá đơn tổng hợp
TOPUP	Nạp điện thoại
PHONE_CARD	Mua thẻ điện thoại
DATA_CARD	Mua thẻ Data 4G
SERVICE_CARD	Mua thẻ dịch vụ
HOME	Trang chủ người dùng

Nạp tiền

Chuyển/rút tiền

Nạp/mua thẻ

Thẻ dịch vụ

Hoá đơn

4.3 Thanh toán dịch vụ merchant

var orderDataString = "some string payment" // Created from Backend
let method = PaymentMethod.
// PaymentMethod.ATM_CARD
// PaymentMethod.CREDIT_CARD
// PaymentMethod.LINK_BANK
var isShowResult = true 
/* Hiển thị màn kết quả của SDK sau khi thanh toán, ngược lại false sẽ không hiển. */

nLib.openPaymentOnSDK(orderDataString: orderDataString, vControoler: UIViewController, paymentMethod: method, isShowResultScreen: isShowResult)

4.4 Lấy thông tin người dùng đã đăng nhập

nLib.getUserInfo()
//Callback to protocol getInfoSuccess()
// Return json string:
// Phone, balance, eKYC status, name.

4.5 Đăng xuất

nLib.logout()

4.6 Đóng SDK

nLib.close()

5. Dữ liệu test sandbox

Loại dữ liệu	Chi tiết
Tài khoản Ví	0912365431
Mật khẩu tài khoản Ví	123123
Mã xác thực OTP	123456
Thông tin ngân hàng sử dụng để liên kết và nạp tiền	Ngân hàng Agribank Số thẻ: 9704 0000 0000 0018 Họ và tên: Nguyen Van A Ngày phát hành: 03/07 OTP: otp
Thẻ quốc tế	Tên chủ thẻ: NGUYEN VAN A Số thẻ: 4005555555000009 (Visa) 5200000000001005 (MasterCard) Ngày hết hạn: 05/25 CVV: 123

6. Bảng mã lỗi SDK

Mã lỗi được trả ở callback onError khi khởi tạo SDK.

Mã	Loại
403	Chưa đăng nhập
2001	Lỗi khi validate thông tin order
2002	Lỗi khi thanh toán dịch vụ merchant
2003	Lỗi khi lấy thông tin ngân hàng và thẻ thanh toán SDK hỗ trợ
2004	Lỗi giải mã dữ liệu trả về
2005	Lỗi chưa xác định