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

Cash FOP（AKA Reference Number API）ガイド

ここでは、考慮すべき重要なユースケースと、現金のお支払い方法を実装するために必要なガイドラインと API について説明します。

ユースケース

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

現金 - ユーザーは実店舗で現金で支払います。
VAN - ユーザーはバーチャルアカウント番号に送金します。

現金

ユーザーは、コンビニエンスストアなどの実店舗で現金で Google から商品を購入できます。その取引を特定するため、ユーザーは参照番号を生成し、店舗で支払うことができます。また、購入を完了する方法に関する手順もユーザーに表示されます。Google が商品を配送できるように、ユーザーが購入を完了次第、インテグレータが Google に通知するのが理想的です。

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

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

VAN

ユーザーは銀行口座で商品の代金を支払うことができます。Google はインテグレータにバーチャルアカウント番号を要求し、番号と手順をユーザーに提示します。ユーザーはこの番号をコピーし、銀行のアプリケーションに送金する金額と合わせて入力します。

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

Google が ReferenceNumberPaidNotificationを受け取ると、Google はプロダクトを提供し、インテグレータがトランザクションを取り消すことはできません。

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

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

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

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

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

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

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

べき等動作に従う

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

メリット

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

べき等性の実装方法

Google が再試行を送信すると、リクエスト ID は同じになり、内容も同じになりますが、タイムスタンプは異なります。以前送信したものと同じ回答で回答します。最初のレスポンスが 200（成功）の場合、Google は異なるタイムスタンプで同じレスポンスを受け取ることを想定しています。

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

詳しくは、詳細なガイドをご覧ください。

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

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

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

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

インテグレータは、サービスを提供する国に応じて異なるアカウントを持つ場合もあります。その原因としては、さまざまな税法や国ごとに異なる違いがあることが考えられます。この場合、国ごとに別の 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"
}

送金を実装する

ご利用のお支払い方法に API を統合したら、送金できます。送金はどのお支払い方法でも同じように行われます。

`remittanceStatementNotification`

取引の 2 日後に、Google はその日に記録した取引の概要を含む 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 を複数回呼び出す必要があります。リクエストは順番に行う必要はなく、並列化できます。

Request 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）

Request URL

リクエスト本文の例

acceptRemittanceStatement、acceptRemittanceStatementWithModifications

acceptRemittanceStatement のリクエスト URL

リクエスト本文の例

レスポンスの例

acceptRemittanceStatementWithModifications のリクエスト URL

リクエスト本文の例

レスポンスの例

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

`referenceNumberPaidNotification`

`remittanceStatementNotification`

調整（`remittanceStatementDetails`）

`acceptRemittanceStatement`、`acceptRemittanceStatementWithModifications`

`acceptRemittanceStatement` のリクエスト URL

`acceptRemittanceStatementWithModifications` のリクエスト URL