管理預付帳戶餘額

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

如要管理預付帳戶的餘額，你可以：

• 查看目前的預付帳戶餘額。詳情請參閱使用 API 查看預付帳戶餘額。
• 視需要透過 Worldpay 等第三方付款服務供應商重新載入帳戶餘額 (儲值)。詳情請參閱透過第三方付款服務供應商管理預付餘額。

  此外，您也可以按照手動管理預付餘額的說明，手動追蹤付款或透過整合式帳單系統追蹤款項，然後呼叫營利 API 重新載入帳戶，藉此管理重新載入作業。

• 使用營利 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：傳回預付帳戶餘額資訊，包括目前和總餘額、用量、儲值金額和使用稅。

您可以傳遞下列查詢參數來篩選結果：

例如：

$ 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。如果公司是預付費用，要求就會擷取目前的預付帳戶餘額。如果公司是後付型公司，要求就會擷取目前的信用額度上限。

您可以傳遞下列查詢參數來篩選結果：

例如：

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

下表說明預付帳戶餘額管理流程中的每個步驟，如上所示。

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

以下各節說明透過第三方付款服務供應商管理預付餘額的步驟：

• 透過 Worldpay 付款服務供應商設定商家帳戶
• 在 Edge 中設定付款服務供應商
• 查看為貴機構設定的付款服務供應商
• 在開發人員入口網站啟用及設定必要模組
• 透過付款服務供應商將款項匯入預付帳戶
• 使用 API 重新載入預付帳戶餘額
• 刪除第三方付款服務供應商

透過 Worldpay 付款服務供應商設定商家帳戶

開始之前，您必須先聯絡第三方付款服務供應商 (Worldpay) 來設定商家帳戶。建議您設定兩個帳戶：一個用於測試，另一個用於正式版。如要進一步瞭解 Worldpay 商家帳戶，請造訪 www.worldpay.com 和 wp-support.crm.worldpay.com (Worldpay 支援中心)。

設定商家帳戶並取得帳戶憑證之後，如要使用 Worldpay 設定商家帳戶：

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

在 Edge 中設定付款服務供應商

下一步是在 Edge 中設定付款服務供應商。

您可以使用下列 API 為特定機構設定付款服務供應商：

/organizations/{org-name}/providers

只有具備系統管理員權限的 Apigee Edge Private Cloud 客戶，可選擇使用下列 API 設定全球付款服務供應商：

/config/providers

呼叫每個 API 時，您必須在要求主體中指定下列資訊：

舉例來說，下列指令會設定名為 Worldpay-myorg 的商家帳戶：

$ 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 模組

在開發人員入口網站中啟用必要的「營利」和「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"
}

系統會以 referenceUrl 傳回「Worldpay Secure Payment」頁面的網址，並以查詢參數附加不重複的訂單金鑰。

使用 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 重新載入預付帳戶餘額時，您必須指定下列屬性：

刪除第三方付款服務供應商

您可以向下列資源發出 DELETE 要求，藉此刪除為 Edge 機構設定的第三方付款服務供應商：

如要刪除「特定機構」的付款服務供應商，請使用下列 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 設定自動重新載入預付帳戶餘額

以下各節將說明如何透過第三方付款服務供應商，為開發人員或公司設定自動重新載入預付帳戶餘額。這個選項適合管理費率方案的週期性付款。

為開發人員設定自動重新載入預付帳戶餘額

如要為開發人員設定自動重新載入預付帳戶餘額，使其餘額低於特定門檻，請向 /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 自動重新載入預付帳戶餘額時，您可以指定下列屬性。

遷移至 WorldPay 代管的付款網頁

WorldPay 已更新安全付款處理流程，改用新的網頁組合 (稱為「代管付款頁面」)。

如果您設定了 WorldPay 付款服務供應商 (在 2017 年 8 月前使用已淘汰的安全付款處理流程)，請務必在 2018 年 1 月前遷移至 WorldPay 新版「代管付款網頁」。

若要遷移至 WorldPay 代管的付款網頁：

1. 請與 WorldPay 聯絡，要求對方遷移您目前的帳戶，改用新版代管付款頁面，並為您的帳戶取得新的安裝 ID。
2. 按照「在 Edge 中設定付款服務供應商」的說明設定新的 WorldPay 付款服務供應商，並在 authType 欄位中傳遞安裝 ID。
3. 按照在開發人員入口網站中設定營利功能的說明，在開發人員入口網站上設定新的付款服務供應商。
4. 如果您透過付款服務供應商設定自動重新載入預付帳戶，則必須重新設定自動重新載入，以使用新的供應商 ID，如使用 API 設定自動重新載入預付帳戶餘額的說明。

後續步驟

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