OK WIRE DEVELOPERS

讓全球資金流動，成為產品的一部分。

將全球付款、收款帳戶與資金查詢，整合到你的產品。

REST APIJSONServer-to-server

流程示例REST / JSON

發起請求merchant / balancePOST

https://api.example.com
/v1/merchant/fundPool/balance

{
  "currency": "USD",
  "appKey": "your_app_key",
  "sign": "…"
}

取得結果code: 0

availableBalance12,000 USD

所有請求地址均為示例域名。接入時請替換為獲分配的服務地址。

api.example.com

本頁目錄

01 / 快速開始

從第一個請求開始。

按順序完成配置，再接入你的業務流程。

01
準備接入資料
完成商戶開通，取得 appKey、appSecret 與接入環境資訊。
進入控制台
02
配置服務端認證
在服務端保存密鑰，確認 IP 配置及是否使用加密報文。
簽名與認證
03
完成首次查詢
以餘額查詢驗證簽名、連線及回應解析。
第一個請求
04
接入業務流程
選擇付款或收款接口，處理訂單狀態與異步結果。
瀏覽 API

02 / 第一個請求

第一個請求

使用只讀的資金池餘額查詢熟悉請求格式。示例在服務端執行，不會從此頁發送請求。

export OKWIRE_APP_KEY='your_app_key'
export OKWIRE_APP_SECRET='your_app_secret'
TIMESTAMP="$(date +%s)000"
NONCE="$(openssl rand -hex 12)"
SIGN=$(printf '%s' "appKey=$OKWIRE_APP_KEY&appSecret=$OKWIRE_APP_SECRET&currency=USD&nonce=$NONCE&timestamp=$TIMESTAMP" \
  | openssl dgst -md5 -r | cut -d ' ' -f 1)

curl --request POST \
  'https://api.example.com/v1/merchant/fundPool/balance' \
  --header 'Content-Type: application/json' \
  --data "{\"appKey\":\"$OKWIRE_APP_KEY\",\"currency\":\"USD\",\"timestamp\":$TIMESTAMP,\"nonce\":\"$NONCE\",\"sign\":\"$SIGN\"}"

Node.js 18+ / Python 3：先在服務端設定 OKWIRE_APP_KEY 與 OKWIRE_APP_SECRET 環境變數。此示例只處理平面欄位。

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "data": [
      {
        "fundPoolId": 1001,
        "merchantId": 2001,
        "currency": "USD",
        "balance": 12500,
        "frozenBalance": 500,
        "availableBalance": 12000,
        "status": 1,
        "channel": 0
      }
    ]
  }
}

示例回應 · 金額與 ID 為虛構資料

code 為 0 表示業務請求成功；餘額列表位於 data.data。請同時處理 HTTP 錯誤與非零業務代碼。

03 / 簽名與認證

簽名與認證

已簽名的 JSON 接口將認證欄位放在請求體中。appSecret 僅在本地參與簽名，不隨請求發送。

appKeystring必填

商戶應用識別碼

timestampinteger必填

Unix 時間戳，毫秒

noncestring必填

每次請求產生的新隨機字串

signstring必填

小寫十六進位 MD5 簽名

排除 sign；加入 appSecret；跳過空字串與 null，保留 0 和 false。
按欄位名稱升序排序，以 key=value 串接，使用 & 分隔；末尾不加 &，不做 URL 編碼。
對 UTF-8 字串計算 MD5，輸出小寫十六進位；將 sign 加入原請求體。

物件與陣列如何簽名？

物件與陣列使用緊湊 JSON 字串參與簽名，需與服務端 Go encoding/json 的序列化結果一致：物件鍵名排序、保留陣列順序，並注意特殊字元轉義及數字格式。不要直接將物件轉為普通字串。

加密報文模式

如使用加密報文，請同時提供 appKey、sKey、sIv 請求標頭。報文使用 AES-CBC，密鑰及 IV 使用 RSA PKCS#1 v1.5 加密；接入前確認雙方公鑰配置。上方示例展示 JSON 簽名模式。

