GMO あおぞらネット銀行オープン API 仕様書イベント通知編 Version: Last Modified: /2/8 GMO Aozora Net Bank, Ltd. All Rights Reserved. 出力日 :2020/2/10

Size: px

Start display at page:

ありみちいなくら
3 years ago
Views:

1 GMO あおぞらネット銀行オープン API 仕様書イベント通知編 Version: Last Modified: /2/8 出力日 :2020/2/0

2 変更履歴版数内容区分更新日.2.0 更新系 APIおよび通知系 API 一般提供変更 209/0/28.2. 他資料の修正に伴いバージョンアップ ( 当仕様書に更新なし ) 変更 209/06/20..0 内部機能改修に伴う変更 ( インターフェース変更なし ) 変更 209/08/0.4.0 Visa デビット取引明細照会 API 一般提供変更 2020/02/08 出力日 :2020/2/0

3 共通仕様 HTTPリクエストヘッダ項目プロトコル charset contenttype 仕様 HTTP./HTTPS UTF8 application/json domain_name 本番環境開発環境 api.gmoaozora.com stgapi.gmoaozora.com メインURL 例 verの場合リクエスト共通仕様項目 NULLデータの扱い仕様項目がセットされていて空または項目ごと設定されていない場合どちらもNULLとして扱いますレスポンス共通仕様項目仕様レスポンスデータの場合レスポンスデータの値が空の場合またはレスポンスデータ自体が設定されない場合は項目自体を設定しないと記載 NULLデータの扱い配列の場合項目はセットするが空の状態の場合空のリストと記載項目自体を設定しない場合は項目自体を設定しないと記載異常時の共通エラーレスポンスエラーコードエラーメッセージ errorcode errormessage 必須型 0 半角英数文字 255 全出力日:2020/2/0

4 共通仕様通知配信制御通知配信制御はイベント種別単位で通知の開始/停止をコントロールしますそのため通知の開始/停止を行うイベント種別を必ず指定する必要があります配信状態におけるリクエスト受付可否各配信状態における処理リクエストの受付可否は以下の通りとなります受付可能受付可能だが何も起こらない受付不可配信状態配信開始状態配信中配信停止状態未配信リクエスト受付可否配信リクエスト配信停止リクエスト未送信明細取得リクエストセキュリティ対策 Webhookをセキュアにするためインターフェース仕様に以下の機能をサポートしますオプションとなっている機能はあらかじめ配信先システムにて使用有無を指定することが可能ですアクセストークン Webhookのリクエストヘッダに通知対象ユーザーに発行されたアクセストークンを設定配信先システムにてWebhook受信時にアクセストークンの一致を検証シグネチャオプション銀行側システムにて配信先システム用に発行したクライアントシークレットをキーとしてWebhookのボディ部をHMACSHA256でハッシュ化し Base64エンコードをかけた値をリクエストヘッダに設定 Webhook受信時に配信先システムにて同様にボディ部をハッシュ化しリクエストヘッダのxwebhooksignatureパラメーターとの一致を検証サンプルクライアントシークレットをキーとしてHMACSHA256によりボディ部のダイジェスト値を取得し xwebhooksignatureの値との一致を検証 echo n '{ボディ部}' openssl dgst binary sha256 hmac {クライアントシークレット} base64 Basic認証オプション配信先システム側がBasic認証に対応している場合 WebhookのリクエストヘッダのAuthorizationに指定されたクレデンシャル情報を設定配信先システムにてWebhook受信時に認証を実施制限事項その他イベント通知に関する制限事項として以下をご確認ください通知するメッセージは非同期に処理されるため順序性は保証されません銀行側システムのメンテナンス時は配信が停止しますメンテナンス終了後に配信が自動的に再開されメンテナンス期間中のメッセージも配信されますアクセストークンの有効期限が切れた場合メッセージの通知も終了しますアクセストークンの更新後または再発行後にメッセージの通知は再開されますがアクセストークンの期限が切れていた間のメッセージは再送されませんのでアクセストークンは期限が切れないよう管理してください期限が切れていた間の明細は振込入金口座入金明細照会API 別仕様書に定義により取得することが可能です通知のリトライは最初のメッセージ通知から指数関数的に間隔を広げながら最大１時間まで行われます最初の通知から１時間以上継続してリトライがエラーとなった場合は自動的に配信が停止状態に移行します配信先システム側のメンテナンスが１時間以上となる場合などは配信が停止しているためメンテナンス終了後に再度配信開始を要求していただく必要があります配信エラーなどの理由により配信が停止したまま４日間を経過したメッセージは削除されます削除されたメッセージは再送することができません削除された過去の明細を確認する必要がある場合は振込入金口座入金明細照会APIにより停止期間中の振込入金明細を取得してください配信停止リクエストにより完全に配信が停止するまでには最大１０分程度タイムラグが発生することがありますトラフィック状況等により通知の正常応答が確認できなかった場合は同一のメッセージが重複して配信される場合があります予期せぬシステム障害によりメッセージがロストされた場合は障害復旧後に振込入金口座入金明細照会APIにより障害発生期間中の振込入金明細を取得し未受信の明細を確認してください 2 出力日:2020/2/0

