Skip to content

APIドキュメントまとめ

はじめに

APIドキュメントの読み方

GPaymentsのActiveServer APIのドキュメントには、各APIの許可されるエンドポイントおよびリクエストHTTPメソッドが含まれています。たとえば、/api/v1/auth/3riはエンドポイントURLであり、許可されるHTTPメソッドはPOSTです。 apiエンドポイント

エンドポイントの詳細を確認するには、エンドポイント・ボックスのいずれかをクリックし、詳細を表示します。以下のスクリーンショットのように表示されます。このスクリーンショットは、APIドキュメントの読み方を説明しています。 apiエンドポイント

認証API

認証APIを使用すると、加盟店と決済代行会社が3Dセキュア2フローをeコマースサイトに統合できます。すべての認証APIは/api/v1/auth/...で始まり、RESTFulの命名規則に従っています。利用可能な主な認証フローには3つあります。

  • アプリベース - 登録されたエージェント（加盟店、デジタル・ウォレットなど）によって指定されたアプリから発生したコンシューマー・デバイス上での取引中の認証。たとえば、コンシューマー・デバイス上の加盟店のアプリ内でチェックアウト・プロセス中に発生したeコマース取引などです。

  • ブラウザベース - ブラウザを使用してWebサイトから発生したコンシューマー・デバイスまたはコンピュータ上での取引中の認証。たとえば、Webサイト内でチェックアウト・プロセス中に発生したeコマース取引などです。

  • 3DS Requestor Initiated (3RI) - 直接カード会員を介さないアカウント情報の確認。たとえば、アカウントがまだ有効であることを確認するサブスクリプションベースのeコマース加盟店などです。

最新の認証APIはこちらで確認できます。

項目条件の説明

各項目には下記のいずれかの条件が記載されています。

  • 必須 - この項目はリクエストを送信する際に必ず必要です。ActiveServerはこの項目の有無を確認し、妥当性の確認を行います。必須項目には*印が記載されています。

  • 条件付き - 項目に記載された条件が満たされていた場合にはリクエストに定義する必要があります。項目が定義されていればActiveServerは妥当性の確認を行います。送信されたJSONにこの項目が定義されていなければActiveServerは妥当性の確認を行いません。

  • オプション - オプションでリクエストに定義できます。項目が定義されていればActiveServerは妥当性の確認を行います。送信されたJSONにこの項目が定義されていなければActiveServerは妥当性の確認を行いません。

最新の認証APIはここからアクセスできます。

認証API - 認証方法

すべての認証APIエンドポイントは、クライアントとサーバーの相互認証が必要なX.509認証によって保護されています。これは、ActiveServerによって発行されたクライアント証明書を使用して実行されます。ActiveServerは2種類のクライアント証明書を提供します。各加盟店用の加盟店クライアント証明書、またはビジネス管理者ユーザー向けの認証APIマスタークライアント証明書です。認証APIの呼び出しを行う手順は次のとおりです。

  1. このガイドに従ってインスタンスがアクティブ化されていることを確認します。

  2. クライアント証明書をダウンロードする。

  3. ユーザープロフィールページからCA証明書チェーンをダウンロードします。CA証明書は、最初の証明書がサーバーCAで、次にGPayments中間CA、最後にGPaymentsルートCAとなっている.pem形式です。

  4. 統合ガイドまとめに従って、認証APIを呼び出すために初めから3DSリクエスターをセットアップできます。 手順2で選択したクライアント証明書方法の使用に関する具体的な詳細については、デモ3DSリクエスターの設定を参照してください。

警告

インスタンスがアクティブ化されていない場合、DOWNLOADボタンは表示されません。

管理API

管理APIは加盟店の管理などの管理タスクを実行するのに利用できます。すべての管理APIは/api/v1/admin/...で始まり、RESTFulの命名規則に従っています。たとえば、こちらで説明されているcreating merchantは、POST APIエンドポイント/api/v1/admin/merchantsを呼ぶことで実行できます。

最新の管理APIはこちらで確認できます。

管理API - 認証方法

管理APIへの認証は認証APIと同様にクライアント証明書を利用して実行されます。

  1. このガイドに従ってインスタンスがアクティブ化されていることを確認します。

  2. ダッシュボードのユーザープロフィールページから管理APIのクライアント証明書をダウンロードします。この証明書は.p12形式です。

  3. 同ページからCA証明書チェーン証明書をダウンロードします。CA証明書は、最初の証明書がサーバーCAで、次にGPayments中間CA、最後にGPaymentsルートCAとなっている.pem形式です。

  4. HTTPクライアント・リクエスト内に含めることで、API認証に対してダウンロードしたクライアント証明書とCAバンドルを使用します。この方法については使用しているHTTPクライアントを参照してください。テスト方法についてはAPIクイック・スタートに従ってください。

管理API証明書

管理APIクイック・スタート

cURLを使用してAPIを試すには、opensslを使用し、以下のcurlコマンドを使用して、X.509証明書をPEM形式に変換する必要があります。

  1. https://www.openssl.org/からopensslコマンド ラインをダウンロードしてインストールします。
  2. 上記の管理API認証方法セクションに従って、クライアント証明書とCA証明書をダウンロードします。

  3. OpenSSLなどを使用して.p12から.pem形式のクライアント証明書と秘密鍵を取得する。

  4. AS管理APIエントリー ポイントを使用して、cURLリクエストを実行します。この場合、/api/v1/admin/merchantsから加盟店のリストが取得されます。

    1
    curl -k https://your.server.address:7443/api/v1/admin/merchants --cacert cacerts.pem --cert crt.pem -v --key key.pem

  5. 以下のようなcURLレスポンスが表示されるはずです。
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    <HTTP/1.1 200 OK
<Expires: 0
<Cache-Control: no-cache, no-store, max-age=0, must-revalidate
<X-XSS-Protection: 1; mode=block
<Pragma: no-cache
<X-Frame-Options: DENY
<Date: Mon, 27 May 2019 09:51:59 GMT
<X-Total-Count: 1
<Connection: keep-alive
<X-Content-Type-Options: nosniff
<Strict-Transport-Security: max-age=31536000 ; includeSubDomains
<Transfer-Encoding: chunked
<Content-Type: application/json;charset=UTF-8
<Link: </api/v1/admin/merchants?page=0&size=20>; rel="last",</api/v1/admin/merchants?page=0&size=20>; rel="first"
< 
* Connection #0 to host your.server.adress left intact
[{"bins":"40001 (Test Acquirer)","merchantId":"123456789012345","name":"Test Merchant","status":"ENABLED","merId":"48f3b030-ed1d-4f7f-aa70-85cda288e0cb"}]%

OpenSSLを使用してP12からPEM形式に変更する方法

curlなどのHTTPクライアントを使用する際にクライアント証明書が.pem形式である必要があります。以下のコマンドを使用することで.p12形式のクライアント証明書から秘密鍵とクライアント証明書を.pem形式で出力することが出来ます。

  1. ターミナルを開きます。

  2. 以下のコマンドを使用して.p12ファイルから秘密鍵を抽出します。要求された場合はパスワードを入力します。
    1
    openssl pkcs12 -in YOUR_P12_FILE_NAME.p12 -nocerts -out key.pem

  3. 以下のコマンドを使用して.p12ファイルから証明書を抽出します。要求された場合はパスワードを入力します。
    1
    openssl pkcs12 -in YOUR_P12_FILE_NAME.p12 -clcerts -nokeys -out crt.pem

  4. 秘密鍵からパスワードを消す
    1
    openssl rsa -in key.pem -out key_no_pass.pem