このAPIを用いることで、PayPayのユーザー認可をQRコードを用いてシームレスに取得する事が可能です。

詳細なフローはここからダウンロードできます。

ユーザー認可フローのダウンロード

PayPay Open Payment APIでは、セキュリティ対策としてTLS 1.2以上の使用が必須となっております。TLS1.0およびTLS1.1では接続できませんのでご注意ください。

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

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

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

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

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

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

加盟店は、ユーザー認証を取得するたびに、「アカウントリンクQRコードの作成」APIにリクエストを行い、ユーザーが同意するPayPay許可画面のURLを生成する必要があります。

特別なケースとして、お客様が認証プロセスにおいてKYCの設定を義務付けることを選択した場合、ユーザーは認証画面においてKYCデータの照合など、いくつかの追加ステップを経る必要があります。KYCデータの照合に失敗した場合、ユーザーはPayPayでKYCを完了するか、加盟店のページに戻るかの選択肢が表示されます。

認可が成功すると、ユーザー認可IDがユーザーごとに発行されます。 このIDをバックエンドに保存し、それを内部ユーザーに関連付ける必要があります。 このユーザー認可IDはクライアント側に保存しないようにしてください。 このIDはOPAへのリクエストで使用され、決済、キャッシュバック及びTopUpのリクエストでユーザーを識別します。

すべてのユーザー認可には有効期間が設けられています。決済、残高付与や再認可を行う度に自動で延長されます。 これは、オンボーディングプロセス中に定義されたユーザー認可有効期間です。
ユーザー認可IDの有効期限は、カスタマーイベントwebhookのexpiry、又は、Get user authorization statusのレスポンスデータのexpireAtで確認ができます。
また、PayPayユーザーは、加盟店に通知することなく、PayPayサービスから認可を取り消すこともできます。 どちらの場合も、ユーザー認可IDを再度取得する必要があります。 ユーザ環境によって、リダイレクトが複数回発生する可能性があります。 こちらをご確認の上、適切な処理をお願いします。

App Invoke flow

Merchant desktop site with PayPay scan

Merchant desktop site with PayPay web login

PayPayの認可ページで、ユーザーは加盟店の認可取得を承認または拒否する選択ができます。 そのユーザーの操作に応じて、認可の取得は成功または失敗する可能性があります。

アカウントリンクの状態を取得する3つの方法

アカウントリンクの結果を受け取るには、次の3つの方法があります。

• リダイレクトURLに付加されたペイロード
• webhook通知のペイロード
• 「アカウントリンクQRコードのステータス取得」APIからのポーリング

最初の 2つは推奨される実装方法で、最後の 1つは任意です。 最初の 2つのオプションはリアクティブであるため、情報をただちに更新する可能性が高いです。 リダイレクトと Webhook がどちらも失敗した場合、ステータスを取得するフォールバック手段としてポーリングが提供されます。

3つの方法がすべて失敗した場合は、アカウントリンクのセッションが失敗し、回復できないことを意味します。 マーチャントの側で新しい試行を開始し、アカウントリンクが失敗したことをユーザーに通知する必要があります。

1. リダイレクトURLに付加されたペイロード

結果をJWTトークンにエンコードして、それをCreate Account Link QR Code API（/v1/qr/sessions） に指定されているリダイレクトURLに渡します。

リダイレクトURLに渡す特定のパラメータは以下のとおりです。

• apiKey は、登録プロセス中に発行されたapi keyです。
• responseToken は、apiKeyに対応するapiKeySecretのBase64デコード値で署名された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

ユーザーがアカウントリンクを拒否した場合、profileIdentifier と userAuthorizationId はレスポンスのJWTには含まれないことに注意してください。

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

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

認証画面の有効期限が切れた場合、以下のURLにリダイレクトします。

  https://<redirect url>

2. webhook通知のペイロード

Webhook section参照。

3. 「アカウントリンクQRコードのステータス取得」APIからのポーリング

Fetch Status of Account Link QR Code参照。

本ドキュメントに記載されているAPIは、HMAC方式での認証が必要です。 HMAC方式での認証の実装においては、認証オブジェクト生成に対してすべてのリクエストを考慮します。

これらから生成されるサンプルHMAC Authヘッダーは以下の通りです。

hmac OPA-Auth:APIKeyGenerated:NW1jKIMnzR7tEhMWtcJcaef+nFVBt7jjAGcVuxHhchc=:acd028:1579843452:1j0FnY4flNp5CtIKa7x9MQ==

Step 1: MD5アルゴリズムを使用してbodyとcontent-typeをハッシュ化する

サンプルコード

private String requestBody;
private String contentType;

MessageDigest md = MessageDigest.getInstance("MD5");
md.update(contentType.getBytes(StandardCharsets.UTF_8));
md.update(requestBody.getBytes(StandardCharsets.UTF_8));
String hash = new String(
          Base64.getEncoder().encode(md.digest()),
          StandardCharsets.UTF_8);

Note : HTTP GETメソッドの場合など、リクエストの本文がない場合、MD5を生成する必要はありません。代わりに、hashには"empty"がセットされます。

Step 2: HMAC-SHA256でハッシュ化される文字列を生成します。

リクエストの署名には、以下のパラメータが必要です。

private String requestUrl; //Only the request URI Example: "/v2/codes/payments/dynamic-qr-test-00002"
private String httpMethod;
private String nonce; //Random string
private String epoch;
private String contentType;
private String hash; //Output of step 1
private static final String DELIMITER = "\n";

