> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 支付寶 App 內支付（In-App）

> 使用 AlipayHK 或 AlipayCN SDK 進行 App 內支付的整合指南。

本文件說明如何透過 QFPay API 搭配 **AlipayHK 或 AlipayCN 官方 SDK**，整合原生 App 內支付流程。

此方式適用於 iOS / Android 原生 App，可提供無瀏覽器跳轉的流暢支付體驗。

<Frame>
  <img src="https://mintcdn.com/qfpay-8e347952/37llGB_BvQrEF2dK/images/online-shop/alipay-in-app.png?fit=max&auto=format&n=37llGB_BvQrEF2dK&q=85&s=5302fa6be3d5e9c2a5750f14d5f61be5" alt="Alipay In App" width="839" height="944" data-path="images/online-shop/alipay-in-app.png" />
</Frame>

***

## 整合流程概覽

1. App 呼叫 QFPay `/trade/v1/payment`
2. QFPay 回傳 `pay_params`
3. App 將 `pay_params` 組裝為 `orderInfo`
4. 呼叫 Alipay 官方 SDK 進行支付
5. 等待非同步通知或查詢交易狀態確認最終結果

***

## SDK 下載

請使用官方 SDK 文件與套件：

* [支付寶海外 SDK 文件](https://global.alipay.com/docs/ac/app/client_integration)
* [AlipayHK SDK 下載](https://global.alipay.com/docs/ac/app_hk/download)
* [AlipayHK SDK 觸發支付指南](https://global.alipay.com/docs/ac/hkapi/securitypay_pay)

***

## API 請求

**Endpoint**\
`POST /trade/v1/payment`

### PayType

| PayType  | 說明                    |
| -------- | --------------------- |
| `801110` | 支付寶 App 內支付（支付寶直接結算）  |
| `801510` | 支付寶 App 內支付（QFPay 結算） |

***

## 必填參數

| 參數名稱           | 必填  | 類型          | 說明                       |
| -------------- | --- | ----------- | ------------------------ |
| `txamt`        | 是   | Int         | 交易金額（分）例如 100 = HKD 1    |
| `txcurrcd`     | 是   | String(3)   | 幣別，例如 `HKD`              |
| `pay_type`     | 是   | String(6)   | `801110` 或 `801510`      |
| `out_trade_no` | 是   | String(128) | 商戶唯一訂單號                  |
| `txdtm`        | 是   | String(20)  | 格式 `YYYY-MM-DD HH:mm:ss` |
| `goods_name`   | 是   | String      | 商品名稱                     |
| `return_url`   | 是   | String      | 支付完成回跳網址                 |
| `seller_id`    | 是   | String      | 支付寶商戶帳號                  |
| `mchid`        | 視情況 | String(16)  | 僅代理商或特定模式需要，請按實際開通狀態使用。  |

通用欄位請參考：\
[通用支付參數](/integration/api-reference/request-format)

***

## 選填參數

| 參數名稱   | 參數編碼           | 說明                             |
| ------ | -------------- | ------------------------------ |
| 商品描述   | `goods_info`   | 支付寶建議填寫，不可含特殊字元                |
| 支付標記   | `pay_tag`      | 預設 `ALIPAYHK`；大陸版使用 `ALIPAYCN` |
| 訂單過期時間 | `expired_time` | 單位分鐘，5–120，預設 30               |

***

## 範例請求（Form 格式）

```plaintext theme={null}
txamt=1
&txcurrcd=HKD
&pay_type=801510
&out_trade_no=052711570017898
&txdtm=2021-05-27 11:57:00
&goods_name=goods_name
&goods_info=goods_info
&mchid=nDB64h9qJ1An
&return_url=https://www.qfpay.global/
&pay_tag=ALIPAYHK
&seller_id=testoverseas9191@alipay.com
```

***

## 回傳欄位（pay\_params）

QFPay 回傳的 `pay_params` 需原樣傳入 Alipay SDK。

| 參數               | 說明        |
| ---------------- | --------- |
| `partner`        | 合作夥伴 ID   |
| `seller_id`      | 收款帳號對應用戶號 |
| `subject`        | 商品標題      |
| `body`           | 商品描述      |
| `total_fee`      | 訂單金額      |
| `notify_url`     | 通知地址      |
| `service`        | 服務名稱      |
| `payment_type`   | 支付類型      |
| `_input_charset` | 編碼格式      |
| `it_b_pay`       | 超時參數      |
| `return_url`     | 回跳網址      |
| `currency`       | 幣別        |
| `product_code`   | 產品代碼      |
| `sign`           | RSA 簽名    |
| `sign_type`      | 簽名類型      |

***

## QFPay 回傳範例

```json theme={null}
{
  "respcd": "0000",
  "pay_type": "801510",
  "syssn": "20210527154100020004180921",
  "out_trade_no": "052711570017898",
  "pay_params": {
    "body": "goods_info",
    "seller_id": "2088231067382451",
    "total_fee": 0.01,
    "currency": "HKD",
    "service": "mobile.securitypay.pay",
    "sign_type": "RSA",
    "sign": "xxxxx",
    "product_code": "NEW_WAP_OVERSEAS_SELLER"
  }
}
```

***

## 組裝 orderInfo

取得 `pay_params` 後：

1. 將參數依 `key="value"` 格式組合
2. 按 key 進行 A–Z 排序
3. 使用 `&` 連接
4. 將 `sign` 與 `sign_type` 放最後

### 範例

```plaintext theme={null}
_input_charset="UTF-8"&body="goods_info"&currency="HKD"&partner="2088231067382451"&product_code="NEW_WAP_OVERSEAS_SELLER"&seller_id="2088231067382451"&service="mobile.securitypay.pay"&total_fee="0.01"&sign="xxxxx"&sign_type="RSA"
```

***

<Note>
  * 必須使用對應地區 SDK（HK 或 CN）
  * `pay_params` 內所有 key 與 value 必須保持完全一致
  * 簽名驗證邏輯需符合支付寶官方 SDK 規範
  * 最終交易結果請以非同步通知或交易查詢 API 為準
</Note>