5 エンドポイント一覧 Request カテゴリイベント通知制御 Webhook カテゴリイベント通知 API種別参照系 API種別参照系スコープ通知を受けるイベント種別に依存 API 通知配信制御概要指定したイベント通知 Webhook の配信開始配信停止をコントロールする電子決済等代行業者様向け個人事業主口座の場合 personal:virtualaccount 法人口座の場合 corp:virtualaccount その他の場合 private:virtualaccount 振込入金口座_未送信明細取得未送信となっている振込入金口座の入金明細を一括取得するスコープ電子決済等代行業者様向け個人事業主口座の場合 personal:virtualaccount 法人口座の場合 corp:virtualaccount その他の場合 private:virtualaccount API 振込入金口座_入金明細通知概要振込入金口座の振込入金明細通知の受信銀行システムから配信先システムへのPOSTリクエスト出力日:2020/2/0

6 ＡＰＩ通知配信制御概要指定したイベント種別に対応するイベント通知 Webhook の配信開始配信停止をコントロールします HTTPメソッド : URLリクエストパス POST /subscribe HTTPリクエストヘッダ認証情報 Authorization 銀行システムが配信先システムに発行したクライアントIDとクライアントシーレットを":" コロンで連結し Base64エンコードした値を設定 Basic CUEzYjhiRmg0QQycDFIcTo2WEpBMVZabTF NODdHeVdPeXBSM2JxUjRuYlZkdlR4bk9TbGJ oqk9vgpgvnhhuluwyw== HTTPリクエストボディ配信状態 subscribestatus イベント種別リスト eventtypes イベント種別 eventtype 0=配信停止要求 =配信開始要求 Array イベント種別のリスト 28 配信開始または配信停止するイベントの種別 vadeposittransaction=振込入金口座への入金明細通知 "" "vadeposittransaction" レスポンス情報 200 OK 以下エラー発生時のHTTPステータスとなりますレスポンスは共通仕様レスポンス共通仕様の異常時の共通エラーレスポンスをご参照ください 400 Bad Request 40 Unauthorized 40 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 4 Length Required 42 Precondition Failed 45 Unsupported media type 500 Internal Server Error 50 Service Unavailable 504 Gateway Timeout その他特記事項 4 出力日:2020/2/0

