管理预付费账号余额

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

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

如何计算预付款账号的剩余账号余额？

如以下部分所述，当您查看开发者或公司的预付费账号余额时，需要从响应中获取以下值：

  • 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.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. 在 Edge 中配置 Worldpay 支付服务机构时，请在 XML 密码字段中设置要使用的密码。
    3. 在 Redirect MAC secret（重定向 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. 点击发布标签页。
    6. 按如下方式推广更改：
      • 对于测试环境，请点击设计下的提升，以从“设计”提升到“沙盒”。
      • 对于生产环境，请点击沙盒下的提升，以从沙盒提升到生产环境。

在 Edge 中配置支付服务机构

下一步是在 Edge 中配置支付服务提供商。

您可以使用以下 API 为特定组织配置支付服务机构：

/organizations/{org-name}/providers

只有具有系统管理员权限的 Apigee Edge 私有云客户才能选择使用以下 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 test 或 WorldPay 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”模块

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

例如，以下请求会将开发者的预付款账号余额增加 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 重新加载预付费账号余额时，必须指定以下属性：

名称 说明 默认值 是否必需？
amount

已应用于预付款余额的金额（以适用币种表示）。

 不适用 是
supportedCurrency

预付款余额所用的币种。这是开发者购买的 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 为预付费账号余额充值中所述。

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

 不适用 是
chargePerUsage false 否
isRecurring

用于指定是否启用自动重新加载的标志 (true)。如需停用自动重新加载，请将此标志设置为 false。

 不适用 是
replenishAmount

预付款账号余额必须低于此阈值，才能触发自动充值。

 不适用 是
recurringAmount

触发自动充值时要添加到预付款账号余额中的金额。

 不适用 是

迁移到 WorldPay 的托管付款页面

WorldPay 已更新其安全付款处理流程，以使用一组新页面，称为“托管付款页面”。

如果您在 2017 年 8 月之前使用已弃用的安全付款处理流程配置了 WorldPay 付款服务提供商，则需要在 2018 年 1 月之前迁移到 WorldPay 的新托管付款页面。

如需改用 WorldPay 的托管付款页面，请执行以下操作：

  1. 请与 WorldPay 联系，将您当前的账号迁移为使用新的托管付款页面，并为您的账号获取新的安装 ID。
  2. 按照在 Edge 中配置支付服务机构中的说明配置新的 WorldPay 支付服务机构，并在 authType 字段中传递安装 ID。
  3. 按照在开发者门户中配置创收功能中的说明，在开发者门户中配置新的付款服务提供商。
  4. 如果您使用支付服务机构设置了预付款账号的自动充值，则需要重新配置自动充值，以使用新的提供方 ID，如使用 API 设置预付款账号余额的自动充值中所述。

后续步骤

您可以为各个后付费开发者设置信用限额。如需了解具体操作方法，请参阅管理后付费余额。