OAuth API

PAY.JP では、RFC6749に沿ってOAuthのAPIを提供しています。 現在、authorization_code grant および refresh_token grantがご利用いただけます。

エンドポイント

各種OAuthリクエストのエンドポイントは下記です。

Authorization Endpoint

https://id.pay.jp/.oauth2/authorize

Token Endpoint

https://api.pay.jp/u/.oauth2/token

API Endpoint Base

https://api.pay.jp/u/v1/

scope

PAY.JP OAuth APIでは以下のscopeがご利用いただけます。

権限の内容
accounts PAY.JPアカウントの情報の読み取り
cards PAY.JPアカウントに登録されている暗号化されたカード情報の読みとり、決済のためのトークン化
addresses PAY.JPアカウントに登録されている商品配送先住所情報の読み取り

アクセス許可画面について

Authorization Endpointでユーザへ提示するアクセス許可のリクエスト画面では、下記の情報を利用します。 OAuth APIを使ってサービスを提供される際は、該当項目を適切にご設定ください。

表示情報 設定箇所
サービス名 本番申請時にご入力いただいた「サービス名」
サービスURL 本番申請時にご入力いただいた「サイトURL」
サービス提供者 ダッシュボードで設定できる「運営者名」
利用する権限 Authorization Endpointへ遷移時のscopeパラメータ

また、cardsscopeを含む場合のアクセス許可画面では、該当のアプリケーションで通常利用するカードの選択が行えるようになっています。 ここで選択されたカードの情報はGET /cards/defaultへのリクエストによって取得できます。詳しくは「カード情報の取得」APIをご参照ください。

OAuth API利用の流れ

Authorization Request

まず最初にユーザからAPIアクセスの許可を取る必要があります。 下記のURLクエリパラメータを付与して、ユーザをAuthorization Endpoinへアクセスさせてください。

URLパラメータ

説明
response_type レスポンスの種類。"code"を指定してください。
client_id 作成したOAuth ClientのClient ID
scope アクセス許可を取得するscope
state CSRF対策のためのオプショナルパラメータ。リクエストごとに一意の適当な値を指定することができます。

リクエストURL例

https://id.pay.jp/.oauth2/authorize?response_type=code&client_id=827cde0e3dd648d6d83c08b091b2b10c3c266e36&scope=accounts+cards&state=9d6cfbf77eb6e80a

ユーザがアクセス許可をすると、リダイレクトが行われ、下記のようなOAuth Clientに設定したコールバックURLへcodeパラメータをもってアクセスします。 このcodeパラメータを使って、次の Token Request を行います。 また、リクエスト時にstateパラメータを渡していた場合はこの時に返ってくるstateを利用して、現在のセッションがstate発行時のセッションと同一であることを確認するようにしてください。

コールバックURL例

https://your.domain/payjp/callback?state=9d6cfbf77eb6e80a&code=7YGsyX7QVMa3pC0ImpVJnspenJEimP

Token Request

先ほど受け取ったcodeパラメータを使って、サーバーサイドからToken Requestを行います。 下記のパラメータをつけて、Token EndpointへPOSTリクエストを行ってください。

URLパラメータ

説明
grant_type トークンの種類。"authorization_code"を指定してください。
code Authorization Requestのコールバックで受けとったcodeパラメータ
client_id OAuth ClientのClient ID

また、認証のためのパラメータとして、Client ID, Client Secretを使ったBasic認証のヘッダをつけるか、 URLパラメータにclient_secretをつける必要があります。

curlによる例

curl -X POST https://api.pay.jp/u/.oauth2/token \
 -u "827cde0e3dd648d6d83c08b091b2b10c3c266e36:your_client_secret_here" \
 -d "grant_type=authorization_code" \
 -d "code=7YGsyX7QVMa3pC0ImpVJnspenJEimP" \
 -d "client_id=827cde0e3dd648d6d83c08b091b2b10c3c266e36"

または

curl -X POST https://api.pay.jp/u/.oauth2/token \
 -d "grant_type=authorization_code" \
 -d "code=7YGsyX7QVMa3pC0ImpVJnspenJEimP" \
 -d "client_id=827cde0e3dd648d6d83c08b091b2b10c3c266e36" \
 -d "client_secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

成功すると下記のパラメータを含んだトークンが発行されます。

レスポンス内容

説明
scope 発行されたトークンのもつscope
token_type 発行されたトークンの種類。常に固定値Bearerとなる
id トークンを所持するアカウントのID
refresh_token リフレッシュトークン
expires_in アクセストークンの有効期限
access_token アクセストークン
レスポンス例
{
  "scope" : "accounts cards",
  "token_type" : "Bearer",
  "id": "acct_cus_38153121efdb7964dd1e147",
  "refresh_token" : "BpU4ugFbYzqiyiO7RBqQOPckopQcXbFVl+uNNKg2Hcg=",
  "expires_in" : 630720000,
  "access_token" : "2kPl8cp4p7YKRe82i6W+ikc7DLVhCUreTU/bsRV5zWE="
}

API Request

発行されたアクセストークンを使って各APIへのリクエストを行います。 アクセストークンは、Authorizationヘッダーに指定するか、GETリクエストの場合はURLクエリパラメータとしても指定できます。 クエリパラメータとして指定する場合は、URLエンコードが必要になりますのでご注意ください。

curlによる例

curl https://api.pay.jp/u/v1/accounts \
 -H "Authorization: Bearer 2kPl8cp4p7YKRe82i6W+ikc7DLVhCUreTU/bsRV5zWE="

または

curl "https://api.pay.jp/u/v1/accounts?access_token=2kPl8cp4p7YKRe82i6W%2Bikc7DLVhCUreTU%2FbsRV5zWE%3D"

