このページは Cloud Translation API によって翻訳されました。

Cash FOP（AKA Reference Number API）ガイド

ここでは、考慮すべき重要なユースケースと、現金 FOP の実装に必要なガイドラインと API について説明します。

ユースケース

参照番号 API にはさまざまな用途があります。このガイドでは、2 つのユースケースとその実装について説明します。

現金 - 物理的な場所で現金で支払います。
VAN - バーチャルアカウント番号に送金します。

現金

ユーザーは Google から商品を購入し、コンビニエンスストアなどの実店舗で現金で支払うことができます。取引を識別するために、ユーザーは参照番号を生成して店舗に持ち込んで支払います。さらに、Google は購入を完了する手順をユーザーに表示します。ユーザーが購入を完了したらすぐに、インテグレーターが Google に通知して、Google が商品を配送できるようにすることが理想的です。

Google の担当者が、一般的なお支払い手順のサンプルを尋ねます。Google の担当者と連携してメッセージを最適化、調整します。

Google が提供したいと考えているユーザーエクスペリエンスは、顧客が注文した商品が店舗を出るときに配送することです。Google は、お客様が参照番号を支払ってから 3 分以内に ReferenceNumberPaidNotification が Google に届くことを想定しています。ReferenceNumberPaidNotification が送信された後、インテグレータでトランザクションを取り消すことはできません。

VAN

ユーザーは自分の銀行口座で商品の代金を支払うことができます。Google はインテグレータにバーチャルアカウント番号の提供を依頼し、その番号と手順をお客様に提示します。お客様はその番号をコピーし、バンキングアプリケーションにその番号と振り込み額を入力します。

インテグレータは、送金した金額が referenceNumberGeneration リクエストの金額と一致することを確認し、参照番号が支払われたことを Google に通知する必要があります。

Google が ReferenceNumberPaidNotification を受信すると、商品は配信され、インテグレータが取引を取り消すことはできません。

お客様のサーバーと Google のサーバー間でメッセージを送信する

お客様のサーバーと Google のサーバー間でメッセージを送信する場合、またはその逆を行う場合は、以下のガイドラインに沿って行ってください。

受信したリクエスト - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

レスポンスの送信 - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google のリクエスト - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google の回答 - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

こちらは、リクエストとレスポンスの処理を示す PGP ライブラリと Java のサンプルです。

べき等動作に従う

べき等性とは、すでに正常に処理されたリクエスト（支払いなど）の再処理を試行してはならないことを意味します。代わりに、成功した処理のレスポンスを返す必要があります。

ポイント

Google は、Google 側の状態がベンダー側の状態と同じであることを確認するために、一部のリクエストを再試行する場合があります。システムでは、これが別の取引であると認識されるべきではありません。したがって、べき等性は非常に重要です。つまり、インテグレータはすでに正常に処理されたデータを再処理すべきではありません。このような場合は、代わりに前のレスポンスを送信する必要があります。

べき等性の実装方法

Google が再試行を送信する場合、リクエスト ID は同じになり、内容は同じになりますが、タイムスタンプは異なります。先ほど送信したのと同じ回答を返します。最初のレスポンスが 200（成功）の場合、同じレスポンスにタイムスタンプが異なるものがあると想定されます。

以前のレスポンスがエラー（400 や 500 など）だった場合は、そのリクエストを新しいリクエストとして処理し、再度確認する必要があります。これは、最初にサーバーがダウンして再試行すると、リクエストが正常に処理される機会を再度与える場合に便利です。

詳しくは、こちらの詳細ガイドをご覧ください。

決済インテグレータのアカウント ID（PIAID）を使用する

Google との統合では、Google のさまざまな事業体との統合が必要になる場合があります。たとえば、Google Play、YouTube、Google 広告などの事業体があります。これらの各構成には、それぞれ異なる販売アカウントが関与します。

Google 内の各エンティティから各販売アカウントにマッピングするために、Google は決済インテグレータのアカウント ID（PIAID）を提供します。Cash FOP API の例については、generateReferenceNumber をご覧ください。以下は、このマッピングを使用するサンプルです。

Google 内の各エンティティから各販売アカウントにマッピングするために、Google は決済インテグレータのアカウント ID（PIAID）を提供します。Cash FOP API の使用例については、generateReferenceNumber をご覧ください。以下は、このマッピングを使用するサンプルです。


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

ハイライト表示されている部分に注目してください。ここで必要な 2 つの値は、Google の担当者から提供される paymentIntegratorAccountId と、販売アカウントの 2 つです。

インテグレータは、サービスを提供する国ごとに異なるアカウントを持っている場合もあります。その原因としては、税法の違いなど、国ごとの違いが考えられます。この場合、国ごとに別の PIAID が生成される場合があります。

統合する API

以下の API は、参照番号の生成と支払い通知を処理します。

送金と決済を処理する API は次のとおりです。

RemittanceStatementNotification
RemittanceStatementDetails
変更した AcceptRemittanceStatement/AcceptRemittanceStatement

照会番号を生成して Google と決済するには、上記の API をすべて統合する必要があります。

参照番号を生成

購入を開始すると、Google が GenerateReferenceNumber を呼び出します。お客様には、該当の取引またはアカウントを特定できる参照番号をお知らせいただく必要があります。予想されるレイテンシは <3 秒。

現金による取引の場合、参照番号は最大 12 文字です。

URL: POST https://[your basepath]/v1/generateReferenceNumber

リクエスト JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
    "requestTimestamp": "1561678470395"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "transactionDescription": "Google Play - Tester",
  "currencyCode": "USD",
  "amount": "10000000"
}

