管理预付费账号余额

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

如需管理预付费账号中的余额，您可以执行以下操作：

• 查看当前的预付费账号余额。请参阅使用 API 查看预付费账号余额。
• 根据需要通过第三方付款服务机构（如 Worldpay）重新加载账号余额（充值）。请参阅使用第三方付款服务提供商管理预付费余额。

  或者，您也可以通过手动或集成的结算系统跟踪付款，然后调用 Monetize API 来为账号重新加载，如手动管理预付费余额中所述。

• 使用变现 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. 在重定向 MAC 密钥字段中输入一个长度为 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. 点击 Publish（发布）标签页。
   6. 宣传更改，具体如下：
      • 对于测试环境，请点击设计下的提升，将资源从“设计”提升到“沙盒”。
      • 对于生产环境，请点击沙盒下的升级，从沙盒升级到生产环境。

在 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 模块

在开发者门户中启用所需的变现和 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} 是开发者的电子邮件地址。发出请求时，您需要在请求正文中指定要添加到余额中的金额和所使用的币种。

例如，以下请求会向开发者的预付费账号余额中添加 1, 000 美元：

$ 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。发出请求时，您需要在请求正文中指定要添加到余额中的金额和所使用的币种。

例如，以下请求会向公司预付款账号余额中添加 1, 000 美元：

$ 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 重新加载预付费账号余额时，必须指定以下属性：

删除第三方付款服务机构

如需删除为 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 重新加载预付款账号余额中的说明，手动或通过集成结算系统跟踪付款，然后调用 monetization 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. 配置新的 WorldPay 付款服务提供商，如在 Edge 中配置付款服务提供商中所述，并在 authType 字段中传递安装 ID。
3. 在您的开发者门户中配置新的付款服务提供商，如在开发者门户中配置创收功能中所述。
4. 如果您使用付款服务提供商设置了预付费账号的自动充值，则需要重新配置自动充值，以使用新的提供商 ID，如使用 API 设置预付费账号余额的自动充值中所述。

后续步骤

您可以为各个后付费开发者设置信用额度。有关详情，请参阅管理后付费余额。