API一覧

エンドポイント 必要なscope
アカウント情報の取得 GET /accounts accounts (,cards)
カード一覧の取得 GET /cards cards
カード情報の取得 GET /cards/:id cards
カードのトークン化 POST /cards/:id/tokenize cards
住所情報の取得 GET /addresses addresses

API レスポンス内容

アカウント情報の取得

GET /accounts

レスポンス内容

説明
created アカウントが作成された時刻
default_card アカウントがデフォルトで利用するカード ※このフィールドを取得するにはcards scopeを許可されている必要があります。
email メールアドレス
first_name アカウントのファーストネーム
id アカウントID
pay_id アカウントのPAY ID。未設定の場合は null
last_name アカウントのラストネーム
updated アカウント情報が更新された時刻

レスポンス例

{
  "created": 1457664156,
  "default_card": null,
  "email": "xxxxxx@example.com",
  "first_name": "Taro",
  "id": "acct_cus_38153121efdb7964dd1e147",
  "pay_id": "pay_kun",
  "last_name": "Yamada",
  "updated": 1457664156
}

カード一覧の取得

GET /cards

レスポンス内容

説明
data card オブジェクトの配列
count 結果の件数
has_more 結果がページングされて全てのデータを返していたに時にtrueとなるフラグ
object オブジェクトの種類。常に "list" が返ります。
url リソースのURL
説明
card.accepted_brand このカードが利用可能なブランドかどうか
card.address_city 市区町村
card.address_line1 番地など
card.address_line2 建物名など
card.address_state 都道府県
card.address_zip 郵便番号
card.address_zip_check
card.brand カードのブランド名
card.country
card.created カードの登録された時刻
card.cvc_check カードがcvcチェック済みかどうか
card.exp_month カード有効期限(月)
card.exp_year カード有効期限(年)
card.fingerprint カードのハッシュ値
card.id cardオブジェクトのID
card.last4 カード番号の下4桁
card.name カードの名義
card.updated カード情報の更新された時刻

レスポンス例

{
  "count": 1,
  "data": [
    {
      "accepted_brand": true,
      "address_city": null,
      "address_line1": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": "unchecked",
      "brand": "Visa",
      "country": null,
      "created": 1465462226,
      "cvc_check": "passed",
      "exp_month": 12,
      "exp_year": 2018,
      "fingerprint": "bd919bdc27e893a39b812fcc2c560adc",
      "id": "acct_car_e5ac26ab070f544a05807c7",
      "last4": "0400",
      "name": "TARO YAMADA",
      "updated": 1465462226
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/u/v1/cards"
}

カード情報の取得

GET /cards/:id

:idにはcardオブジェクトのidまたはdefaultと入力してください。 defaultを指定した場合は、ユーザがアクセス許可画面で選択したカードの情報が返されます。 ユーザに明示的にカードを選択させるような場合を除いて、通常の決済処理時にはdefaultをご利用ください。

レスポンス内容

GET /cards の cardオブジェクト単体の内容と同じになります

レスポンス例

{
  "accepted_brand": true,
  "address_city": null,
  "address_line1": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": "unchecked",
  "brand": "Visa",
  "country": null,
  "created": 1465462226,
  "cvc_check": "passed",
  "exp_month": 12,
  "exp_year": 2018,
  "fingerprint": "bd919bdc27e893a39b812fcc2c560adc",
  "id": "acct_car_e5ac26ab070f544a05807c7",
  "last4": "0400",
  "name": "TARO YAMADA",
  "updated": 1465462226
}

カードのトークン化

POST /cards/:id/tokenize

:idにはcardオブジェクトのidまたはdefaultと入力してください。 defaultを指定した場合は、ユーザがアクセス許可画面で選択したカードのトークンが作成されます。 ユーザに明示的にカードを選択させるような場合を除いて、通常の決済処理時にはdefaultをご利用ください。

レスポンス内容

説明
card トークン化したカードの情報。※このオブジェクトに含まれるid ではカード情報の取得やトークン化を行うことはできませんのでご注意ください。
created トークンの作成された時刻
id 作成されたトークン
livemode 本番モードの時にtrue、テストモードの時にfalseとなるフラグ
object オブジェクトの種類。常に "token" が返ります。
used トークンが利用済みかどうかのフラグ。APIを呼び出した時点では常にfalseが返ります。

レスポンス例

{
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1465518210,
    "customer": null,
    "cvc_check": "unchecked",
    "exp_month": 12,
    "exp_year": 2020,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_10e3d1cc44bb8f107d35b5bfc358",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1465518210,
  "id": "tok_ca30ec646d8d238bda67c8839859",
  "livemode": false,
  "object": "token",
  "used": false
}

住所情報の取得

GET /addresses

レスポンス内容

説明
address_city 市区町村
address_line1 住所1
address_line2 住所2
address_state 都道府県
address_zip 郵便番号
country
created アカウントが作成された時刻
email メールアドレス
first_name アカウントのファーストネーム
id アカウントID
last_name アカウントのラストネーム
phone 電話番号
updated アカウント情報が更新された時刻

レスポンス例

{
  "address_city": "渋谷区",
  "address_line1": "道玄坂2丁目11−1",
  "address_line2": "Gスクエア4F",
  "address_state": "東京都",
  "address_zip": "150-0043",
  "country": "JP",
  "created": 1464005269,
  "email": "xxxx@example.com",
  "first_name": "TARO",
  "id": "acct_cus_xxxxxxxxxxxxxxxxxxxxxxx",
  "last_name": "YAMADA",
  "phone": null,
  "updated": 1464005269
}