支払リクエスト (1.0)

このドキュメントでは、Pending Payment APIについて記載しています。 OPAクライアントは、事前に認可IDを取得しているユーザーに対して、支払いを求める通知を送信します。

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

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

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

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

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

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

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

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

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

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

Value	Description	Example
API Key	PayPayから発行されたAPI Key	APIKeyGenerated
API Key secret	PayPayから発行されたAPI Key secret	APIKeySecretGenerated
Request URI	リクエストURL path	/v2/codes
Request method	HTTPメソッド	POST
Epoch	現在のエポックタイムスタンプ（秒単位）, Note : サーバー時刻との差が2分未満である必要があります。	1579843452
Nonce	ランダムに生成された文字列。 Note : 任意の文字列、length 8を推奨。	acd028
Request body	リクエストで渡されるbody。	{"sampleRequestBodyKey1":"sampleRequestBodyValue1","sampleRequestBodyKey2":"sampleRequestBodyValue2"}
Request content type	リクエストヘッダーで渡されるコンテンツタイプ。	application/json;charset=UTF-8;
hash (MD5(Request body, Request content type))	リクエストの本文とコンテンツタイプのハッシュ。以下に記載されているStep1で生成されます。	1j0FnY4flNp5CtIKa7x9MQ==

これらから生成されるサンプル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共通レスポンスコード

Status	Code	Description
200	SUCCESS	Success
400	INVALID_REQUEST_PARAMS	リクエストにより提供された情報に無効なデータが含まれています。例: サポートされていない通貨
400	MISSING_REQUEST_PARAMS	設定されたパラメータが無効です。
400	UNACCEPTABLE_OP	リクエストされた操作は現状では処理できません。例: 不審なユーザー
401	UNAUTHORIZED	有効なapi keyとsecretが提供されていません。
401	INVALID_USER_AUTHORIZATION_ID	指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です。
401	EXPIRED_USER_AUTHORIZATION_ID	ユーザー認証IDの有効期限が切れています。
401	OP_OUT_OF_SCOPE	The operation is not permitted.
404	OPA_CLIENT_NOT_FOUND	OPAクライアントが見つかりません。
429	RATE_LIMIT	リクエスト制限数超過。
500	SERVICE_ERROR	サービスエラーが発生しました。
500	INTERNAL_SERVER_ERROR	このコードは問題が発生したことを意味しますが、トランザクションが発生したかどうか正確にはわかりません。不明な支払いステータスとして処理する必要があります。
503	MAINTENANCE_MODE	メンテナンス中です。

Create a pending payment

Status	Code	Description
201	SUCCESS	Success
400	DUPLICATE_REQUEST_ORDER	同じ決済IDのrequest orderが存在します。
400	SUSPECTED_DUPLICATE_ORDER	同じオーダーが複数回行われています。

Get payment details

Status	Code	Description
400	INVALID_PARAMS	設定されたパラメータが無効です。
404	REQUEST_ORDER_NOT_FOUND	取引が存在しません。

Cancel a pending order

Status	Code	Description
404	REQUEST_ORDER_NOT_FOUND	取引が存在しません。
409	INVALID_REQUEST_ORDER_STATE	Request orderが無効な状態です。

Refund a payment

Status	Code	Description
400	UNACCEPTABLE_OP	リクエストされた操作は現状では処理できません。例: 不審なユーザー
400	CANCELED_USER	対象のユーザーが存在しません。
400	THROTTLED_MULTIPLE_REFUND_REJECTED	同様の処理が進行中のため、返金リクエストが拒否されました。1分後にリトライできます。
400	REFUND_LIMIT_EXCEEDED	返金の最大数に達しているため、処理できません。加盟店の複数回返金機能が有効化されている場合にのみ発生する可能性があります。
400	REFUND_WINDOW_EXCEED	返金可能な期間を超過しています。
401	USER_STATE_IS_NOT_ACTIVE	ユーザーのステータスが非アクティブなので、 リクエストを受け入れることができません。
403	MERCHANT_MULTIPLE_REFUND_REJECTED	加盟店の複数回返金機能が有効化されていません。
404	NO_SUCH_REFUND_ORDER	対象の返金が存在しません。
404	RESOURCE_NOT_FOUND	オーダーが見つかりません。

Get refund details

Status	Code	Description
404	NO_SUCH_REFUND_ORDER	対象の返金が存在しません。

Get masked user profile

Status	Code	Message
401	INVALID_USER_AUTHORIZATION_ID	指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です。

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

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

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

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

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

Create a pending payment

ユーザーの状態
ユーザー退会	ユーザー認可の有効期限切れ	アプリ操作での認可解除
http status:401 Code="INVALID_USER_AUTHORIZATION_ID"	http status:401 Code="EXPIRED_USER_AUTHORIZATION_ID"	http status:401 Code="INVALID_USER_AUTHORIZATION_ID"

※2022/2/25までに退会したユーザーに対してCreate a pending paymentを実行した場合、
　エラーコードは"VALIDATION_FAILED_EXCEPTION"となります。

Refund a payment

ユーザーの状態
ユーザー退会	ユーザー認可の有効期限切れ	アプリ操作での認可解除
http status:400 Code="CANCELED_USER"	http status:200 Code="SUCCESS"	http status:200 Code="SUCCESS"

この画面遷移は、決済における表示画面と画面遷移について記載しています。

記載の内容は以下となります。

・通知受信後のPayPayアプリにおける決済画面遷移フロー

・APIのRequest Parameterと表示画面のマッピング

詳細はこちらをご覧ください。

決済に関して

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

Push通知

