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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.9pay.vn/ios-sdk/huong-dan-tich-hop.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.