您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info
如要管理預付帳戶餘額,請按照下列步驟操作:
- 查看目前的預付帳戶餘額。請參閱「使用 API 查看預付帳戶餘額」。
- 使用 Worldpay 等第三方付款服務供應商,視需要為帳戶餘額加值 (存入款項)。請參閱「透過第三方付款服務供應商管理預付餘額」。
或者,您也可以手動或透過整合式結帳系統追蹤付款,然後呼叫營利 API 重新載入帳戶,如「手動管理預付餘額」一文所述。
- 使用 Monetization API 和第三方付款服務供應商 (例如 Worldpay),在預付帳戶餘額低於特定門檻時設定自動儲值。這個選項有助於管理費率方案的週期性付款。詳情請參閱「使用 API 設定預付帳戶餘額自動儲值」。
如何計算預付帳戶的剩餘餘額?
如要查看開發人員或公司的預付帳戶餘額 (如下列章節所述),您需要從回應中取得下列值:
amount:目前帳單週期可用的總金額。使用本節所述方法重新加值預付帳戶時,這個值會更新。usage:目前帳單週期內使用的總金額。每當有符合資格的營利交易,或發放抵免額 (正數或負數) 時,這個值就會更新。
如要計算目前帳單週期的預付帳戶餘額,請從 amount 值中減去 usage 值。舉例來說,如果 amount 值為 335.50,而 usage 值為 34,則剩餘餘額的計算方式如下:
amount(335.50) - usage(34) = 229.50使用 API 查看預付帳戶餘額
以下各節說明如何使用 API,查看開發人員或公司的預付帳戶餘額。
查看開發人員的預付帳戶餘額
如要查看開發人員的預付帳戶餘額,請對下列其中一個 API 發出 GET 要求,其中 {developer_id} 是開發人員的電子郵件地址:
/mint/organizations/{org_name}/developers/{developer_id}/developer-balances:為開發人員傳回預付帳戶餘額和定期設定資訊。/mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances:傳回預付帳戶餘額資訊,包括目前和總餘額、用量、儲值和使用稅。
您可以傳遞下列查詢參數來篩選結果:
| 查詢參數 | 說明 |
|---|---|
all |
這個旗標會指定是否要傳回所有 API 套件。如果設為 false,則每頁傳回的 API 套件數量由 size 查詢參數定義。預設值為 false。 |
size |
每個頁面傳回的 API 套件數量。預設值為 20。如果 all 查詢參數設為 true,系統會忽略這個參數。 |
page |
要傳回的頁碼 (如果內容已分頁)。如果 all 查詢參數設為 true,系統會忽略這個參數。 |
currencyId |
要查看預付帳戶餘額的幣別 ID。 |
例如:
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password
以下是回應範例:
{ "developerBalance": [ { "amount": 2005, "chargePerUsage": false, "id": "your-provider-id", "isRecurring": false, "supportedCurrency": { "description": "United States Dollars", "displayName": "United States Dollars", "id": "usd", "name": "USD", "organization": { "address": [ { "address1": "10 Almaden Blvd.", "city": "San Jose", "country": "US", "id": "32e808d8-3a3c-4d76-a0ae-17d70a982c61", "isPrimary": true, "state": "CA", "zip": "95113" } ], "approveTrusted": false, "approveUntrusted": false, "billingCycle": "CALENDAR_MONTH", "country": "US", "currency": "USD", "description": "my-org", "groupOrganization": false, "hasBillingAdjustment": false, "hasBroker": false, "hasSelfBilling": false, "hasSeparateInvoiceForProduct": false, "id": "my-org", "issueNettingStmt": false, "name": "my-org", "nettingStmtPerCurrency": false, "selfBillingAsExchOrg": false, "selfBillingForAllDev": false, "separateInvoiceForFees": false, "status": "ACTIVE", "supportedBillingType": "BOTH", "taxModel": "HYBRID", "timezone": "UTC" }, "status": "ACTIVE", "virtualCurrency": false }, "usage": 2.1572 } ], "totalRecords": 1 }
查看公司的預付帳戶餘額
如要查看公司的預付帳戶餘額,請對 /mint/organizations/{org_name}/companies/{company_id}/developer-balances 發出 GET 要求,其中 {company_id} 是公司的 ID。如果公司採用預付方式,要求會擷取目前的預付帳戶餘額。如果公司採用後付方案,這項要求會擷取目前的信用額度。
您可以傳遞下列查詢參數來篩選結果:
| 查詢參數 | 說明 |
|---|---|
all |
這個旗標會指定是否要傳回所有 API 套件。如果設為 false,則每頁傳回的 API 套件數量由 size 查詢參數定義。預設值為 false。 |
size |
每個頁面傳回的 API 套件數量。預設值為 20。如果 all 查詢參數設為 true,系統會忽略這個參數。 |
page |
要傳回的頁碼 (如果內容已分頁)。如果 all 查詢參數設為 true,系統會忽略這個參數。 |
currencyId |
要查看預付帳戶餘額的幣別 ID。 |
例如:
$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password
查看開發人員的預付帳戶餘額時,回應內容與上文所示的回應類似。
透過付款服務供應商管理預付帳戶餘額
如要管理預付帳戶餘額,請透過第三方付款服務供應商 (例如 Worldpay) 設定商家帳戶。下圖說明如何使用 Worldpay 付款服務供應商管理預付帳戶餘額。

