管理預付帳戶餘額

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件
info

如要管理預付帳戶餘額,請按照下列步驟操作:

如何計算預付帳戶的剩餘餘額?

如要查看開發人員或公司的預付帳戶餘額 (如下列章節所述),您需要從回應中取得下列值:

  • 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 付款服務供應商管理預付帳戶餘額。

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 付款服務供應商設定商家帳戶

開始前,請務必先與第三方付款服務供應商 (Worldpay) 聯絡,設定商家帳戶。建議您設定兩個帳戶,一個用於測試,另一個用於正式環境。如要進一步瞭解 Worldpay 商家帳戶,請參閱 www.worldpay.comwp-support.crm.worldpay.com (Worldpay 支援中心)。

設定商家帳戶並收到帳戶憑證後,請按照下列步驟,透過 Worldpay 設定商家帳戶:

  1. 前往 https://secure.worldpay.com/sso/public/auth/login.html
  2. 使用 Worldpay 提供的憑證登入 Worldpay 帳戶。
  3. 設定 XML 密碼和訊息驗證碼 (MAC) 密鑰:
    1. 按一下「個人資料」
    2. 在 Edge 的 XML 密碼欄位中,設定要用於設定 Worldpay 付款服務供應商的密碼。
    3. 在「Redirect MAC secret」欄位中,輸入 20 到 30 個字元的 MAC 密鑰。
    4. 按一下「儲存設定檔」
  4. 將 Apigee Edge 管理伺服器新增至商家 IP 清單 (許可清單):
    1. 依序點選「設定檔」>「商家環境」
    2. 按一下「新增測試 IP」
    3. 輸入 Apigee Edge 管理伺服器的 IP。
    4. 按一下 [儲存]
  5. 設定商家網址,附加 Worldpay 參數,包括方法驗證碼 (MAC):
    1. 依序點選「安裝」>「代管付款頁面」>「付款頁面設計工具」
    2. 在「編輯付款頁面」下方,從「選取管道」下拉式清單中選取安裝 ID。
    3. 在「屬性」分頁中,選取「編輯商家設定」
    4. 將「傳送網址參數」值設為 True
    5. 按一下「發布」分頁標籤。
    6. 按照下列步驟升級變更:
      • 如果是測試環境,請按一下「設計」下方的「升級」,將設計升級至沙箱。
      • 如要將沙箱環境升級為正式環境,請按一下「沙箱」下方的「升級」

在 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 存取付款服務供應商的端點
  • 如果是測試帳戶,請使用: https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
  • 如果是正式版帳戶,請使用: https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp
merchantCode 付款服務供應商提供給 API 消費者的商家代碼
name 供應商的名稱。

僅限 Apigee Edge Private Cloud 客戶:如果是全球付款服務供應商,請確保名稱在所有 Edge 機構中都是唯一的。建議在供應商名稱中加入 WorldPay (不區分大小寫),方便識別。例如:WorldPay testWorldPay prod. 供應商名稱中的空格會轉換為底線。

舉例來說,下列程式碼會設定名為「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

指定是否啟用自動重新載入的旗標 (true)。如要停用自動重新載入,請將這個旗標設為 false

N/A
replenishAmount

預付帳戶餘額必須低於此門檻,才會觸發自動儲值。

N/A
recurringAmount

觸發自動儲值時,要加到預付帳戶餘額的金額。

N/A

遷移至 WorldPay 的代管付款頁面

WorldPay 已更新安全付款處理流程,改用一組新頁面,稱為「代管付款頁面」。

如果您在 2017 年 8 月前,使用已淘汰的安全付款處理流程設定 WorldPay 付款供應商,則必須在 2018 年 1 月前遷移至 WorldPay 的新代管付款頁面。

如要遷移至 WorldPay 的代管付款頁面,請按照下列步驟操作:

  1. 請與 WorldPay 聯絡,將現有帳戶遷移至新的代管付款頁面,並取得帳戶的新安裝 ID
  2. 如「在 Edge 中設定付款服務供應商」一文所述,設定新的 WorldPay 付款服務供應商,並在 authType 欄位中傳遞安裝 ID。
  3. 在開發人員入口網站中設定新的付款服務供應商,詳情請參閱「在開發人員入口網站中設定營利功能」。
  4. 如果使用付款服務供應商設定預付帳戶的自動儲值功能,請按照「使用 API 設定預付帳戶餘額的自動儲值功能」一文所述,重新設定自動儲值功能,並使用新的供應商 ID。

後續步驟

您可以為個別後付開發人員設定信用額度上限。詳情請參閱「管理後付餘額」。