管理预付费账号余额

您正在查看的是 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 Secret 生成消息身份验证代码 (MAC)。
12 Worldpay 会将 API 使用方的浏览器重定向至成功的回调网址(来自第 8 步),将 MAC 作为查询参数附加 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. 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. Edit Payment Pages(修改付款页面)下,从 Select channel(选择渠道)下拉列表中选择您的安装 ID。
    3. 在“属性”标签页上,选择修改商家配置
    4. 将“发送网址参数”值设置为 True
    5. 点击 Publish(发布)标签页。
    6. 宣传变更,具体说明如下:
      • 对于测试环境,点击 Design 下的 Upgrade,即可从 Design 提升到 Sandbox。
      • 对于生产环境,请点击沙盒下的升级,从沙盒升级到生产环境。

在 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 

查看第三方付款服务机构

查看并确认为您的 Edge 组织配置的第三方付款服务机构,方法是向以下资源发出 GET 请求:

/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"
  } ]
}

在开发者门户中启用和配置 Monetization 和 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"
}

系统会以 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 重新加载预付款帐号余额时,必须指定以下属性:

名称 说明 默认 是否必需?
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

手动管理预付款账号余额

或者,您也可以手动或通过集成结算系统跟踪付款,然后调用 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 自动重新加载预付款账号余额时,可以指定以下属性。

名称 说明 默认 是否必需?
providerId

付款服务机构的 ID。

不适用
chargePerUsage false
isRecurring

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

不适用
replenishAmount

预付款账号余额必须降至以下的最低值才能触发自动充值。

不适用
recurringAmount

触发自动充值后,充值帐号余额的金额。

不适用

迁移到 WorldPay 的托管付款页面

WorldPay 更新了其安全付款处理流程,以使用一组新的页面,即“托管的付款页面”。

如果您在 2017 年 8 月之前(在 2017 年 8 月之前)配置了 WorldPay 付款服务机构,则需要在 2018 年 1 月之前迁移到 WorldPay 的全新托管付款页面。

要迁移至 WorldPay 的托管付款页面,请执行以下操作:

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

后续步骤

您可以为各个后付费开发者设置信用额度。请参阅管理后付费余额,了解如何操作。