點點金支付文件

版本歷史

版本 描述 日期
1.2.8 建置 v1.2.8 初版 2024-03-27

環境

通用錯誤代碼

Response

名稱 類型 描述
code number 代碼
  • 10001: 加簽異常
  • 10002: 代理未授權
  • 10003: 支付管道異常
data array []

API功能

代收

HTTP request URL

[POST] {api-domain}/api/deposit

Parameters

名稱 類型 必填 描述
agent string 是 商戶號
由點點金支付客服提供
order_sn string 是 商戶訂單號
允許格式
  • 長度(10 ~ 50)
  • 英文(a-zA-Z), 數字(0-9), 下底線(_)
amount numeric 是 金額
允許格式
  • 僅允許整數
  • 額度範圍請參考後台 代理資訊
type string 否 類型
允許格式
  • 0：銀行轉帳(預設)
  • 1：超商代碼
  • 2：虛擬帳號轉帳
  • 3：信用卡
bank_name string 是/否 持有人銀銀行名稱
允許格式
  • 銀行轉帳(type:0)時該欄必填
  • 範例：中國信託
  • 上限長度30
bank_code string 是/否 持有人銀行代碼
允許格式
  • 銀行轉帳(type:0)時該欄必填
  • 範例：822
  • 上限長度10
bank_account string 是/否 持有人銀行帳號
允許格式
  • 銀行轉帳(type:0)時該欄必填
  • 範例：000011112222
  • 上限長度50
bank_branch_name string 否 持有人銀行分行名稱
允許格式
  • 範例：敦北分行
  • 上限長度30
bank_branch_code string 否 持有人銀行分行代號
允許格式
  • 範例：0015
  • 上限長度10
bank_data_json json 否 同單多組銀行資料
允許格式
  • 範例：
    [
    {"bank_name":"國泰世華",
    "bank_code":"013",
    "bank_account":"1111",
    "bank_branch_name":"OO分行",
    "bank_branch_code":"0001"},
    {"bank_name":"台新銀行",
    "bank_code":"812",
    "bank_account":"2222",
    "bank_branch_name":"XX分行",
    "bank_branch_code":"0002"}
    ]
  • 依此範例建單完成後，將會產生三張商戶訂單號分別 {order_sn} / {order_sn}_1 / {order_sn}_2
user_name string 是/否 付款人姓名
允許格式
  • 超商代碼(type:1)時該欄必填
pay_content string 是/否 繳費內容
允許格式
  • 超商代碼(type:1)時該欄必填
  • 上限長度100
cvs_payment string 否 繳費超商代碼
  • 711(預設): 711
  • 全家: Family
  • 萊爾富: HiLife
  • OK: OK
user_birthday date('Y-m-d') 否 持有人生日
user_id_number string 否 持有人身分證
user_phone string(10) 否 付款人電話
注意
  • 部分支付通道此欄位為必填
  • 範例：0912345678
client_ip string 否 請求IP
notify_url string 否 支付回調URL
備註
  • 未填(預設): 使用後台設定 支付回調URL
  • 已填: 將使用該欄進行回調
  • 與後台設定 支付回調URL 不衝突
sign string 是 請求密鑰加簽參考 附錄 - 加密範例

Response

名稱 類型 描述
code number 代碼
  • 1: 成功
  • -1: 建單異常
  • -2: 商戶訂單號存在
  • -3: 商戶訂單號格式異常
  • -4: 金額異常
  • -5: 持有人銀行名稱必填
  • -6: 持有人銀行代碼必填
  • -7: 持有人銀行帳號必填
  • -8: 付款人姓名必填
  • -9: 繳費內容格式異常
  • -10: 類型異常
  • -11: 繳費超商代碼異常
  • -12: 同單多組銀行資料異常
  • -13: 付款人電話必填
data array 回傳資料
data 回傳資料
名稱 類型 描述
system_sn string(33) 系統單號
order_sn string 商戶訂單號
amount string 金額
total_commission string 總佣金
notify_url string 支付回調URL(異步通知)
payment_code string 支付代碼
  • 銀行轉帳(type:0)
    收款銀行代碼: "812"
  • 超商代碼(type:1)
    收款代碼: "CVS"
  • 虛擬帳號轉帳(type:2)
    收款代碼: "ATM"
  • 信用卡(type:3)
    收款代碼: "CC"
payment_account string 支付帳號
  • 銀行轉帳(type:0)
    收款銀行帳號: "222211110000"
  • 超商代碼(type:1)
    繳費單號: "12345678EAEB"
    繳費網址: URL
  • 虛擬帳號轉帳(type:2)
    繳費網址: URL
  • 信用卡(type:3)
    繳費網址: URL
status string 訂單狀態
  • 00:處理中
  • 01:成功
  • 02:代收無拒絕