7 ＡＰＩ振込入金口座_未送信明細取得概要配信停止状態となっている場合本APIを利用することで未送信または送信エラーとなっている振込入金口座の入金明細を一括で取得することができます通常未送信または送信エラーとなっている明細は配信再開後に通知されますが本APIで取得された明細は配信済みとなるため配信再開後には通知されません未送信または送信エラーとなっている明細が無い場合は404 Not Foundを返却します法人口座および個人事業主口座のみ対象となり個人口座は対象外となります HTTPメソッド : URLリクエストパス GET /unsentlist/vadeposittransaction HTTPリクエストヘッダ認証情報 Authorization 銀行システムが配信先システムに発行したクライアントIDとクライアントシーレットを":" コロンで連結し Base64エンコードした値を設定 Basic CUEzYjhiRmg0QQycDFIcTo2WEpBMVZabTF NODdHeVdPeXBSM2JxUjRuYlZkdlR4bk9TbGJ oqk9vgpgvnhhuluwyw== レスポンス情報 200 OK メッセージ messages Array 半角英数字 9 9 メッセージを一意に識別するID ISO860 時差(offset)も表記 YYYYMMDDTHH:MM:SS+09:00形式入金口座情報入金先の口座を識別するID 2 29 " " メッセージID messageid イベント生成日時 timestamp 入金口座情報 account object 入金口座ID raid 入金口座支店コード rabranchcode 入金口座支店名カナ rabranchnamekana 5 入金口座口座番号 raaccountnumber 入金口座口座名義漢字 raholdername 48 基準日 basedate 0 0 基準時刻 basetime 4 4 振込入金口座入金明細 vatransaction object 振込入金口座ID vaid 0 0 応答日付もしくは入金明細の基準日を示す YYYYMMDD形式応答時刻もしくは入金明細の基準時刻を示す ISO860 時差(offset)も表記 HH:MM:SS+09:00形式振込入金口座入金明細情報振込入金口座を識別するID transactiondate 0 0 YYYYMMDD形式 "20809" 取引日 valuedate 0 0 YYYYMMDD形式 "20809" 起算日支店コード支店名カナ口座番号 vabranchcode vabranchnamekana vaaccountnumber 5 口座名義カナ vaaccountnamekana 40 入金金額振込依頼人名カナ仕向金融機関名カナ仕向支店名カナ depositamount remitternamekana paymentbankname paymentbranchname サービス企業名 partnername 0 "502" "ｱｼﾞｻｲ" "099622" "ｱｵｿﾞﾗﾀﾛｳﾃｽﾄﾆﾕｳｷﾝｸﾞﾁ" "ｼﾞｰｴﾑｵｰｱｵｿﾞﾗ(ｶﾃｽﾄﾆﾕｳｷﾝｸﾞﾁ" "0000" "ﾃｽﾄﾀﾛｳ" "ｱｵｿﾞﾗｷﾞﾝｺｳ" "ﾎﾝﾃﾝ" "GMOあおぞらネット銀行" 摘要内容 remarks 255 明細キー itemkey 24 全角文字全振込入金口座契約サービス企業名全該当データがない場合は項目自体を設定しません口座ID毎に設定される明細キー明細データtimestamp μs 5 "20809T:59:59+09:00" " " "002456" "20" "0" "ﾋﾞｼﾞﾈｽ" "ﾎｳｼﾞﾝｴｲｷﾞﾖｳﾌﾞ" "2456" "ＧＭＯあおぞら太郎" "GMOあおぞら株式会社" "20809" ":59:59+09:00" " " "振込ｲｰﾃﾞｲｰｱｲテストタロウあじさい支店 069" " " 出力日:2020/2/0