下表說明上述預付帳戶餘額管理流程的每個步驟。
| 步驟 | 說明 |
|---|---|
| 0 |
事前準備步驟 身為 API 供應商,如要設定第三方付款服務供應商 (例如 Worldpay),您必須: |
| 1 |
如要觸發流程,API 消費者必須在開發人員入口網站中執行下列其中一項工作:
|
| 2 | 開發人員入口網站會透過 Edge 為開發人員啟動付款程序,並提供供應商 ID、重新載入金額和幣別。如要瞭解如何使用 API 啟動付款程序,請參閱「使用付款服務供應商向預付帳戶付款」。 |
| 3 | Edge 會依據 ID 尋找供應商,並判斷這是 Worldpay 帳戶。 |
| 4 | Edge 會產生訂單代碼。 |
| 5 | Edge 會在 Worldpay 上建立付款通知。 |
| 6 | Worldpay 會傳回訂單的參照 ID,以及在時限內完成訂單的網址。 |
| 7 |
Worldpay 的回應會轉換為一般 Edge /payment API 回應,並傳回開發人員入口網站,完成步驟 2 中啟動的呼叫。例如:
{
"isRecurring": "false",
"orderCode": "1234",
"referenceId": "3042815493",
"referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
"success": "true"
}
|
| 8 | 開發人員入口網站會將回呼網址 (適用於成功、失敗等情況) 做為查詢參數附加至網址。 |
| 9 | 開發人員入口網站會重新導向 API 消費者的瀏覽器至修改後的網址,以回應步驟 1 的要求。 |
| 10 | API 消費者填寫申請表,並透過 Worldpay 啟動處理程序。 |
| 11 | Worldpay 會擷取帳單資訊並處理付款。成功後,Worldpay 會使用在 Worldpay 和開發人員入口網站上設定的 MAC 密鑰,產生訊息驗證碼 (MAC)。 |
| 12 | Worldpay 會將 API 消費者的瀏覽器重新導向至成功的回呼網址 (步驟 8),並附加 MAC 做為查詢參數和金額。 |
| 13 | 瀏覽器會使用要求的金額和 MAC,在開發人員入口網站上呼叫網址。 |
| 14 | 入口網站會根據 MAC 密鑰驗證 MAC。MAC 可防止使用者任意聲稱已成功付款。 |
| 15 | 開發人員入口網站會傳送要求給 Edge,重新載入預付帳戶餘額。如要瞭解如何使用 API 重新載入帳戶餘額,請參閱「使用 API 重新載入預付帳戶餘額」。 |
下列各節說明如何使用第三方付款服務供應商管理預付餘額:
- 透過 Worldpay 付款服務供應商設定商家帳戶
- 在 Edge 中設定付款服務供應商
- 查看為貴機構設定的付款服務供應商
- 在開發人員入口網站中啟用及設定必要模組
- 使用付款服務供應商為預付帳戶付款
- 使用 API 重新載入預付帳戶餘額
- 刪除第三方付款服務供應商
向 Worldpay 付款服務供應商設定商家帳戶
開始前,請務必先與第三方付款服務供應商 (Worldpay) 聯絡,設定商家帳戶。建議您設定兩個帳戶,一個用於測試,另一個用於正式環境。如要進一步瞭解 Worldpay 商家帳戶,請參閱 www.worldpay.com 和 wp-support.crm.worldpay.com (Worldpay 支援中心)。
設定商家帳戶並收到帳戶憑證後,請按照下列步驟,透過 Worldpay 設定商家帳戶:
- 前往 https://secure.worldpay.com/sso/public/auth/login.html。
- 使用 Worldpay 提供的憑證登入 Worldpay 帳戶。
- 設定 XML 密碼和訊息驗證碼 (MAC) 密鑰:
- 按一下「個人資料」。
- 在 Edge 的 XML 密碼欄位中,設定要用於設定 Worldpay 付款服務供應商的密碼。
- 在「Redirect MAC secret」欄位中,輸入 20 到 30 個字元的 MAC 密鑰。
- 按一下「儲存設定檔」
- 將 Apigee Edge 管理伺服器新增至商家 IP 清單 (許可清單):
- 依序點選「設定檔」>「商家環境」。
- 按一下「新增測試 IP」。
- 輸入 Apigee Edge 管理伺服器的 IP。
- 按一下 [儲存]。
- 設定商家網址,附加 Worldpay 參數,包括方法驗證碼 (MAC):
- 依序點選「安裝」>「代管付款頁面」>「付款頁面設計工具」。
- 在「編輯付款頁面」下方,從「選取管道」下拉式清單中選取安裝 ID。
- 在「屬性」分頁中,選取「編輯商家設定」。
- 將「傳送網址參數」值設為 True。
- 按一下「發布」分頁標籤。
- 按照下列步驟升級變更:
- 如果是測試環境,請按一下「設計」下方的「升級」,將設計升級至沙箱。
- 如要將沙箱環境升級為正式環境,請按一下「沙箱」下方的「升級」。
在 Edge 中設定付款服務供應商
下一步是在 Edge 中設定付款服務供應商。
您可以使用下列 API,為特定機構設定付款服務供應商:
/organizations/{org-name}/providers僅限 Apigee Edge Private Cloud 客戶,且須具備系統管理員權限,才能使用下列 API 選擇性設定全域付款服務供應商:
/config/providers
呼叫每個 API 時,您必須在要求主體中指定下列資訊:
| 參數 | 說明 | 必要 |
authType |
付款服務供應商提供的安裝 ID。 | 是 |
credential |
Worldpay 商家帳戶的 Base64 編碼憑證 (username:XMLpassword);username 等於商家代碼 (全大寫),XMLpassword 則指定您在先前設定 Worldpay 商家帳戶時設定的 XML 密碼。 |
是 |
description |
付款服務供應商說明。 | 否 |
endpoint |
存取付款服務供應商的端點
|
是 |
merchantCode |
付款服務供應商提供給 API 消費者的商家代碼 | 是 |
name |
供應商的名稱。
僅限 Apigee Edge Private Cloud 客戶:如果是全球付款服務供應商,請確保名稱在所有 Edge 機構中都是唯一的。建議在供應商名稱中加入 WorldPay (不區分大小寫),方便識別。例如: |
是 |
舉例來說,下列程式碼會設定名為「Worldpay-myorg」的 Worldpay 商家帳戶:
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"name": "Worldpay-myorg",
"description": "Worldpay payment provider",
"endpoint": "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
"authType": "123456",
"credential": "dXNlcm5hbWU6cGFzc3dvcmQ=",
"merchantCode": "myMerchantCode"
}' \
"https://api.enterprise.apigee.com/v1/organizations/myOrg/providers" \
-u email:password
查看第三方付款服務供應商
對下列資源發出 GET 要求,即可查看並確認為 Edge 機構設定的第三方付款服務供應商:
/mint/organizations/{org-name}/providers
舉例來說,以下畫面會顯示目前為 myorg 設定的第三方付款服務供應商:
$ curl -X GET \ "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers" \ -u email:password
以下是回應範例,顯示兩個商家帳戶,一個用於測試,另一個用於正式環境。
{
"provider" : [ {
"authType" : "123456",
"credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
"description" : "Worldpay payment provider",
"endpoint" : "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
"id" : "worldpay-myorg",
"merchantCode" : "MERCH_CODE",
"name" : "Worldpay-myorg"
}, {
"authType" : "123456",
"credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
"description" : "Worldpay payment provider",
"endpoint" : "https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp",
"id" : "worldpay-test",
"merchantCode" : "MERCH_CODE_FROM_PROVIDER",
"name" : "Worldpay-test"
} ]
}
在開發人員入口網站中啟用及設定營利和 Worldpay 模組
在開發人員入口網站中啟用必要的「Monetization」和「Worldpay」模組。詳情請參閱在開發人員入口網站中設定營利。
使用付款服務供應商為預付帳戶付款
如預付帳戶管理流程的步驟 2 所示,當 API 消費者:
- 接受費率方案,但預付帳戶餘額不足
- 要求為預付帳戶儲值。
如要使用 API 從第三方付款服務供應商發起付款,請對下列資源發出 POST 要求,其中 {developer_id} 是開發人員的電子郵件地址。
/mint/organizations/{org_name}/developers/{developer_id}/payment?amount={amount}&provider={providerId}&supportedCurrencyId={currency}
發出要求時,您需要指定下列值做為查詢參數:
- 要新增至預付帳戶餘額的金額 (
amount={amount}) - 付款服務供應商 ID (
provider={providerId}) - 支援的幣別 (
supportedCurrencyId={currency})
此外,您還需要傳遞基本帳戶詳細資料,例如公司帳單地址。
舉例來說,以下程式碼會使用 Worldpay 付款服務供應商,重新載入預付帳戶餘額。預付帳戶的初始轉移金額為 10 美元 (amount
查詢參數設為 10)。
$ curl -H "Content-Type:application/xml" -X POST -d \
'{
"address1": "5115 Hopyard Ave.",
"city": "Pleasanton",
"country": "US",
"state": "CA",
"zip": "58158"
}'
' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/payment?amount=10&provider=worldpay-myorg&supportedCurrencyId=usd" \
-u email:password
以下是回應範例:
{
"isRecurring": "false",
"orderCode": "1234",
"referenceId": "3042815493",
"referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
"success": "true"
}
Worldpay 安全付款頁面的網址會以 referenceUrl 傳回,並附加專屬訂單金鑰做為查詢參數。
使用 API 重新載入預付帳戶餘額
如預付帳戶管理流程的步驟 15 所示,驗證付款服務供應商已成功處理後,開發人員入口網站會傳送要求給 Edge,重新載入預付帳戶。
開發人員或公司可以使用 API 重新載入預付帳戶餘額,詳情請參閱下列各節。
為開發人員的預付帳戶餘額加值
如要使用 API 為開發人員的預付帳戶餘額加值,請對 /mint/organizations/{org_name}/developers/{developer_id}/developer-balances 發出 POST 要求,其中 {developer_id} 是開發人員的電子郵件地址。發出要求時,您需要在要求主體中指定要加到餘額的金額和使用的幣別。
舉例來說,下列要求會將 $1000 美元新增至開發人員的預付帳戶餘額:
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"amount": 1000,
"supportedCurrency": {
"id": "usd"
}
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password
如需要求屬性的說明,請參閱「重新載入預付帳戶的要求屬性摘要」。
為公司重新加值預付帳戶餘額
如要使用 API 為公司重新加值預付帳戶餘額,請對 /mint/organizations/{org_name}/companies/{company_id}/developer-balances 發出 POST 要求,其中 {company_id} 是公司的 ID。發出要求時,您需要在要求主體中指定要加到餘額的金額和使用的幣別。
舉例來說,下列要求會將 $1000 美元新增至公司的預付帳戶餘額:
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"amount": 1000,
"supportedCurrency": {
"id": "usd"
}
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password
如需要求屬性的說明,請參閱「重新載入預付帳戶的要求屬性摘要」。
重新載入預付帳戶的請求屬性摘要
使用 API 重新載入預付帳戶餘額時,必須指定下列屬性:
| 名稱 | 說明 | 預設 | 是否必要? |
|---|---|---|---|
amount |
套用至預付餘額的金額 (以適用貨幣計算)。 |
N/A | 是 |
supportedCurrency |
預付餘額使用的幣別。這是開發人員購買的 API 套件方案所設定的幣別。 |
N/A | 是 |
刪除第三方付款服務供應商
如要刪除為 Edge 機構設定的第三方付款服務供應商,請對下列資源發出 DELETE 要求:
如要刪除特定機構的付款服務供應商,請使用下列 API:
/mint/organizations/{org-name}/providers/id僅限 Apigee Edge Private Cloud 客戶,且須具備系統管理員權限,才能使用下列 API 選擇性刪除全球付款服務供應商:
/config/providers/id
舉例來說,下列指令會刪除目前為 myorg 設定的第三方付款服務供應商:
$ curl -X DELETE \ "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers/worldpay-myorg" \ -u email:password
手動管理預付帳戶餘額
或者,您也可以手動追蹤付款或透過整合式結帳系統,管理預付餘額的儲值作業,然後呼叫營利 API 為帳戶儲值,如「使用 API 為預付帳戶餘額儲值」一文所述。
使用 API 設定預付帳戶餘額自動加值
以下各節說明如何使用第三方付款服務供應商,為開發人員或公司的預付帳戶餘額設定自動加值。這個選項有助於管理費率方案的週期性付款。
為開發人員設定預付帳戶餘額自動儲值
如要設定在開發人員的預付帳戶餘額低於特定門檻時自動儲值,請對 /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup 發出 POST 要求,其中 {developer_id} 是開發人員的電子郵件地址。
發出要求時,您必須指定下列項目:
- 用來為帳戶加值的付款服務供應商 ID (
providerID) - 啟用自動重新載入的旗標 (
isRecurring) - 預付帳戶餘額必須低於此門檻,才會觸發自動儲值 (
replenishAmount) - 自動加到帳戶的金額 (
recurringAmount) supportedCurrencyID查詢參數來指定幣別。
在下列範例中,當開發人員的預付帳戶餘額低於 5 美元時,系統會自動為帳戶加值 10 美元。
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"providerId": "worldpay-myorg",
"isRecurring" : true,
"replenishAmount" : 5,
"recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password
如需要求屬性的說明,請參閱設定預付帳戶自動重載功能的要求屬性摘要。
為公司設定預付帳戶餘額自動儲值
如要設定公司預付帳戶餘額自動加值,請在餘額低於特定金額時,對 /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup 發出 POST 要求,其中 {company_id} 是公司 ID。
發出要求時,您必須指定下列項目:
- 用來為帳戶加值的付款服務供應商 ID (
providerID) - 啟用自動重新載入的旗標 (
isRecurring) - 預付帳戶餘額必須低於此門檻,才會觸發自動儲值 (
replenishAmount) - 自動加到帳戶的金額 (
recurringAmount) supportedCurrencyID查詢參數來指定幣別。
在下列範例中,當公司的預付帳戶餘額低於 5 美元時,系統會自動為帳戶加值 10 美元。
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"providerId": "worldpay-myorg",
"isRecurring" : true,
"replenishAmount" : 5,
"recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password
如需要求屬性的說明,請參閱設定預付帳戶自動重載功能的要求屬性摘要。
設定預付帳戶自動儲值的要求屬性摘要
使用 API 自動重新載入預付帳戶餘額時,可以指定下列屬性。
| 名稱 | 說明 | 預設 | 是否必要? |
|---|---|---|---|
providerId |
付款服務供應商的 ID。 |
N/A | 是 |
chargePerUsage |
false | 否 | |
isRecurring |
指定是否啟用自動重新載入的旗標 ( |
N/A | 是 |
replenishAmount |
預付帳戶餘額必須低於此門檻,才會觸發自動儲值。 |
N/A | 是 |
recurringAmount |
觸發自動儲值時,要加到預付帳戶餘額的金額。 |
N/A | 是 |
遷移至 WorldPay 的代管付款頁面
WorldPay 已更新安全付款處理流程,改用一組新頁面,稱為「代管付款頁面」。
如果您在 2017 年 8 月前,使用已淘汰的安全付款處理流程設定 WorldPay 付款供應商,則必須在 2018 年 1 月前遷移至 WorldPay 的新代管付款頁面。
如要遷移至 WorldPay 的代管付款頁面,請按照下列步驟操作:
- 請與 WorldPay 聯絡,將現有帳戶遷移至新的代管付款頁面,並取得帳戶的新安裝 ID。
- 如「在 Edge 中設定付款服務供應商」一文所述,設定新的 WorldPay 付款服務供應商,並在
authType欄位中傳遞安裝 ID。 - 在開發人員入口網站中設定新的付款服務供應商,詳情請參閱「在開發人員入口網站中設定營利功能」。
- 如果使用付款服務供應商設定預付帳戶的自動儲值功能,請按照「使用 API 設定預付帳戶餘額的自動儲值功能」一文所述,重新設定自動儲值功能,並使用新的供應商 ID。
後續步驟
您可以為個別後付開發人員設定信用額度上限。詳情請參閱「管理後付餘額」。