前払い残高を管理する

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. Edge で Worldpay 決済機関を設定する際に使用するパスワードを [XML Password]（XML パスワード）フィールドに設定します。
   3. [リダイレクト MAC シークレット] フィールドに 20 ～ 30 文字の MAC シークレット キーを入力します。
   4. [Save Profile] をクリックします。
4. Apigee Edge 管理サーバーを販売者の IP リスト（許可リスト）に追加します。
   1. [Profile] > [Merchant Environment] をクリックします。
   2. [New Test IP] をクリックします。
   3. Apigee Edge Management Server の IP を入力します。
   4. [保存] をクリックします。
5. メソッド認証コード（MAC）などの Worldpay パラメータを追加するように、販売者の URL を構成します。
   1. [Installations] > [Hosted Payment Pages] > [Payment Page Designer] をクリックします。
   2. [Edit Payment Pages] で、[Select channel] プルダウン リストからインストール ID を選択します。
   3. [プロパティ] タブで、[販売者の設定を編集] を選択します。
   4. [URL パラメータを送信] の値を [True] に設定します。
   5. [公開] タブをクリックします。
   6. 次のように変更を昇格します。
      • テスト環境の場合は、[デザイン] の [昇格] をクリックして、デザインからサンドボックスに昇格します。
      • 本番環境の場合は、[Sandbox] の [Promote] をクリックして、サンドボックスから本番環境にプロモートします。

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 つの販売者アカウント（1 つはテスト用、もう 1 つは本番環境用）を示すレスポンスの例を示します。

{
  "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 モジュールを有効にします。詳細については、デベロッパー ポータルで Monetization を構成するをご覧ください。

決済機関を使用してプリペイド アカウントへの支払いを開始する

前払いアカウント管理フローのステップ 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 の安全な支払いページの URL が referenceUrl で返されます。この URL には、一意の注文キーがクエリ パラメータとして追加されています。

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 を使用するように自動チャージを再構成する必要があります。

次のステップ

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