created_at date('Y-m-d H:i:s') 建立時間
completed_at date('Y-m-d H:i:s') 完成時間，返回值可能為空字串
overtime_at date('Y-m-d H:i:s') 失效時間

代收查詢

HTTP request URL

[POST] {api-domain}/api/deposit/info

Parameters

名稱 類型 必填 描述
agent string 是 商戶號
由點點金支付客服提供
order_sn string 是 商戶訂單號
允許格式
  • 長度(10 ~ 50)
  • 英文(a-zA-Z), 數字(0-9), 下底線(_)
sign string 是 請求密鑰加簽參考 附錄 - 加密範例

Response

名稱 類型 描述
code number 代碼
  • 1: 成功
  • -1: 訂單異常
  • -2: 商戶訂單號不存在
  • -3: 商戶訂單號格式異常
data array 回傳資料
data 回傳資料
名稱 類型 描述
system_sn string(33) 系統單號
order_sn string 商戶訂單號
amount string 金額
total_commission string 總佣金
notify_url string 支付回調URL(異步通知)
payment_code string 支付代碼，例如銀行代碼: "812"
payment_account string 支付帳號，例如銀行帳號: "222211110000"
status string 訂單狀態
  • 00:處理中
  • 01:成功
  • 02:拒絕
created_at date('Y-m-d H:i:s') 建立時間
completed_at date('Y-m-d H:i:s') 完成時間，返回值可能為空字串
overtime_at date('Y-m-d H:i:s') 失效時間
note string 成功狀態備註 (status=01)
  • 超商：“IbonPay店點：99xxxx”
  • 虛擬帳戶：“013-xxxx”
    		•

    代付

    HTTP request URL

    [POST] {api-domain}/api/withdraw

    Parameters

    名稱 類型 必填 描述
    agent string 是 商戶號
    由點點金支付客服提供
    order_sn string 是 商戶訂單號
    允許格式
    • 長度(10 ~ 50)
    • 英文(a-zA-Z), 數字(0-9), 下底線(_)
    amount numeric 是 金額
    允許格式
    • 僅允許整數
    • 額度範圍請參考後台 代理資訊
    bank_name string 是 持有人銀銀行名稱
    允許格式
    • 範例：中國信託
    • 上限長度30
    bank_code string 是 持有人銀行代碼
    允許格式
    • 範例：822
    • 上限長度10
    bank_account string 是 持有人銀行帳號
    允許格式
    • 範例：000011112222
    • 上限長度50
    bank_branch_name string 否 持有人銀行分行名稱
    允許格式
    • 範例：敦北分行
    • 上限長度30
    bank_branch_code string 否 持有人銀行分行代號
    允許格式
    • 範例：0015
    • 上限長度10
    user_name string 否 持有人姓名
    user_birthday date('Y-m-d') 否 持有人生日
    user_id_number string 否 持有人身分證
    client_ip string 否 請求IP
    notify_url string 否 支付回調URL
    備註
    • 未填(預設): 使用後台設定 支付回調URL
    • 已填: 將使用該欄進行回調
    • 與後台設定 支付回調URL 不衝突
    sign string 是 請求密鑰加簽參考 附錄 - 加密範例

    Response

    名稱 類型 描述
    code number 代碼
    • 1: 成功
    • -1: 建單異常
    • -2: 商戶訂單號存在
    • -3: 商戶訂單號格式異常
    • -4: 金額異常
    • -5: 持有人銀行名稱必填
    • -6: 持有人銀行代碼必填
    • -7: 持有人銀行帳號必填
    • -8: 商戶餘額不足
    data array 回傳資料
    data 回傳資料
    名稱 類型 描述
    system_sn string(33) 系統單號
    order_sn string 商戶訂單號
    amount string 金額
    total_commission string 總佣金
    notify_url string 支付回調URL(異步通知)
    status string 訂單狀態
    • 00:處理中
    • 01:成功
    • 02:拒絕
    created_at date('Y-m-d H:i:s') 建立時間
    completed_at date('Y-m-d H:i:s') 完成時間，返回值可能為空字串
    overtime_at date('Y-m-d H:i:s') 失效時間

    代付查詢

    HTTP request URL

    [POST] {api-domain}/api/withdraw/info

    Parameters

    名稱 類型 必填 描述
    agent string 是 商戶號
    由點點金支付客服提供
    order_sn string 是 商戶訂單號
    允許格式
    • 長度(10 ~ 50)
    • 英文(a-zA-Z), 數字(0-9), 下底線(_)
    sign string 是 請求密鑰加簽參考 附錄 - 加密範例

    Response

    名稱 類型 描述
    code number 代碼
    • 1: 成功
    • -1: 訂單異常
    • -2: 商戶訂單號不存在
    • -3: 商戶訂單號格式異常
    data array 回傳資料
    data 回傳資料
    名稱 類型 描述
    system_sn string(33) 系統單號
    order_sn string 商戶訂單號
    amount string 金額
    total_commission string 總佣金
    notify_url string 支付回調URL(異步通知)
    status string 訂單狀態
    • 00:處理中
    • 01:成功
    • 02:拒絕
    created_at date('Y-m-d H:i:s') 建立時間
    completed_at date('Y-m-d H:i:s') 完成時間，返回值可能為空字串
    overtime_at date('Y-m-d H:i:s') 失效時間

    代收、代付回調(異步通知)

    HTTP request URL

    [POST] 由點點金支付後台進行設定

    Parameters

    名稱 類型 必填 描述
    agent string 是 商戶號
    system_sn string(33) 是 系統單號
    order_sn string 是 商戶訂單號
    amount string 是 金額
    total_commission string 是 總佣金
    status string 是 訂單狀態
    • 00:處理中
    • 01:成功
    • 02:拒絕
    type string 是 支付類型
    • 0: 代收
    • 1: 代付
    note string 是 支付備註
    • 代收
      超商：“IbonPay店點：99xxxx”
      虛擬帳戶：“013-xxxx”
    created_at date('Y-m-d H:i:s') 是 建立時間
    completed_at date('Y-m-d H:i:s') 是 完成時間，返回值可能為空字串
    overtime_at date('Y-m-d H:i:s') 是 失效時間
    sign string 是 請求密鑰加簽參考 附錄 - 加密範例

    Response

    回調參數的 sign，只需對 Parameters 內的參數驗證簽名
    收到回調後，請回傳 OK

    商戶資訊查詢

    HTTP request URL

    [POST] {api-domain}/api/agent/info

    Parameters

    名稱 類型 必填 描述
    agent string 是 商戶號
    由點點金支付客服提供
    sign string 是 請求密鑰加簽參考 附錄 - 加密範例

    Response

    名稱 類型 描述
    code number 代碼
    • 1: 成功
    • -1: 查詢異常
    data array 回傳資料
    data 回傳資料
    名稱 類型 描述
    account string 商戶帳號
    credit string 商戶可用餘額
    notify_url string 回調URL
    created_at date('Y-m-d H:i:s') 商戶建立時間
    updated_at date('Y-m-d H:i:s') 商戶最後異動時間

    支付通道查詢

    HTTP request URL

    [POST] {api-domain}/api/payment/channel

    Parameters

    名稱 類型 必填 描述
    agent string 是 商戶號
    由點點金支付客服提供
    sign string 是 請求密鑰加簽參考 附錄 - 加密範例

    Response

    名稱 類型 描述
    code number 代碼
    • 1: 成功
    • -1: 查詢異常
    data array 回傳資料
    data 回傳資料
    名稱 類型 描述
    name string 名稱
    code string 代號
    account string 帳號
    status string 狀態
    • 0: 維護中
    • 1: 正常
    type string 類型
    • 0: 代收
    • 1: 代付

    附錄

    加密範例

    [1] 由點點金支付客服提供