8 ＡＰＩ振込入金口座_未送信明細取得レスポンス例 { "messages" : [ { "messageid" : " ", "timestamp" : "20809T:59:59+09:00", "account" : { "raid" : "002456", "rabranchcode" : "0", "rabranchnamekana" : "ﾎｳｼﾞﾝｴｲｷﾞﾖｳﾌﾞ", "raaccountnumber" : "2456", "raholdername" : "GMOあおぞら株式会社", "basedate" : "20809", "basetime" : ":59:59+09:00" }, "vatransaction" : { "vaid" : " ", "transactiondate" : "20809", "valuedate" : "20809", "vabranchcode" : "502", "vabranchnamekana" : "ｱｼﾞｻｲ", "vaaccountnumber" : "099622", "vaaccountnamekana" : "ｼﾞｰｴﾑｵｰｱｵｿﾞﾗ(ｶﾃｽﾄﾆﾕｳｷﾝｸﾞﾁ", "depositamount" : "0000", "remitternamekana" : "ﾃｽﾄﾀﾛｳ", "paymentbankname" : "ｱｵｿﾞﾗｷﾞﾝｺｳ", "paymentbranchname" : "ﾎﾝﾃﾝ", "partnername" : "GMOあおぞらネット銀行", "remarks" : "振込ｲｰﾃﾞｲｰｱｲテストタロウあじさい支店 069", "itemkey" : " " } }, { "messageid" : " ", "timestamp" : "20809T8:4:2+09:00", "account" : { } ] } 以下エラー発生時のHTTPステータスとなりますレスポンスは共通仕様レスポンス共通仕様の異常時の共通エラーレスポンスをご参照ください 400 Bad Request 40 Unauthorized 40 Forbidden 404 Not Found 405 Method Not Allowed 406 Not Acceptable 4 Length Required 42 Precondition Failed 45 Unsupported media type 500 Internal Server Error 50 Service Unavailable 504 Gateway Timeout その他特記事項取得上限件数 500件取得できる明細数が500に満たないときは取得できる明細のみを返却します取得できた明細数が500件の場合まだ取得できる明細が残っている可能性がありますので 404 Not Found が返却されるまでリクエストを繰り返してください 6 出力日:2020/2/0

9 ＡＰＩ振込入金口座_入金明細通知概要振込入金口座による被仕向入金が発生した際入金明細通知を配信します法人口座および個人事業主口座のみ対象となり個人口座は対象外となります HTTPメソッド : URLリクエストパス POST 配信先指定のURL HTTPリクエストヘッダアクセストークン xaccesstoken シグネチャ xwebhooksignature ユーザーエージェント UserAgent 認証情報 Authorization イベント種別 xeventtype 28 通知対象ユーザーに発行されたアクセストークン配信先システムがシグネチャ検証に対応している場合のみ設定 256 銀行システムが配信先システムに発行したクライアントシークレットをキーとして HS256でボディを署名しBase64エンコードした値を設定 28 GMOあおぞらネット銀行の通知を示すユーザーエージェント 28 配信先システムがBasic認証に対応している場合のみ設定配信先システムが銀行システムに発行したユーザー名とパスワードを":"(コロンで連結し Base64エンコードした値を設定通知するイベントの種別 vadeposittransaction=振込入金口座への入金明細通知 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRS UpKPiHJv+vjl8hVFcIPr/Xa6aGafRwMud2jfJG YNS4= GMO Aozora Net Bank Notification Service Agent Basic CUEzYjhiRmg0QQycDFIcTo2WEpBMVZabTF NODdHeVdPeXBSM2JxUjRuYlZkdlR4bk9TbGJ oqk9vgpgvnhhuluwyw== vadeposittransaction HTTPリクエストボディメッセージID messageid イベント生成日時 timestamp 入金口座情報 account 入金口座ID raid 半角英数字 9 9 メッセージを一意に識別するID ISO860 時差(offset)も表記 YYYYMMDDTHH:MM:SS+09:00形式 object 入金口座情報入金先の口座を識別するID 2 29 入金口座支店コード rabranchcode 入金口座支店名カナ rabranchnamekana 5 入金口座口座番号 raaccountnumber 入金口座口座名義漢字 raholdername 48 基準日 basedate 0 0 基準時刻 basetime 4 4 振込入金口座入金明細 vatransaction object 振込入金口座ID vaid 0 0 応答日付もしくは入金明細の基準日を示す YYYYMMDD形式応答時刻もしくは入金明細の基準時刻を示す ISO860 時差(offset)も表記 HH:MM:SS+09:00形式振込入金口座入金明細情報振込入金口座を識別するID transactiondate 0 0 YYYYMMDD形式 "20809" 取引日 valuedate 0 0 YYYYMMDD形式 "20809" 起算日支店コード支店名カナ口座番号 vabranchcode vabranchnamekana vaaccountnumber 5 口座名義カナ vaaccountnamekana 40 入金金額振込依頼人名カナ仕向金融機関名カナ仕向支店名カナ depositamount remitternamekana paymentbankname paymentbranchname サービス企業名 partnername 50 "502" "ｱｼﾞｻｲ" "099622" "ｱｵｿﾞﾗﾀﾛｳﾃｽﾄﾆﾕｳｷﾝｸﾞﾁ" "ｼﾞｰｴﾑｵｰｱｵｿﾞﾗ(ｶﾃｽﾄﾆﾕｳｷﾝｸﾞﾁ" "0000" "ﾃｽﾄﾀﾛｳ" "ｱｵｿﾞﾗｷﾞﾝｺｳ" "ﾎﾝﾃﾝ" "GMOあおぞらネット銀行" 摘要内容 remarks 255 明細キー itemkey 24 全角文字全振込入金口座契約サービス企業名全該当データがない場合は項目自体を設定しません口座ID毎に設定される明細キー明細データtimestamp μs " " "20809T:59:59+09:00" " " "002456" "20" "0" "ﾋﾞｼﾞﾈｽ" "ﾎｳｼﾞﾝｴｲｷﾞﾖｳﾌﾞ" "2456" "ＧＭＯあおぞら太郎" "GMOあおぞら株式会社" "20809" ":59:59+09:00" " " "振込ｲｰﾃﾞｲｰｱｲテストタロウあじさい支店 069" " " 出力日:2020/2/0

10 ＡＰＩ振込入金口座_入金明細通知リクエスト例 POST /example/webhook/post/ HTTP/. Host: example.merchant.com xaccesstoken: NzYxMDAxIiwKICJhdWQiOiAiczZCaGRS xwebhooksignature: UpKPiHJv+vjl8hVFcIPr/Xa6aGafRwMud2jfJGYNS4= UserAgent: GMO Aozora Net Bank Notification Service Agent Authorization: Basic YjNFNWhwWEZsTWJDdXRZaEZpMDc6WldidmgwdGp0YjFYamGQXUxTGh2d2RVjYzdGM0clpddrTWYzbQ== xeventtype: vadeposittransaction ContentType: application/json;charset=utf8 { "messageid" : " ", "timestamp" : "20809T:59:59+09:00", "account" : { "raid" : "002456", "rabranchcode" : "0", "rabranchnamekana" : "ﾎｳｼﾞﾝｴｲｷﾞﾖｳﾌﾞ", "raaccountnumber" : "2456", "raholdername" : "GMOあおぞら株式会社", "basedate" : "20809", "basetime" : ":59:59+09:00" }, "vatransaction" : { "vaid" : " ", "transactiondate" : "20809", "valuedate" : "20809", "vabranchcode" : "502", "vabranchnamekana" : "ｱｼﾞｻｲ", "vaaccountnumber" : "099622", "vaaccountnamekana" : "ｼﾞｰｴﾑｵｰｱｵｿﾞﾗ(ｶﾃｽﾄﾆﾕｳｷﾝｸﾞﾁ", "depositamount" : "0000", "remitternamekana" : "ﾃｽﾄﾀﾛｳ", "paymentbankname" : "ｱｵｿﾞﾗｷﾞﾝｺｳ", "paymentbranchname" : "ﾎﾝﾃﾝ", "partnername" : "GMOあおぞらネット銀行", "remarks" : "振込ｲｰﾃﾞｲｰｱｲテストタロウあじさい支店 069", "itemkey" : " " } } レスポンス情報 200 OK レスポンスが200以外の場合またはレスポンスが返却されない場合は配信エラーとみなしますその他特記事項配信エラー時の挙動配信エラーとなった場合は通知のリトライを試みます通知のリトライは最初のメッセージ通知から指数関数的に間隔を広げながら最大１時間まで行われます最初の通知から１時間以上継続してリトライがエラーとなった場合は自動的に配信を停止状態に移行します 8 出力日:2020/2/0

11 EOF 出力日 :2020/2/0

Microsoft Word - アクセストークン取得API仕様書（AS）_ver1.docx

Microsoft Word - アクセストークン取得API仕様書（AS）_ver1.docx バリューコマースウェブサービストークン取得 API リファレンス ( アフィリエイトサイト向け ) 第 1 版概要アフィリエイトサイト向け認証下 API にアクセスするために必要なトークンを提供するリクエストについての仕様書ですトークン発リクエストをうためには事前に管理画設定 > レポート API 認証キーの取得画にて API 認証キーを発している必要があります有効期限

GMO あおぞらネット銀行 オープン API 仕様書イベント通知編 Version: Last Modified: /2/8 GMO Aozora Net Bank, Ltd. All Rights Reserved. 出力日 :2020/2/10

GMO あおぞらネット銀行オープン API 仕様書イベント通知編 Version: Last Modified: /2/8 GMO Aozora Net Bank, Ltd. All Rights Reserved. 出力日 :2020/2/10