Link user (1.0)

PayPayユーザーのウォレットから決済を回収できるようにするには、ユーザーの認可を明示的に取得する必要があります。

ユーザー認可の取得は、OAuth/OpenID ConnectスタイルのWebView認可および認可フローと同様に、単純なWebリダイレクトフローを通じて行われます。

認可が成功すると、ユーザーごとにユーザー認可IDが発行されます。このIDをバックエンドに保存し、内部ユーザーにリンクする必要があります。このユーザー認可IDがクライアント側に保存されていないことを確認してください。このIDは、Payment、Cashback、およびTopupリクエストでユーザーIDとして使用されます。 決済、残高付与や再認可を行う度に自動で延長されます。
ユーザー認可IDの有効期限は、カスタマーイベントwebhookのexpiry、又は、Get user authorization statusのレスポンスデータのexpireAtで確認ができます。

PayPay OPAの利用を開始するには、事前に定められたプロセスに従ってPayPay加盟店の登録を行なってください。 このプロセスは 情報収集、手動検証、契約確認、およびクレデンシャル情報の発行から構成されます。

PayPayの加盟店として登録された後、以下の項目が設定されます。

• api key と apiKeySecret
• webhookの通知先となるエンドポイント
• クライアントIPのホワイトリスト

これらの設定を管理するには、マーチャントパネルを使用するか、弊社営業担当までご連絡ください。

ユーザーからのPayPayアプリ、PayPayWeb画面への日本国外からのアクセスは制限されています。詳細については個別にご相談ください。

ユーザーの認可を取得するために、ホストアプリはユーザーにパラメーターapiKeyおよびrequestTokenを指定してPayPay認可ウェブページを表示する必要があります。 このページでは、ユーザーはPayPayにログインして、口座振替の許可を加盟店に付与したり、PayPayアプリケーションでQRコードをスキャンして加盟店にリンクできます。

認可ページURL：Production server

https://www.paypay.ne.jp/app/opa/user_authorization?apiKey={apiKey}&requestToken={jwtToken}

認可ページURL：Sandbox server

https://stg-www.sandbox.paypay.ne.jp/app/opa/user_authorization?apiKey={apiKey}&requestToken={jwtToken}

必須パラメーター

• apiKeyは、登録プロセス中に発行されたapi keyです

• requestToken は、対応するapi key secretで署名されたJWTトークンです

{
  "alg": "HS256",
}
.
{
  "aud" : "paypay.ne.jp",
  "iss" : "<merchant organization id>",
  "exp": 1638198000,
  "scope" : "direct_debit,get_balance",
  "nonce" : "<random case sensitive string>",
  "redirectUrl": "https://<merchant service auth redirect endpoint>",
  "referenceId": "<merchant user reference id>",
  "deviceId": ""
}
.
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  base64Decode(API SECRET)
)

cliam	type	description
aud	string	"paypay.ne.jp"
iss	string	加盟店名
exp	number	認可ページURLの有効期限。エポックタイムスタンプ（秒単位）で設定。
scope	array of string	direct_debit：ネイティブペイメント preauth_capture_native：ネイティブペイメント（出荷売上） get_balance：Get balance continuous_payments：継続課金 pending_payments：支払リクエスト merchant_topup：Merchant Top Up cashback：PayPayポイントAPI（旧CashbackAPIもしくは残高API） 下記は一部の特殊な加盟店のみ利用可能となります。 quick_pay user_notification user_topup user_profile push_notification notification_center_og notification_center_ab notification_center_tl bank_registration
nonce	string	クライアント側での検証のため、レスポンスで返却されます。
redirectUrl	url string	クライアントから提供されたコールバックエンドポイント。HTTPSであること、またドメインは事前に許可されたコールバックドメイン内になければなりません。
referenceId	string	加盟店システムでユーザーを識別するためのID。再照合の目的でPayPayデータベースに格納されます。
deviceId	string	（オプション）ユーザーの携帯電話デバイスID。提供されている場合は、より快適なUXを提供するために、この携帯電話デバイスIDを使って、ユーザーの確認とSMSの確認を省略できます。

PayPayの認可ページで、ユーザーは加盟店の認可取得を承認または拒否する選択ができます。 そのユーザーの操作に応じて、認可の取得は成功または失敗する可能性があります。 結果をJWTトークンにエンコードして、前述のrequestTokenに指定されているリダイレクトURLに渡します。 リダイレクトURLに渡す特定のパラメータは以下のとおりです。

• apiKey は、登録プロセス中に発行されたapi keyです。

• responseTokenは、対応するapi keyとsecretで署名されたJWTトークンです。

  {
    "typ": "JWT",
    "alg": "HS256",
  }
  .
  {
    "aud" : "<merchant organization id>",
    "iss" : "paypay.ne.jp",
    "exp" : 1638198000,
    "result": "succeeded",
    "profileIdentifier": "*******5678",
    "nonce" : "<the same nonce in the request>",
    "userAuthorizationId" : "<PayPay user reference id>",
    "referenceId": "<merchant user reference id>"
  }
  .
  signature

claim	type	description
aud	string	加盟店名
iss	string	"paypay.ne.jp"
exp	number	認可ページURLの有効期限。エポックタイムスタンプ（秒単位）で設定。
result	string	succeeded, declined or bad_request
profileIdentifier	string	Masked phone number or email e.g. "*******5678", "abc*******@example.com"
nonce	string	レスポンスを検証するために必要な　クライアント側のリクエスト内の同一のnonce。
userAuthorizationId	string	データベースに保持し、APIの呼び出しの際に使用するPayPayユーザー参照ID。最大長64文字。
referenceId	string	リクエスト内で同一の参照ID。

ユーザーが認可要求を承認または却下した後は、WebViewを以下のURLにリダイレクトします。

https://<redirect url>?apiKey={apiKey}&responseToken={jwtToken}