> For the complete documentation index, see [llms.txt](https://doc.9pay.vn/ios-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.9pay.vn/ios-sdk/huong-dan-tich-hop.md).

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

## 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.

```swift
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

```swift
<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

<table><thead><tr><th width="349">Params</th><th>Chú thích</th></tr></thead><tbody><tr><td>merchantCode</td><td>Đây là mã của đối tác khi tích hợp SDK</td></tr><tr><td>secretKey</td><td>Đây là khoá để kết nối API với 9pay</td></tr><tr><td>uid</td><td>Đị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</td></tr><tr><td>env</td><td>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.</td></tr><tr><td>brandColor</td><td>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</td></tr><tr><td>phoneNumber</td><td>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</td></tr></tbody></table>

## 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

<figure><img src="https://lh6.googleusercontent.com/qq_r1JCWcAMR2EAt9N-2Abyqpws7hlUoNKUFLYgJnOB9d8cc5sd2bLU0GmRoV_vod1fwOGUMVhu82BKRKtIYOjj2voHA9HOmtwb3iWajtFdv6e4RhK_cxjZNDkxgEhHEHVxFU0XxAyXd30_QLs_tluE" alt=""><figcaption></figcaption></figure>

### **4.1** Code mẫu khởi tạo

{% code overflow="wrap" %}

```swift
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))
```

{% endcode %}

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

```swift
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.

```swift
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            |

###

{% tabs %}
{% tab title="Nạp tiền" %}

<figure><img src="/files/5LVXf4yjV5AT6PT0KDw5" alt="" width="188"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Chuyển/rút tiền" %}

<figure><img src="/files/uKdat3vUEvRJRdfEYu2T" alt="" width="188"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Nạp/mua thẻ" %}

<figure><img src="/files/paz99pVf3XNz4JJqDO2Y" alt="" width="188"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Thẻ dịch vụ" %}

<figure><img src="/files/WS1I9r02pvVEknG0hHzr" alt="" width="188"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Hoá đơn" %}

<figure><img src="/files/kXYpr7vCiCSukBntbjyU" alt="" width="188"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### 4.3 Thanh toán dịch vụ merchant

```swift
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

<figure><img src="https://lh4.googleusercontent.com/i0RQRU8xWxQKCNSZoG7j7Tvmy_SZ4UhfmjpBtL0cYidKzvvN5AzvSHknRUxt2qXLP1DH9rjjj0cXfa0oRN0qzLANh7qSdSgOIhUg-HGh_cM41xLJUMeOAlrPVI901cYLPLUk4cugjP0ribrGXpmSXIM" alt=""><figcaption></figcaption></figure>

{% code overflow="wrap" %}

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

{% endcode %}

### **4.5 Đăng xuất**

```swift
nLib.logout()
```

### 4.6 Đóng SDK

```swift
nLib.close()
```

## **5. Dữ liệu test sandbox**

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

## **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                                            |
|      |                                                              |