レスポンス JSON

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

サンプル Java

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

参照番号をキャンセル

Google は、照会番号をキャンセルして、お客様にお支払いが行われないようにすることがあります。ユースケースの一例として、期限切れのプロモーションがあります。このリクエストに成功の返信を送ったら、参照番号で支払いができないことを確認する必要があります。

ユーザーが支払いプロセス（POS の照会番号の検索など）をすでに開始している場合、サーバーはリクエスト本文で HTTP 423 レスポンスと ErrorResponse を返し、ステータスは USER_ACTION_IN_PROGRESS にする必要があります。

URL: POST https://[your basepath]/v1/cancelReferenceNumber

リクエスト JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "51e00f16-36ba-4490-b228-0a670d202206",
    "requestTimestamp": "1561678947926"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

レスポンス JSON

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

`referenceNumberPaidNotification`

支払いが承認されて取引が完了したら、サービスを通じて、取引が完了したことを Google に通知し、ユーザーに商品を届ける必要があります。Google は、この通知を受け取った時点で取引が確定し、予約できないことを想定しています。

referenceNumberPaidNotification エンドポイント URL:


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

リクエスト JSON

{
 "requestHeader": {
    "requestTimestamp": "1561748625577",
    "requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    }
  },
  "paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
  "referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
  "paymentLocation": {
    "brandName": "TestMart",
    "locationId": "1234"
  },
   "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "paymentTimestamp": "1561748625577"
}

レスポンス JSON

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

送金を実行する

特定の FOP の API を統合したら、送金の準備が整います。送金はすべての FOP で同じです。

`remittanceStatementNotification`

取引から 2 日後に、その日に記録された取引の概要を含む remittanceStatementNotification が送信されます。取引から 2 日後の通知の例を次に示します。

POST https://www.integratordomain.com/v1/remittanceStatementNotification

リクエスト JSON


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-statement-abc",
    "requestTimestamp": "1502632800000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "remittanceStatementSummary": {
    "statementDate": "1502607600000",
    "billingPeriod": {
      "startDate": "1502434800000",
      "endDate": "1502521199000",
    },
    "dateDue": "1503212400000",
    "currencyCode": "INR",
    "totalDueByIntegrator": "1076000000",
  }
}

totalDueByIntegrator のマッピングに注目してください。この行には、インテグレータが支払うべき正味額（マイクロ）が表示されます。また、このメッセージには日付と通貨の種類が表示されます。請求対象期間は、取引の最も早い日付と最も遅い日付の 00:00:00.000 と 23:59:59.999 をそれぞれ表しています。

調整（`remittanceStatementDetails`）

調整のため、インテグレータは remittanceStatementDetails を呼び出して、remittanceStatementNotification に含まれるイベントのリストを取得します。

Google は remittanceStatementDetails リクエストに対して、ページ分けされたイベントのリストを返します。合計トランザクション数が 1,000 を超える場合は、remittanceStatementDetails を複数回呼び出す必要があります。リクエストは順番に行う必要はなく、並列化できます。

リクエスト URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

リクエストの本文の例

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

次に、2 つのキャプチャイベント（トランザクション）を説明する、大きなレスポンスの短いスニペットを示します。

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

詳しくは、remittanceStatementDetails をご覧ください。

`acceptRemittanceStatement`、`acceptRemittanceStatementWithModifications`

インテグレータは、これらのイベントを、自身が記録したイベントと比較する必要があります。取引が一致しない、または取引がない場合は、Google にお問い合わせのうえ、詳しく調査してください。すべての取引が一致し、手続き手数料に税金が含まれていない場合は、acceptRemittanceStatement を呼び出します。税金が含まれている場合は、acceptRemittanceStatementWithModifications を呼び出します。

acceptRemittanceStatement メソッドは、手数料に税金が適用されない場合に使用します。

税金を含める場合は、acceptRemittanceStatementWithModifications を呼び出して税率を定義します。税率が変更された場合は、必ず更新してください。acceptRemittanceStatement が正常に完了したら、Google アカウントへの銀行振込を開始します。

`acceptRemittanceStatement` のリクエスト URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

リクエストの本文の例

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

レスポンスの例

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

`acceptRemittanceStatementWithModifications` のリクエスト URL

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

リクエストの本文の例

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

レスポンスの例

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}

Cash FOP（AKA Reference Number API）ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ユースケース

現金

VAN

お客様のサーバーと Google のサーバー間でメッセージを送信する

べき等動作に従う

ポイント

べき等性の実装方法

決済インテグレータのアカウント ID（PIAID）を使用する

統合する API

参照番号を生成

リクエスト JSON

レスポンス JSON

サンプル Java

参照番号をキャンセル

リクエスト JSON

レスポンス JSON

referenceNumberPaidNotification

リクエスト JSON

レスポンス JSON

送金を実行する

remittanceStatementNotification

リクエスト JSON

調整（remittanceStatementDetails）

リクエスト URL

リクエストの本文の例

acceptRemittanceStatement、acceptRemittanceStatementWithModifications

acceptRemittanceStatement のリクエスト URL

リクエストの本文の例

レスポンスの例

acceptRemittanceStatementWithModifications のリクエスト URL

リクエストの本文の例

レスポンスの例

Cash FOP（AKA Reference Number API）ガイド

`referenceNumberPaidNotification`

`remittanceStatementNotification`

調整（`remittanceStatementDetails`）

`acceptRemittanceStatement`、`acceptRemittanceStatementWithModifications`

`acceptRemittanceStatement` のリクエスト URL

`acceptRemittanceStatementWithModifications` のリクエスト URL