管理預付帳戶餘額

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。info

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

• 查看目前的預付帳戶餘額。請參閱「使用 API 查看預付帳戶餘額」。
• 使用 Worldpay 等第三方付款服務供應商，視需要為帳戶餘額重新儲值 (加值)。請參閱「使用第三方付款供應商管理預付款餘額」。

  或者，您也可以透過手動追蹤付款或整合的結帳系統來管理重新加值作業，然後呼叫 Monetization API 來重新加值帳戶，如「手動管理預付餘額」一文所述。

• 使用 Monetization API 和第三方付款服務供應商 (例如 Worldpay)，在預付帳戶餘額低於特定門檻時設定自動儲值功能。這個選項可用於管理費率方案的週期性付款。如需相關資訊，請參閱「使用 API 設定預付帳戶餘額的自動重載」。

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

如同下文所述，為開發人員或公司查看預付帳戶餘額時，您需要從回覆中取得下列值：

• amount：目前帳單週期的可用金額。使用本節所述的方法重新加值預付帳戶時，這個值就會更新。
• usage：目前帳單週期內的使用費用總額。每筆符合資格的營利交易或發出功勞 (正或負) 時，這個值就會更新。

您可以將 usage 值減去 amount 值，計算目前帳單週期內剩餘的預付帳戶餘額。舉例來說，如果 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. 在「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」True。
   5. 按一下「發布」分頁標籤。
   6. 提交變更，如下所示：
      • 如果是測試環境，請按一下「Design」下方的「Promote」，從設計改為沙箱。
      • 如為正式環境，請按一下「Sandbox」下方的「Promote」，將應用程式從沙箱推送至正式環境。

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

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

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

/organizations/{org-name}/providers

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

/config/providers

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

舉例來說，以下會設定名為 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 模組

在開發人員入口網站啟用必要的「營利」和「世界付款」模組。詳情請參閱「在開發人員中心設定營利功能」。

透過付款服務供應商辦理付款給預付帳戶

如預付帳戶管理流程的步驟 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 安全付款頁面的網址，並附上專屬訂單鍵做為查詢參數。

使用 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

手動管理預付帳戶餘額

或者，您也可以透過手動追蹤付款或整合結帳系統，然後呼叫 Monetization 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 自動重新加載預付帳戶餘額時，可以指定下列屬性。

遷移至 WorldPay 代管的付款頁面

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

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

如要改用 WorldPay 代管的付款頁面，請按照下列步驟操作：

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

後續步驟

你可以為個別後付開發人員設定信用額度。瞭解如何管理後付餘額。