イベント	カテゴリ	メッセージ（例）
Create a pending payment:API	Push通知	〇〇から5555円の支払い依頼が届きました.
Create a pending payment:API	アクションバー	〇〇から5555円の支払い依頼が届きました
PayPay画面での決済処理	Push通知	取引が完了しました。 金額：1000円 取引番号：xxxxxxxxxxxxxxxxxxxx 店舗名：テスト加盟店
Refund a payment:API	Push通知	取引番号: xxxxxxxxxxxxxxxxxxxx 1000円の返金が完了しました。

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

実施処理	実施前	実施後	WEBHOOK通知
Create a pending payment:API	-	CREATED	無し
PayPay画面での決済処理	CREATED	COMPLETED	COMPLETED
有効期限を超過	CREATED	EXPIRED	無し
Cancel a pending order:API	CREATED	CANCELED	無し
Refund a payment:API	COMPLETED	REFUNDED	無し

PayPayはアカウントでイベントが発生した際に、Webhookで通知を行います。
どのイベントが発生したかは 通知データのnotification_typeフィールドで確認できます。
通知を受信するためには、Webhook URLを設定する必要があります。

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

セキュリティ上の問題から、通知受信において、クライアントによるPayPay IPアドレスのホワイトリスト登録を強く推奨します。 現在Webhookに送信されている通知について、以下もご一読ください。

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

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

{
  "notification_type": "customer.authroization.succeeded",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "scopes": "direct_debit",
  "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": "pending_payments",
    "userAuthorizationId": "xxxxx",
    "expiry": 1234567  // 秒単位の認証ID有効期限エポックタイムスタンプ
}

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

サンプル・イベント:

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

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

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

{
  "merchant_id": "01234567890123456789",
  "merchant_order_id": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "notification_type": "Transaction",
  "order_amount": "1000",
  "order_id": "00000111112222233333",
  "paid_at": "2020-08-07T13:58:03+09:00",
  "state": "COMPLETED"
}

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

{
  "merchant_id": "01234567890123456789",
  "merchant_order_id": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "notification_type": "Transaction",
  "order_amount": "1000",
  "order_id": "00000111112222233333",
  "paid_at": null,
  "state": "FAILED"
}

PayPayでは取引明細ファイル（突合ファイル）を日次の処理で生成し、Webhookで通知します。

Category	Description	Note
ファイル連携方法	Webhook
ファイル名	transaction_＜merchant_id＞_＜from＞_＜to＞.csv
ファイル作成単位	加盟店（merchant_id）単位
実行サイクル (JST)	日次処理	PayPay側の取引日時が作成対象日の 00:00:00 – 23:59:59 の範囲
通知時間 (JST)	毎日 1:30 から 10:00 の間
フォーマット	CSV
ファイル取得可能期間	2時間程度
ファイル保持期間	1週間	加盟店障害などにより突合ファイルを取得できなかった場合に、PayPay側でwebhookを再送可能な期間となります。 再通知をご希望の際はお問い合わせください。
文字コード（ファイル本文）	Shift_JIS
文字コード（ファイル名）	UTF-8
改行コード	CRLF

Key	Value from	Note
決済番号	order_id	PayPayで採番された決済番号
加盟店ID	merchant_id	PayPayで採番された加盟店ID
屋号	brandName	PayPayで管理しているブランド名
店舗ID	storeId	リクエスト時にセットされたstoreId
店舗名	storeName	PayPayで管理している店舗名
端末番号 / Pos ID	terminalId	リクエスト時にセットされたterminalId
取引ステータス	"取引完了", "取引失敗", "返金完了", "返金失敗"	PayPayで管理している取引データのステータス
取引日時	acceptedAt
取引金額	amount	取消の場合はマイナス記号あり
レシート番号	orderReceiptNumber	レシート番号
支払い方法	"PayPay残高", "クレジットカード", "あと払い", "PayPayポイント"	カンマ区切りの支払い方法。
マーチャント決済ID	merchantPaymentId	加盟店で採番された決済番号
支払い詳細	[{"paymentMethod":"PayPayポイント", "amount":5, "breakdown":[{"type":"REGULAR", "amount":5}]}, {"paymentMethod":"PayPay残高", "amount":5}]	支払い方法ごとの支払い金額です。

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

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

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

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

ドキュメント更新日	リリース日	種別	セクション	変更箇所
2023.03.30	Released	Documentation Fix	突合ファイル連携仕様	通知時間の説明を修正しました。
2023.04.03	2023.06.06	Feature	Create a pending payment	リクエストパラメータとレスポンスパラメータ productType を追加しました。
2023.04.13	Released	Documentation Fix	突合ファイル	取引ステータス："取引失敗"の場合、エラー原因によっては、突合ファイルに出力されない場合があることを追加しました。
2023.06.16	Released	Documentation Fix	Refund a payment	Refund a paymentの説明を変更しました。
2023.07.04	Released	Documentation Fix	Create a pending payment, Get payment details	metadataの説明を変更しました。
2023.08.24	2023.11.13	Feature	Get payment details	支払い詳細の取得 API で注文を完了するために使用された支払い方法を返します。
2023.11.15	2023.11.15	Feature	Recon file	MethodOfPayment に支払いタイプ「POINT」を追加し、新しい列「paymentDetails」を追加しました。
2023.12.19	TBD	Feature	Get Refund details	リクエストのクエリパラメータ paymentId を追加し、説明を更新しました。
2024.03.12	Released	Documentation Fix	Create a pending payment, Get payment details	metadataは廃止であることを追加しました。
2024.09.05	TBD	Feature	Recon file	breakdown を paymentDetails に追加しました。