前払い残高を管理する

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントに移動。 情報

前払いアカウントの残高を管理するには、次の方法があります。

• 現在の前払いアカウント残高を確認します。API を使用した前払いアカウント残高の表示をご覧ください。
• 必要に応じて、サードパーティの決済機関（Worldpay など）を使用してアカウント残高を再読み込み（入金）します。第三者の決済機関を使用したプリペイド残高の管理をご覧ください。

  または、プリペイド残高を手動で管理するで説明されているように、支払いを手動で追跡するか、統合された課金システムを使用して追跡し、収益化 API を呼び出してアカウントを再読み込みすることで、チャージを管理することもできます。

• Monetization 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）に連絡して販売アカウントを設定する必要があります。テスト用と本番環境用の 2 つのアカウントを設定することをおすすめします。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 Password] フィールドに、Edge で Worldpay 決済機関を構成するときに使用するパスワードを設定します。
   3. [Redirect MAC secret] フィールドに、20 ～ 30 文字の MAC 秘密鍵を入力します。
   4. [Save Profile] をクリックします。
4. Apigee Edge Management Server を販売者の IP アドレスのリスト（許可リスト）に追加します。
   1. [プロフィール] > [販売者の環境] をクリックします。
   2. [New Test IP] をクリックします。
   3. Apigee Edge Management Server の IP を入力します。
   4. [保存] をクリックします。
5. メソッド認証コード（MAC）などの Worldpay パラメータを追加するように販売者の URL を設定します。
   1. [インストール] > [ホスト型支払いページ] > [支払いページ デザイナー] をクリックします。
   2. [お支払いページを編集] で、[チャンネルを選択] プルダウン リストからインストール ID を選択します。
   3. [プロパティ] タブで、[販売者の設定を編集] を選択します。
   4. Send URL パラメータの値を [True] に設定します。
   5. [公開] タブをクリックします。
   6. 次のように変更を昇格させます。
      • テスト環境の場合は、[設計] の [昇格] をクリックして、設計からサンドボックスに昇格します。
      • 本番環境の場合は、[サンドボックス] で [昇格] をクリックして、サンドボックスから本番環境に昇格します。

Edge で支払いプロバイダを構成する

次のステップは、Edge で決済プロバイダを構成することです。

特定の組織用に決済機関を構成するには、次の API を使用します。

/organizations/{org-name}/providers

システム管理者権限を持つ Apigee Edge Private Cloud のお客様のみは、必要に応じて次の API を使用してグローバル決済プロバイダを構成できます。

/config/providers

各 API を呼び出すときに、リクエスト本文に次の情報を指定する必要があります。

たとえば、次のコマンドは、Worldpay の販売者アカウント（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

次に、テスト用と本番環境用の 2 つの販売者アカウントを示すレスポンスの例を示します。

{
  "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 モジュールを有効にして構成する

デベロッパー ポータルで、必要な収益化モジュールと 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 の [Secure Payment] ページの URL が 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 を使用して前払いアカウントの残高を再チャージする場合は、次のプロパティを指定する必要があります。

第三者の決済機関を削除する

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 を使用して前払いアカウント残高をチャージするで説明されているように、手動または統合された課金システムで支払いを追跡し、収益化 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. 支払いプロバイダを使用してプリペイド アカウントの自動チャージを設定している場合は、API を使用してプリペイド アカウント残高の自動チャージを設定するで説明されているように、新しいプロバイダ ID を使用するように自動チャージを再構成する必要があります。

次のステップ

後払いデベロッパーごとにクレジット上限を設定できます。詳しくは、後払い残高を管理するをご覧ください。