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

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

1. Cài đặt thư viện

Thêm repositories maven vào android/build.gradle

allprojects {
	repositories {
		maven { url 'https://jitpack.io' }
	}
}

Thêm tiếp vào android/app/build.gradle thư viện SDK

dependencies {
        implementation 'com.github.mobile9pay:ninepay_sdk::0.2.5'
}

Cuối cùng nhấn Sync để download thư viện vào project

2. Khởi tạo SDK

Tham số	Giải thích
merchantCode	Đây là mã của đối tác khi tích hợp SDK
secretKey	Đây là khóa để 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
flavorEnv	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.
colorCode	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

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

Hằng số	Giải thích
EnvironmentKey.SANDBOX	flavorEnv môi trường Sandbox
EnvironmentKey.PRODUCTION	flavorEnv môi trường Production
PaymentMethod.DEFAULT	Thanh toán bằng tất cả hình thức (sử dụng trong hàm openPaymentOnSDK).
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 thẻ quốc tế (sử dụng trong hàm openPaymentOnSDK).

4. Luồng kỹ thuật

4.1 Code mẫu khởi tạo

String merchantCode = "merchant_code"; // Liên hệ 9Pay để được cung cấp
String secretKey = "secret_key"; // Liên hệ 9Pay để được cung cấp
String uId = "0975998989"; // Có thể không cần truyền vào
String colorCode = "15AE62";
String flavorEnv = EnvironmentKey.SANDBOX; // EnvironmentKey.PRODUCTION

// Cấu hình khởi tạo
SdkConfig sdkConfig = new SdkConfig.Builder(this)
                            .merchantCode(merchantCode)
                            .secretKey(secretKey)
                            .uid(uId/or null)
                            .env(flavorEnv)
                            .brandColor(colorCode)
                            .build();

initSdk(sdkConfig);

private void initSdk(SdkConfig sdkConfig) {
        // Hàm khởi tạo SDK, nó có nhiệm vụ khởi tạo và trả ra các callback tương ứng
        // với mỗi dịch vụ mà user chọn hoặc thông tin cần thiết
        NPayLibrary.getInstance().init(activity, sdkConfig, new NineLibListener() {

            // Được gọi khi hàm NPayLibrary.getInstance().getUserInfo() được gọi để
            //lấy thông tin user.
            // Cần login trước khi lấy thông tin user, nếu không khi gọi
            //NPayLibrary.getInstance().getUserInfo() sẽ trả về mã lỗi 403                 
            @Override
            public void getInfoSuccess(String jsonData) {
                // Trả về một chuỗi thông tin của user bao gồm:
                // Điện thoại đăng nhập, số dư, trạng thái eKYC, tên
            }

            // Lỗi xảy ra trong quá trình thanh toán
            @Override
            public void onError(int errorCode, String message) {
                // Trả về mã lỗi và message
            }

            // Được gọi khi user tài khoản ví 9Pay đăng xuất (logout)
            //or khi gọi NPayLibrary.getInstance().logout();
            @Override
            public void onLogoutSuccessful() {
                
            }

            // Được gọi lại khi SDK bị đóng bởi người dùng hoặc kết thúc quá trình
            // thanh toán.
            @Override
            public void onCloseSDK() {
                //update app merchant...
            }

            // Một chức năng đã được thực hiện hoàn thành
            // Name: tên chức năng.
            // status: Trạng thái (onSuccess, onFail)
            // params: giá trị trả về (nếu có), mặc định null
            
            @Override
            public void sdkDidComplete(String name, Object status, @Nullable Object
            params) {         
                //có thể dùng để update UI
            }

            // Người dùng di chuyển sang màn khác mà không thực hiện chức năng chính
            // của màn hình đó (bỏ thanh toán, bỏ nhập OTP...). 
            // screen là màn hình người dùng đã bỏ qua.
            @Override
            public void backToAppFrom(String screen) {
                
            }
        });

    }

// Json mẫu callback getInfoSuccess:

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

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

NPayLibrary.getInstance().openSDKWithAction(action);
// Actions.DEPOSIT, Actions.TRANSFER

Tên action	Chức năng
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	Hóa đơ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ụ

Nạp tiền

Chuyển/rút tiền

Nạp/mua thẻ

Thẻ dịch vụ

Hóa đơn

4.3 Thanh toán dịch vụ merchant

String url = ""; // Url payment được tạo từ backend
String method = PaymentMethod.WALLET; // Phương thức thanh toán
// PaymentMethod.WALLET
// PaymentMethod.ATM_CARD
// PaymentMethod.CREDIT_CARD
// PaymentMethod.DEFAULT

boolean isShowResultScreen = true; // 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.
//code
NPayLibrary.getInstance().openPaymentOnSDK(url, method, isShowResultScreen);

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

NPayLibrary.getInstance().getUserInfo();

// Dữ liệu sẽ trả về trong callback ở hàm callback getInfoSuccess
// Trả về object UserInfo chứa thông tin:
// Số điện thoại đăng nhập, số dư, trạng thái eKYC, tên, ngân hàng liên kết.

4.5 Đăng xuất

NPayLibrary.getInstance().logout();

4.6 Đóng giao diện SDK

NPayLibrary.getInstance().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