---
title: "統一金流 API 回 403？少帶 user-agent"
description: "為什麼 Postman 測得過、程式卻 403；怎麼加 user-agent、哪些請求要改、改完還是 403 怎麼辦。"
url: "https://wptoolbear.com/docs/payuni-api-403-user-agent-header/"
updated: "2026-09-13"
category: 統一金流申請
---

# 統一金流 API 回 403？少帶 user-agent

**快速答案：**統一金流的 API 前面有一層雲端防火牆，從伺服器直接打過去的「幕後」請求如果沒帶 `User-Agent` 標頭，會在進到統一金流系統之前就被擋下、回 HTTP 403。在程式的請求標頭加上 user-agent 就好，內容格式不拘。消費者在瀏覽器裡跳轉的付款頁不受影響，因為瀏覽器本來就會帶。

## 為什麼會這樣

統一金流把系統搬上雲端時通知過代理商：之後只要是打進來的幕後請求，不管是金流、物流還是代理商相關的 API，都要在 Request header 帶上 user-agent，否則雲端防火牆（AWS WAF）會依預設規則回 403。這是防火牆擋掉「不像正常用戶端」的請求，跟你的商店代號、金鑰對不對無關。

麻煩的是很多寫法預設不會帶這個標頭。PHP 的 cURL 沒設定就不送 User-Agent；反過來，Postman 和命令列的 curl 會自動帶。所以最典型的症狀是：「Postman 測都正常，程式一跑就 403」。WordPress 內建的 `wp_remote_post` 預設會帶，自己用 cURL 寫的串接最容易漏。如果串接程式是在這個規定之前寫的、又剛好沒帶，就會變成「以前好好的，某天開始 403」。

## 怎麼處理

1. **先分清楚是哪一種錯。**回來的是 API 文件定義的錯誤代碼與訊息，那是參數、簽章或加解密的問題，照文件查；回來的是 HTTP 403、內容不是 API 的回傳格式，先查 user-agent。
2. **在請求加上標頭。**PHP cURL 加一行 `curl_setopt($ch, CURLOPT_USERAGENT, 'MyShop/1.0');`；其他語言或套件，在 header 加上 `User-Agent` 即可。統一金流的說法是「有帶就好、不拘格式」，寫網站或系統名稱加版本號，日後比較好辨認。
3. **每一支幕後請求都要改。**建立交易、查詢交易、退款、物流，只要是伺服器直接呼叫的，全部檢查一遍，不要只改出錯的那一支。
4. **先在測試環境驗證。**統一金流有測試環境，改完先在測試區跑一輪，再更新正式站；測試與正式環境的網址、商店參數要各自對好。
5. **改完還是 403**，把請求的網址、完整標頭、發生時間整理好，交給代理商轉統一金流技術查，比自己猜快。

## 我們實際遇過的情況

這條規則是統一金流專員直接通知代理商的，所以我們的申請頁在「開通後」那一段特別寫明：要串接的，幕後 API 請求需帶 user-agent。另一個常見狀況是寫程式的人不是填申請單的人：有客戶還在等審核，負責做網頁的同事就來問有沒有可以測試的 API，想先把串接做起來。後來申請表多了「技術聯絡人 Email」一欄，送件時就把工程師拉進來，這類技術通知才不會卡在不看程式的人手上。

反方向的問題也很常見：不是你的伺服器打不出去，而是金流的付款通知進不來你的網站，多半是你這邊的防火牆或資安外掛擋掉的，查法見[綠界已扣款、訂單沒更新那篇](https://wptoolbear.com/docs/ecpay-paid-order-still-processing/)。

## 什麼時候該找人

串接程式是前一家廠商寫的、找不到發請求的那段在哪；403 解掉之後又卡在簽章或加解密；或是要串 1shop 這類第三方平台（先問該平台客服是否支援統一金流）。金流程式改錯的代價是收不到錢或重複扣款，正式站不要邊改邊試。

## 常見問題

### user-agent 要填什麼？

格式不拘，有帶就好。建議寫網站或系統名稱加版本號，例如 MyShop/1.0，出問題時比較好辨認。

### 為什麼 Postman 可以、程式卻 403？

Postman 會自動帶 User-Agent，PHP cURL 預設不帶；在程式裡用 CURLOPT_USERAGENT 補上即可。

### 消費者的付款頁也要改嗎？

不用。瀏覽器跳轉的付款頁本來就會帶，要改的是伺服器直接呼叫的幕後 API。

還沒開通？[透過豐遠資訊代理申請統一金流](https://wptoolbear.com/payuni/)（國內卡 2.4%），需要 API 串接的在申請表留下技術聯絡人。要我們替你串接與測試：[架站與整合](https://wptoolbear.com/build/)。