文件上傳的認證

上傳使用 multipart/form-data，必填文字欄位為 appKey、timestamp、sign。將所有非空文字欄位（排除 sign）與 appSecret 排序後簽名，文件內容不參與。timestamp 允許前後 15 分鐘偏差。tagIds 目前接受單個 ID 的文字值。

04 / API 參考

API 參考

依業務選擇接口，展開查看請求地址、認證方式與業務欄位。

24 個接口

POST建立付款訂單/v1/tf/order/create

提交付款資料與商戶訂單號；所需收款資料依目的地及付款方式而定。

JSON 簽名application/json

https://api.example.com/v1/tf/order/create

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

orderNostring必填
extstring選填
transferTypeinteger · 1 2 3必填
transferSegmentinteger · 1 2必填
sourceCurrencyTypeinteger · 1 2 3必填
sourceCurrencystring必填
destinationCurrencyTypeinteger · 1 2 3必填
destinationCurrencystring必填
cardNumberstring必填
amountnumber必填
notifyUrlstring選填
remarkstring選填
channelinteger · 1 2必填
customerIdstring必填
firstNamestring必填
lastNamestring必填
countrystring選填
citystring選填
addressstring選填
postcodestring選填
sortCodestring選填
routingNumberstring選填
bsbCodestring選填
ifscstring選填
ibanstring選填
bicstring選填
clabestring選填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢付款訂單列表/v1/tf/order/list

分頁查詢付款訂單與處理狀態。

JSON 簽名application/json

https://api.example.com/v1/tf/order/list

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

pageinteger必填
pageSizeinteger必填
merOrderNostring選填
sourceCurrencyTypeinteger選填
cardNumberstring選填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢付款訂單/v1/tf/order

使用系統訂單 ID 查詢详情；id 並非商戶 orderNo。

JSON 簽名application/json

https://api.example.com/v1/tf/order

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

idinteger必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢付款產品列表/v1/tf/transfer_product/list

查閱可用付款產品及設定。

JSON 簽名application/json

https://api.example.com/v1/tf/transfer_product/list

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

pageinteger必填
pageSizeinteger必填
namestring選填
statusinteger選填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢付款產品/v1/tf/transfer_product

按產品 ID 查詢付款產品詳情。

JSON 簽名application/json

https://api.example.com/v1/tf/transfer_product

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

idinteger必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST建立客戶登記/v1/va/user/registration/create

提交客戶 KYC 資料；個人、公司、法人及實益擁有人資料依 KYC 類型提供。

JSON 簽名application/json

https://api.example.com/v1/va/user/registration/create

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST更新客戶登記/v1/va/user/registration/update

使用 vaUserId 更新登記資料。

JSON 簽名application/json

https://api.example.com/v1/va/user/registration/update

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢登記詳情/v1/va/user/registration/detail

查閱客戶登記資料與審核狀態。

JSON 簽名application/json

https://api.example.com/v1/va/user/registration/detail

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

vaUserIdstring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢客戶列表/v1/va/user/list

分頁查詢已登記的收款客戶。

JSON 簽名application/json

https://api.example.com/v1/va/user/list

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST申請收款帳戶/v1/va/account/apply

為已登記客戶申請收款帳戶；開戶資料及可用幣種依業務配置而定。

JSON 簽名application/json

https://api.example.com/v1/va/account/apply

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢收款帳戶列表/v1/va/account/list

依帳號、幣種或狀態篩選收款帳戶。

JSON 簽名application/json

https://api.example.com/v1/va/account/list

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢收款帳戶/v1/va/account/detail

使用 vaAccountId 查詢帳戶詳情。

JSON 簽名application/json

https://api.example.com/v1/va/account/detail

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

vaAccountIdstring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢收款記錄列表/v1/va/collection/records/list

依幣種、日期、帳號等條件分頁查詢收款記錄。

JSON 簽名application/json

https://api.example.com/v1/va/collection/records/list

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢收款記錄/v1/va/collection/records