byte[] hmacData = new StringBuilder()
                    .append(requestUrl)
                    .append(DELIMITER)
                    .append(httpMethod)
                    .append(DELIMITER)
                    .append(nonce)
                    .append(DELIMITER)
                    .append(epoch)
                    .append(DELIMITER)
                    .append(contentType)
                    .append(DELIMITER)
                    .append(hash != null ? hash : "")
                    .toString()
                    .getBytes(StandardCharsets.UTF_8);

Note : HTTP GETメソッドの場合など、リクエストの本文がない場合、content-typeおよびhashには"empty"がセットされます。

Step 3 : Step2で生成された値と、Key secretを使用してHMACオブジェクトを生成します。

public final String toBase64HmacString() {
    private String apiKeySecret;
    private byte[] dataToSign; //Output from step 2
    try {
      SecretKeySpec signingKey = new SecretKeySpec(apiKeySecret.getBytes(StandardCharsets.UTF_8),
          "HmacSHA256");
      Mac sha256HMAC = Mac.getInstance("HmacSHA256");
      sha256HMAC.init(signingKey);
      byte[] rawHmac = sha256HMAC.doFinal(dataToSign);
      return java.util.Base64.getEncoder().encodeToString(rawHmac);
    } catch (GeneralSecurityException e) {
      LOGGER.error("Unexpected error while creating hash: " + e.getMessage());
      throw new IllegalArgumentException(e);
    }
  }

Step 4 : ヘッダーオブジェクトを生成します。

String authHeader = "hmac OPA-Auth:" + api-key +
":" + macData + ":" + nonce + ":" + epoch + ":" + hash;

Note: macDataはStep3で生成された値を使用してください。また、nonceとepochは、Step2で使用した値を渡す必要があります。

HTTP GETメソッドの場合などリクエストの本文がない場合、hash値は"empty"となるため、ヘッダーオブジェクトは下記の通りとなります。

String authHeader = "hmac OPA-Auth:" + api-key +
":" + macData + ":" + nonce + ":" + epoch + ":empty";

authHeaderの値を、HttpHeader.AUTHORIZATIONにセットして渡してください。
PayPay側で渡ってきたデータをデコードし、SHA256（ "key"、requestParams）を再作成します。 再作成したmacDataとヘッダーで渡ってきた値が一致しているかを検証します。

PayPay OPAはhttpレスポンスステータスコードとOPAエラーコードを使用してリクエストの成功または失敗を示します。 これらの情報を使用して、どのようなエラー対応をするかを判断できます。 PayPay OPAは以下のhttpレスポンスステータスコードを返します。

共通コード

アカウントリンクQRコードの作成

アカウントリンクQRコードのステータス取得

推奨タイムアウト値は各APIで指定されています。 APIのタイムアウト値は30秒以下であってはいけません。 タイムアウトが発生した場合、それは状態が不明なステータスとして扱ってください。

PayPayは、アカウントでイベントが発生したときにアプリケーションに通知するWebhookを送信します。 通知を受信するためには、POSTメソッドを使用してクライアントにデータを送信するWebhook URLを設定する必要があります。 すべての通知データには、どのイベントが発生したかを判断するためにクライアントサービスで使用できるnotification_typeフィールドがあります。

Webhook処理が正常に終了した場合、200 OK のHTTPステータスコードを返してください。 レスポンスボディは必須ではないですが、"OK"など、簡単な文字列を返していただくことを推奨します。

セキュリティ上の問題から、通知受信において、クライアントによるPayPay IPアドレスのホワイトリスト登録を強く推奨します。

現在Webhookに送信されている通知について、以下もご一読ください。

ユーザー状態の変化に関連するイベントです。 authroization の部分は文字通りです。

通知の種別ごとの例は以下の通りです。

この通知は、クライアントがユーザーの認可を正常に取得した場合に送信されます。

{
  "notification_type": "customer.authroization.succeeded",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "scopes": "direct_debit",
  "userAuthorizationId": "xxxxx",
  "profileIdentifier": "*******5678",
  "expiry": 1669734000  // the authorization id expiration epoch timestamp in seconds
}

この通知は、クライアントがユーザーの認可の取得に失敗した場合に送信されます。

{
  "notification_type": "customer.authroization.failed",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "result": "declined",
  "reason": "invalid scope"
}

result（結果）はdeclined、kyc_not_completed、kyc_data_mismatch のいずれかになります。

• declined : リクエストがユーザーによって拒否された場合
• kyc_not_completed ユーザーがKYC (本人確認) を完了していない場合
• kyc_data_mismatch ユーザーのKYCデータが一致しない場合

この通知は、ユーザーがPayPayアプリから、認可を取り消した場合に送信されます。

{
  "notification_type": "customer.authroization.revoked",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "userAuthorizationId": "xxxxx",
  "referenceId": "yyyy"
}

この通知は、ユーザー認可の期限がPayPayによって延長された場合に送信されます。

支払いの実施／認可の取得をした場合にユーザー認可の期限を延長します。 これにより、ユーザー操作による認可の取得を減らすことで、ユーザーへの負担を減らせます。

{
    "notification_type": "customer.authroization.extended",
    "notification_id": "evt_aXnbdeFt2Ke",
    "createdAt": "1349654313",
    "scopes": "direcrt_debit",
    "userAuthorizationId": "xxxxx",
    "expiry": 1669734000  // the authorization id expiration epoch timestamp in seconds
}

この通知は、ユーザーが退会した時に送信されます。

サンプル・イベント:

{
  "notification_type": "customer.authroization.canceled",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "userAuthorizationId": "xxxxx"
}

最新のFAQについてはこちらをご参照ください。