OK WIRE DEVELOPERS

跨境收付款 API，整合企業業務流程。

接入單筆付款、客戶登記、收款帳戶及收款與資金餘額查詢。

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 / 快速開始

API 接入流程

完成接入配置與查詢驗證後，整合所需業務接口。

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 接口在請求本文內傳送 appKey、timestamp、nonce、sign，並校驗時間範圍及重複請求。appSecret 僅在服務端參與簽名，不隨請求傳送；重試時須重新產生認證參數。

appKeystring必填

商戶應用識別碼

timestampinteger必填

Unix 毫秒時間戳，允許前後 15 分鐘偏差

noncestring必填

每次請求使用新的隨機字串，最多 256 字元，不含 &、= 或控制字元

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；nonce 可選，提供時須符合字串規則。非空文字欄位（排除 sign）與 appSecret 排序後簽名，文件內容不參與。時間戳允許前後 15 分鐘偏差，請勿重複傳送同一簽名；各文字欄位僅傳單一值，不使用 URL 查詢參數。tagIds 目前接受單個 ID 文字值。

04 / API 參考

API 參考

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

24 個接口

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

以 orderNo 提交商戶付款參考及單筆付款資料；收款人、銀行與用途欄位依付款產品要求提供。

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

分頁查詢付款訂單及處理狀態；可用 merOrderNo 篩選商戶訂單號，取得系統訂單 ID。

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 不可直接作為 id。

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

提交客戶身分核實資料；依客戶類型提供個人、企業、法定代表人及實益擁有人等所需資訊。

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

查詢當前商戶各幣種資金帳戶的識別碼、帳戶餘額、凍結餘額、可用餘額及狀態，可按 currency 篩選。

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

通知驗證與狀態核對

驗證通知來源，依訂單識別碼及業務狀態處理重複通知。API 查單詳情使用系統訂單 ID；如僅有商戶訂單號，可先使用列表接口的 merOrderNo 篩選取得 ID，再核對處理結果。

查詢付款與收款狀態

BUILD WITH OK WIRE

諮詢 API 接入方案

完成商戶開通與接入配置，整合企業跨境收付款服務。

進入企業管理平台

跨境收付款 API，整合企業業務流程。

API 接入流程

準備接入資料

配置服務端認證

完成首次查詢

接入業務流程

資金餘額查詢

簽名與認證

API 參考

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

業務請求欄位

異步通知

設定接收地址

通知驗證與狀態核對

諮詢 API 接入方案