使用 vaCollectionId 查詢單筆收款及補充資料狀態。

JSON 簽名application/json

https://api.example.com/v1/va/collection/records

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

vaCollectionIdstring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST提交收款補充資料/v1/va/collection/records/attachment/submit

提交上傳後的文件 ID 與附件資料；資料需經審核。

JSON 簽名application/json

https://api.example.com/v1/va/collection/records/attachment/submit

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

vaCollectionIdstring必填
attachmentTypestring必填
attachmentsstring必填
unitIdstring必填
fileIdsstring[]必填
webStoreUrlstring依業務條件
senderInfoobject依業務條件
- companyNamestring必填
- legalNamestring必填
- addressstring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢收款淨額彙總/v1/va/collection/records/balance/summary

按帳號及幣種彙總收款淨額；此數值不代表可用餘額。

JSON 簽名application/json

https://api.example.com/v1/va/collection/records/balance/summary

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

accountNostring必填
currencystring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢資金池餘額/v1/merchant/fundPool/balance

查詢當前商戶的餘額、凍結金額及可用餘額，可按幣種篩選。

JSON 簽名application/json

https://api.example.com/v1/merchant/fundPool/balance

業務請求欄位

另需加入 appKey、timestamp、nonce、sign；詳見簽名與認證。

currencystring選填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢匯率列表/v1/tf/quote/all

查閱匯率報價列表。

無簽名參數application/json

https://api.example.com/v1/tf/quote/all

業務請求欄位

無業務請求欄位，可傳送空 JSON 物件。

POST查詢幣種對報價/v1/tf/quote

指定來源與目標幣種查詢匯率。

無簽名參數application/json

https://api.example.com/v1/tf/quote

業務請求欄位

sourceCurrencystring必填
destinationCurrencystring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢國家列表/v1/tf/country/list

取得目的地國家代碼及名稱。

無簽名參數application/json

https://api.example.com/v1/tf/country/list

業務請求欄位

無業務請求欄位，可傳送空 JSON 物件。

POST查詢幣種與付款方式/v1/tf/currency/partner

按國家與通道類型查詢支持的幣種和通道夥伴。

無簽名參數application/json

https://api.example.com/v1/tf/currency/partner

業務請求欄位

typestring必填
countrystring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢業務模式/v1/tf/business/mode

查詢指定國家及業務類型支持的模式。

無簽名參數application/json

https://api.example.com/v1/tf/business/mode

業務請求欄位

countrystring必填
typestring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST查詢銀行列表/v1/tf/bank/list

取得指定國家的銀行代碼及名稱。

無簽名參數application/json

https://api.example.com/v1/tf/bank/list

業務請求欄位

countrystring必填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

POST上傳文件/v1/file/upload

使用 multipart/form-data 上傳文件；簽名由非空文字欄位計算，文件內容不參與簽名。

表單簽名multipart/form-data

https://api.example.com/v1/file/upload

業務請求欄位

filebinary必填
fileTypeinteger選填
tagIdsstring選填

依業務條件必填的資料，請配合客戶類型、付款方式及接入配置提供。展開物件可查看子欄位。

05 / 異步通知

異步通知

為付款訂單提供通知地址，並將查單接口納入結果確認流程。

設定接收地址

付款建立請求可提供 notifyUrl。通知欄位、驗簽方式與重試約定，請在接入聯調時確認。

https://merchant.example.com/webhooks/okwire

可靠地處理結果

建議以訂單識別碼去重，驗證通知來源後更新狀態；遇到重複通知或不確定結果時，使用查詢接口核實。

查詢付款與收款狀態

BUILD WITH OK WIRE

準備接入你的下一個流程？

從商戶開通開始，讓產品與全球收付款連接。

進入控制台

讓全球資金流動，成為產品的一部分。

從第一個請求開始。

準備接入資料

配置服務端認證

完成首次查詢

接入業務流程

第一個請求

簽名與認證

API 參考

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

異步通知

設定接收地址

可靠地處理結果

準備接入你的下一個流程？