PayPay Open Payment API（OPA）は、様々なシナリオに対応した決済関連操作が設計されており、ユーザーへ快適な決済体験を提供します。 本書では、PayPay決済パートナー向けに設計したContinuous Payments APIに焦点を当てます。

Continuous Paymentsは、サブスクリプションでの定期的な支払いを必要とするオンライン加盟店向けのAPIです。 シンプルなインテグレーションで、安全に定期的な支払いをユーザーへリクエストすることが可能です。

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

PayPay OPAの利用を開始するには、事前に定められたプロセスに従ってPayPay加盟店の登録を行なってください。

このプロセスは 情報収集、手動検証、契約確認、およびクレデンシャル情報の発行から構成されます。

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

• api keyとsecret
• 許可された認可コールバックドメイン
• ユーザー認可有効期間
• Webhookエンドポイント
• クライアントIPホワイトリスト

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

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

ユーザー認可を取得する方法については、 こちら をご参照ください。

また、SCOPEには"continuous_payments"を指定して下さい。

本ドキュメントに記載されている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とヘッダーで渡ってきた値が一致しているかを検証します。

APIのリクエスト時に加盟店識別子をセットする必要があります。 加盟店識別子をセットするには2つの方法があります。

クエリの中にセットする:

?assumeMerchant={MerchantId}

HTTPヘッダにセットする:

X-ASSUME-MERCHANT: {MerchantId}

両方を指定した場合、クエリにセットしたパラメーターが優先されます。

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

各API共通レスポンスコード

Create a continuous payment

以下のエラーはユーザーがKYC（本人確認）を完了していない場合に発生します。

以下のエラーは使用した支払い方法がCREDIT_CARDまたはPAY_LATER_CCの場合に発生します。

Get payment details

Cancel a payment

Refund a payment

Get refund details

Unlink user

Get user authorization status

Get masked user profile

Get payment methods

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

この状況に対処する方法は2つあります。

1. 取引の状況を照会するには、照会APIを使用してください。 PayPayにおいて元の取引が失敗になっているか存在しない場合は、同じ取引として新しいトランザクションを開始できます。

2. キャンセルAPIが提供されている場合は、取引をキャンセルすることもできます。 キャンセルが承認された後、同じ取引として新しいトランザクションを開始できます。

OPAに関するその他のFAQについてはこちらをご覧ください。

ユーザー認可のステータス変更に伴い、APIの実行に失敗する場合があります。 想定されるユーザー状態と、対応するAPI実行結果は下記の通りとなります。他APIにおいて、ステータス変更に伴うエラーは発生しません。

Get user authorization status

Create a continuous payment、Get payment methods、Check user wallet balance、Get masked user profile

Refund a payment

決済・取消に関して

ユーザー管理に関して

ユーザーがPayPayアプリからの通知を許可している場合、以下の内容の通知がユーザーへ配信されます。.

Push通知

イベント毎の基本的なステータスの遷移と、WEBHOOK通知については下記の通りとなります。

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

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

セキュリティ上の問題から、クライアントのWebhookエンドポイントを、httpsを介したbasic認証で保護することを強く推奨します。 この場合、URLは次のようになります。

https://username:password@the.merchant.com/path/to/webhook

ユーザー状態の変化に関連するイベント

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

{
  "notification_type": "customer.authroization.succeeded",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "scopes": "continuous_payments",
  "userAuthorizationId": "xxxxx",
  "profileIdentifier": "*******5678",
  "expiry": 1234567  // 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",  // or bad_request
  "reason": "invalid scope"
}

Payloadのresult（結果）は、リクエストがユーザーによって拒否された場合はdeclined（拒否された）、 リクエストに無効な情報がある場合はbad_request（不正な要求）のいずれかになります。

この通知は、ユーザーが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": "continuous_payments",
    "userAuthorizationId": "xxxxx",
    "expiry": 1234567  // 秒単位の認証ID有効期限エポックタイムスタンプ
}

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

サンプル・イベント:

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

PayPayでは取引明細ファイル（突合ファイル）を日次の処理で生成し、Webhookで通知します。
取引ステータス: "取引失敗"の場合、エラー原因によっては、突合ファイルに出力されない場合があります。
突合ファイルに取引データが出力されない例は以下となります。
・ユーザーの利用限度額超過による取引失敗
・1回の決済上限額超過による取引失敗

Sampleファイルをダウンロード

Webhookで通知されたpathからファイルを取得してください。

{
  "notification_type":"file.created",
  "notification_id": "<UUID>",
  "fileType":"transaction_recon",
  "path":"https://<server_path>/<filename>?parameters",
  "requestedAt":"<epoch time>"
}

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