商戶號 = agent

[2] 由後台個人資訊可見
API_KEY = b8bc271e255d830370cc2f49480e16c9

[3] 發送代收資料
data = [
  "agent" => "agent"
  "order_sn" => "AD1234567890"
  "amount" => "1000"
  "bank_name" => "中國信託"
  "bank_branch_code" => "0015"
  "bank_code" => "822"
  "bank_account" => "000011112222"
]

[4] 依照ASCII由小到大做排序
data = [
  "agent" => "agent"
  "amount" => "1000"
  "bank_account" => "000011112222"
  "bank_branch_code" => "0015"
  "bank_code" => "822"
  "bank_name" => "中國信託"
  "order_sn" => "AD1234567890"
]

[5] 將data依照key=value&key1=value1...規則组成字串，最后加上&api_key={API_KEY}
[5_備註] 需將中文進行 url encode, ex. PHP http_build_query(data)
data = "agent=agent&amount=1000&bank_account=000011112222&bank_branch_code=0015&bank_code=822&bank_name=%E4%B8%AD%E5%9C%8B%E4%BF%A1%E8%A8%97&order_sn=AD1234567890&api_key=b8bc271e255d830370cc2f49480e16c9"

[6] 最後將 data 進行 md5 加密
sign=md5(data)
    =md5("agent=agent&amount=1000&bank_account=000011112222&bank_branch_code=0015&bank_code=822&bank_name=%E4%B8%AD%E5%9C%8B%E4%BF%A1%E8%A8%97&order_sn=AD1234567890&api_key=b8bc271e255d830370cc2f49480e16c9")
    =e698a3cc698ad09bb0beca0dbfca9b1a