PayPay Open Payment API（OPA）は、様々なシナリオに対応した決済関連操作が設計されており、ユーザーへ快適な決済体験を提供します。 PayPay OPAクライアントとして登録されている場合、決済パートナーは下記の機能が使用可能になります。

• PayPayユーザーのウォレットから直接支払い金額を引き落とし、決済を完了させる
• 動的なQRコードを作成し、PayPayアプリで決済を完了させる
• スムーズな決済を行うため事前にユーザーの認可を取得し、決済フローを確立する
• PayPayキャッシャーページとWebアプリケーションを統合し、決済を完了させる
• PayPay OPAが提供する様々なAPIを使用し、独自の決済エクスペリエンスの構築

本書では、PayPay決済パートナー向けに設計したDynamic QR Code APIに焦点を当てます。

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

このフローでは、加盟店がユーザーに提示するQRコードを作成します。 その後、ユーザーはPayPayアプリを用いてQRコードをスキャンし、支払を行います。 加盟店は、APIで支払ステータスの照会や、通知機能を利用し注文の処理を行うことが可能です。 ポーリング間隔は、2〜3秒程度として下さい。

フローの詳細はこちらを参照してください。

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

• api key と apiKeySecret
• webhookの通知先となるエンドポイント
• クライアントIPのホワイトリスト
• 加盟店識別子（エージェントクライアントの場合）

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

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

本ドキュメントに記載されている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 QRCode

Delete a QRCode

Get payment details

Cancel a payment

Update a payment authorization

Capture a payment authorization

Revert a payment authorization

Refund a payment

Get refund details

推奨されるタイムアウト設定は、各APIで指定されています。 最も重要なのは、支払いタイムアウトAPIで、読み取りタイムアウト値を30秒以上で設定してください。

タイムアウトが発生した場合、不明な支払いステータスとして扱ってください。

ステータスが不明な場合、下記のいずれかの方法で対処してください。

1. 取引のステータスを照会するため、照会APIを使用してください。 PayPayで取引が失敗になっている、または存在しない場合は、元取引と同様のリクエストを再度行なってください。

2. キャンセルAPIを使用してください。 キャンセルAPIが提供されている場合は、取引をキャンセルすることもできます。 キャンセルが承認された後、元取引と同様のリクエストを再度行なってください。

決済に関して

決済APIのGetPaymentDetailsや後述のWebhook(トランザクションイベント)の結果を元に、決済結果を判定ください。

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

残高ブロックありの場合

残高ブロックなしの場合

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

残高ブロックありの場合

残高ブロックなしの場合

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

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

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

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

トランザクションのステータスが変更になった際、Webhookで通知します。

この通知は、以下の2つのケースで発生します。

1. 支払い承認が正常に作成された場合。
2. PayLater 側で制御不能な事象が発生し、支払承認の有効期限が予期せず短縮された場合（PAY_LATER_CC のオーソリにのみ適用可能）。

ケース 2 の場合、更新された有効期限がペイロードに含まれます。 マーチャントはこのようなイベントの発生後、キャプチャ失敗を回避するために適切な処理を実装する必要があります。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "state": "AUTHORIZED"
}

この通知は、ReAuthorize処理が成功した際に送信されます。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "reauth_request_id": "123456789",
  "state": "AUTHORIZED"
}

この通知は、オーダーステータスがCOMPLETEDに変わった際に送信されます。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": "2020-04-13T13:35:29Z",
  "order_amount": 12345,
  "state": "COMPLETED"
}

この通知は、オーダーステータスがCANCELEDに変わった際に送信されます。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "state": "CANCELED"
}

この通知は、オーダーステータスがEXPIREDに変わった際に送信されます。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "state": "EXPIRED"
}

この通知は、ユーザーへの増額の承認要求が期限切れとなった際に送信されます。 増額の承認要求は、リクエストから6時間後に期限切れになります。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "confirmation_expires_at": "2020-04-13T13:35:29Z",
  "order_amount": 12345,
  "reauth_request_id": "123456789",
  "state": "AUTHORIZED"
}

この通知は、残高ブロックなしかつオーダーステータスがFAILEDに変わった際に送信されます。 エラーの種類によっては通知されない場合があります。

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "order_amount": 12345,
  "state": "FAILED"
}

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

残高ブロックありの場合

残高ブロックなしの場合

残高ブロックありの場合

merchantPaymentId、acceptedAtは、transactionStatus毎に値の取得元が変わるため、下記に記載します。

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

残高ブロックなしの場合

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

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

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

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