前払い残高を管理する

現在、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 に設定した場合、1 ページあたりで返される 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
}

会社の前払い残高の確認

会社の前払い口座残高を表示するには、GET リクエストを /mint/organizations/{org_name}/companies/{company_id}/developer-balances に送信します。ここで、{company_id} は会社の ID です。会社が前払いの場合、リクエストは現在の前払い済みアカウント残高を取得します。その会社が後払いの場合、リクエストは現在の利用限度額を取得します。

次のクエリ パラメータを渡して、結果をフィルタリングできます。

クエリ パラメータ 説明
all すべての API パッケージを返すかどうかを指定するフラグ。false に設定した場合、1 ページあたりで返される 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 デベロッパー ポータルは、プロバイダ ID、再読み込み金額、通貨を使って、Edge を介してデベロッパーへの支払いを開始します。API を使用して支払いを開始する方法については、決済機関を使用してプリペイド口座への支払いを開始するをご覧ください。
3 ID でプロバイダを検出し、Worldpay アカウントであると判断する。
4 Edge がオーダー コードを生成します。
5 Edge は、Worldpay で支払い注文を作成します。
6 Worldpay は、注文の参照 ID と、注文を処理するための期間限定の URL を返します。
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 デベロッパー ポータルは、クエリ パラメータとしてコールバック URL(成功、失敗など)を URL に追加します。
9 デベロッパー ポータルは、ステップ 1 のリクエストに応答して、API コンシューマのブラウザを変更された URL にリダイレクトします。
10 API コンシューマが申請フォームに記入し、Worldpay で処理を開始します。
11 Worldpay でお支払い情報を取得し、支払い処理を行います。成功すると、Worldpay は、Worldpay とデベロッパー ポータルで構成された MAC Secret を使用して、メッセージ認証コード(MAC)を生成します。
12 Worldpay は、API コンシューマのブラウザを、ステップ 8 で呼び出された正常なコールバック URL にリダイレクトし、クエリ パラメータとして MAC アドレスと金額を追加します。
13 ブラウザが、リクエストされた金額と MAC を使ってデベロッパー ポータルの URL を呼び出します。
14 ポータルが MAC を MAC シークレットと照合して検証します。MAC は、支払いが正常に完了したとユーザーが勝手に主張するのを防止します。
15 デベロッパー ポータルは、前払い残高を再読み込みするリクエストを Edge に送信します。API を使用してアカウント残高を再読み込みする方法については、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. [リダイレクト MAC シークレット] フィールドに 20 ~ 30 文字の MAC 秘密鍵を入力します。
    4. [Save Profile] をクリックします。
  4. Apigee Edge 管理サーバーを販売者 IP のリスト(許可リスト)に追加します。
    1. [プロフィール] > [販売者の環境] をクリックします。
    2. [新しいテスト IP] をクリックします。
    3. Apigee Edge 管理サーバーの IP を入力します。
    4. [保存] をクリックします。
  5. メソッド認証コード(MAC)などの Worldpay パラメータを追加する販売者の URL を構成します。
    1. [Installations] > [Hosted Payment Pages] > [Payment Page Designer] をクリックします。
    2. [お支払いページを編集] の [チャンネルを選択] プルダウン リストからインストール ID を選択します。
    3. [プロパティ] タブで [販売者の設定を編集] を選択します。
    4. [URL パラメータを送信する] の値を True に設定します。
    5. [公開] タブをクリックします。
    6. 変更を次のようにプロモートします。
      • テスト環境では、[Design] の下の [Promote] をクリックして、デザインからサンドボックスにプロモートします。
      • 本番環境では、[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 

第三者の決済機関の表示

次のリソースに 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 モジュールの有効化と構成

デベロッパー ポータルで、必要な 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"
}

Worldpay の安全なお支払いページの 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 を使用して前払い残高を再読み込みする場合は、次のプロパティを指定する必要があります。

名前 説明 デフォルト 必須 / 任意
amount

前払い残高に適用される金額(該当通貨)。

なし
supportedCurrency

前払い残高に使用する通貨。これは、デベロッパーが購入した 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

前払い残高の手動管理

別の方法として、手動または統合課金システムを使用して支払いを追跡し、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 月より前に)を使用して WorldPay の決済機関を設定している場合は、2018 年 1 月までに WorldPay の新しい Hosted Payment ページに移行する必要があります。

WorldPay のホスト型決済ページに移行するには:

  1. WorldPay に連絡して、現在のアカウントを移行して新しい「ホスト型決済ページ」を使用できるようにし、アカウントの新しいインストール ID を取得してください。
  2. Edge での決済プロバイダの構成の説明に沿って、新しい WorldPay 決済プロバイダを構成します。authType フィールドにインストール ID を渡します。
  3. デベロッパー ポータルで収益化を構成するの説明に従って、デベロッパー ポータルで新しい決済機関を構成します。
  4. 決済機関を使用して前払いアカウントの自動再読み込みを設定している場合は、API を使用した前払い口座残高の自動再読み込みの設定で説明されているように、新しいプロバイダ ID を使用するように自動再読み込みを再構成する必要があります。

次のステップ

後払い式デベロッパーごとに利用限度額を設定できます。詳しくは、後払い残高を管理するをご覧ください。