PayPayポイントAPI（旧CashbackAPIもしくは残高API） (1.1)

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

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

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

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

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

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

• api key と apiKeySecret
• 承認された認可コールバックドメイン
• ユーザー認可有効時間
• webhookの通知先となるエンドポイント
• クライアントIPのホワイトリスト
• 加盟店識別子（エージェントクライアントの場合）

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

PayPayユーザーのウォレットに残高を付与できるようにするには、ユーザーの認可を明示的に取得する必要があります。

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

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

本ドキュメントに記載されている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
202	REQUEST_ACCEPTED	Request accepted
400	INVALID_REQUEST_PARAMS	リクエストにより提供された情報に無効なデータが含まれています。例: サポートされていない通貨
401	OP_OUT_OF_SCOPE	The operation is not permitted.
400	MISSING_REQUEST_PARAMS	設定されたパラメータが無効です。
401	UNAUTHORIZED	有効なapi keyとsecretが提供されていません。
404	OPA_CLIENT_NOT_FOUND	OPAクライアントが見つかりません。
429	RATE_LIMIT	リクエスト制限数超過。
500	SERVICE_ERROR	サービスエラーが発生しました。
500	INTERNAL_SERVER_ERROR	このコードは問題が発生したことを意味します が、トランザクションが発生したかどうか 正確にはわかりません。 不明な支払いステータスとして処理する必要が あります。
503	MAINTENANCE_MODE	メンテナンス中です。

Give Cashback to User

Status	Code	Description
400	VALIDATION_FAILED_EXCEPTION	リクエストパラメータの処理で問題が発生したことを意味します。 例えば、過去にボーナス付与に失敗したリクエストと重複するmerchantCashbackIdを指定した場合も本コードになります。
400	FAILURE	トランザクションが重複しています。
401	INVALID_USER_AUTHORIZATION_ID	指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です。
401	EXPIRED_USER_AUTHORIZATION_ID	ユーザー認証IDの有効期限が切れています。
404	RESOURCE_NOT_FOUND	キャンペーンが見つかりません。
500	UNAUTHORIZED_ACCESS	リソースサーバーへの不正アクセスです。

Check Cashback Details

Status	Code	Description
200	NOT_ENOUGH_MONEY*	キャッシュバックトランザクションを完了させるのに十分なキャンペーン予算残高がありません。
200	BALANCE_OUT_OF_LIMIT*	付与対象ユーザーの残高が制限を超過します。
200	INTERNAL_SERVICE_ERROR*	キャッシュバックトランザクションの処理中に内部サービスエラーが発生しました。
404	TRANSACTION_NOT_FOUND	トランザクションが存在しません。
500	UNAUTHORIZED_ACCESS	リソースサーバーへの不正アクセスです。

*注意 : Give Cashback APIは非同期処理であり、Check Cashback Details APIを呼び出すことで加盟店がキャッシュバックトランザクションのステータスを確認することができます。 上記にあるように、一部のエラーケースでは失敗の理由をHTTPステータス200のエラーコードとして返します。詳細についてはこちらをご確認下さい

Reverse a given cashback

Status	Code	Description
400	VALIDATION_FAILED_EXCEPTION	リクエストパラメータの処理エラーまたはPayPayマネーライトのキャセルがリクエストされました。
404	TRANSACTION_NOT_FOUND	トランザクションが存在しません。
500	UNAUTHORIZED_ACCESS	リソースサーバーへの不正アクセスです。

Check Cashback Reversal Details

Status	Code	Description
404	TRANSACTION_NOT_FOUND	トランザクションが存在しません。
500	UNAUTHORIZED_ACCESS	リソースサーバーへの不正アクセスです。

Cashback Event

Status	Code	Description
200	SUCCESS	キャッシュバックの付与に成功しました。
200	NOT_ENOUGH_MONEY	キャッシュバックトランザクションを完了させるのに十分なキャンペーン予算残高がありません。
200	BALANCE_OUT_OF_LIMIT	付与対象ユーザーの残高が制限を超過します。
200	INTERNAL_SERVICE_ERROR	キャッシュバックトランザクションの処理中に内部サービスエラーが発生しました。

Get user authorization status

Status	Code	Description
400	CANCELED_USER	対象のユーザーが存在しません。
401	INVALID_USER_AUTHORIZATION_ID	指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です。

Get masked user profile

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

Unlink user

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

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

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

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

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

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

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

Get user authorization status

ユーザーの状態
ユーザー退会	ユーザー認可の有効期限切れ	アプリ操作での認可解除
http status:400 Code="CANCELED_USER"	http status:200 data.expiresAt<現在日	http status:200 data.status="inactive"

Give Cashback to User、Get masked user profile

ユーザーの状態
ユーザー退会	ユーザー認可の有効期限切れ	アプリ操作での認可解除
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までに退会したユーザーに対して上記APIを実行した場合、
　エラーコードは"VALIDATION_FAILED_EXCEPTION"となります。

マーチャントは Get user wallet balance apiのproductTypeパラメーターにPOINTを指定してリクエストすることで、ユーザーのキャッシュバック残高を確認できます。（PayPay側での設定が必要なため、ご利用を希望される場合は弊社担当までご連絡ください。）

マーチャントはCreate a payment apiのproductTypeパラメーターにPOINTを指定してリクエストすることで、ユーザーのキャッシュバック残高を使用して支払いができます。（PayPay側での設定が必要なため、ご利用を希望される場合は弊社担当までご連絡ください。）

ユーザーのウォレット残高に関して, ユーザーにキャッシュバックを提供し、キャッシュバックの詳細を確認するプロセスがここに表示されます

キャッシュバックの取り消しとキャッシュバックの取り消しの詳細の確認のプロセスは上記と同じであることに注意してください。

ユーザー管理に関して

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

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

応答がない、または大きく遅れて応答した場合、PayPayは再度通知を送信します。 これは何度か繰り返される可能性があります。

• Webhook送信時に2秒間応答がない場合はクライアント側でタイムアウト
• リトライ回数は初回を含め最大3回
• リトライのインターバルは100ms

3種類のwebhookが存在しています。具体的には下記の通りとなります。

No.	名称	目的
1	カスタマーイベント	ユーザー認可に関する通知を受け取ります。
2	キャッシュバック	ユーザーに残高を付与した場合に通知を受け取ります。
3	キャッシュバック取消	ユーザーへの残高付与を取り消した場合に通知を受け取ります。

通知内容の詳細については、以降に記載いたします。

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

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

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

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

サンプル・イベント:

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

キャッシュバックに関するイベント。

この通知は、加盟店にキャッシュバック結果を知らせるために送信されます。 リクエストボディは、Check Cashback Details APIのレスポンスボディと同じです。

{
  "resultInfo": {
    "code": "SUCCESS",
    "codeId": "08100001",
    "message": "SUCCESS"
  },
  "data": {
    "cashbackId": "12345-test10",
    "status": "SUCCESS",
    "acceptedAt": 1566278399,
    "merchantAlias": "266952919408074752",
    "merchantCashbackId": "test10",
    "userAuthorizationId": "de9f3b76-3820-4136-a54c-8068c9b7d03d",
    "amount": {
      "amount": 10,
      "currency": "JPY"
    },
    "requestedAt": 1566278399,
    "orderDescription": "Description of the order",
    "walletType": "CASHBACK",
    "metadata": {}
  }
}

キャッシュバックに失敗した場合、下記のWEBHOOKが送信されます。 エラーコードはエラーハンドリングのCashback Eventに記載しています。

{
  "resultInfo": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Not enough balance in the campaign budget to complete the cashback transaction",
    "codeId": "WAL_500017"
  },
  "data": {
    "status": "FAILURE",
    "acceptedAt": 1566278399,
    "merchantAlias": "266952919408074752",
    "amount": {
      "amount": 10,
      "currency": "JPY"
    },
    "requestedAt": 1601962499,
    "cashbackId": "12345-test10",
    "merchantCashbackId": "test10",
    "userAuthorizationId": "de9f3b76-3820-4136-a54c-8068c9b7d03d",
    "orderDescription": "Description of the order",
    "walletType": "CASHBACK",
    "metadata": {}
  }
}

この通知は、加盟店にcashback reverse結果を知らせるために送信されます。

リクエストボディは、Check Cashback Reversal Details APIの応答ボディと同じです。エラーコードはエラーハンドリングのCheck Cashback Reversal Detailsに記載しています。

{
  "resultInfo": {
    "code": "SUCCESS",
    "codeId": "08100001",
    "message": "SUCCESS"
  },
  "data": {
    "cashbackReversalId": "121904701032398848-rc_31922956-8e06-45aa-9a3a-bb6ba1e1b0d8_1_cancel",
    "status": "SUCCESS",
    "acceptedAt": 1566278399,
    "merchantAlias": "testMerchant",
    "merchantCashbackReversalId": "rc_31922956-8e06-45aa-9a3a-bb6ba1e1b0d8_1_cancel"
    "merchantCashbackId": "c_31922956-8e06-45aa-9a3a-bb6ba1e1b0d8_1",
    "userAuthorizationId": "null",
    "amount": {
      "amount": 10,
      "currency": "JPY"
    },
    "requestedAt": 1566278399,
    "reason": "reversing reason",
    "metadata": {}
  }
}

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

Category	Description	Note
ファイル連携方法	Webhook
ファイル名	cashback_＜merchant_id＞_＜from＞_＜to＞.csv
ファイル作成単位	加盟店（merchant_id）単位
実行サイクル (JST)	1日4回	それぞれ18:00-23:59、0:00-05:59, 06:00-11:59,12:00-17:59の時間帯のトランザクションが入っています。
通知時間 (JST)	右記参照	実行サイクル毎にファイルを作成し、完了後に通知する。 実行サイクルの2〜4時間後が目安ではあるが、トランザクション量によって通知時間は変動する。 ※実行サイクル単位での通知となります。 　1日分をまとめて通知することは出来ません。
フォーマット	CSV
ファイル取得可能期間	2時間程度
ファイル保持期間	1週間	加盟店障害などにより突合ファイルを取得できなかった場合に、PayPay側でwebhookを再送可能な期間となります。 再通知をご希望の際はお問い合わせください。
文字コード（ファイル本文）	UTF-8
文字コード（ファイル名）	UTF-8
改行コード	CRLF

Key	Value from	Note
merchant_cashback_id	merchantCashbackId	加盟店で採番されたmerchantCashbackId
merchant_cashback_reversal_id	merchantCashbackReversalID	Cashbackが取り消された場合のみ
cashback_id	cashback_id	PayPayで採番されたcashback_id
transaction_type		CASHBACK / CASHBACK_REVERSAL
merchant_id		PayPayで採番された加盟店ID
amount	amount	金額
currency	currency	JPY固定
wallet_type	wallet_type	CASHBACK / PREPAID
status		SUCCESS/FAILURE
expiry_date	expiryDate	expiryDateが指定されている場合のみ
order_description	orderDescription	注文の説明
requested_at	requestedAt	YYYY-MM-DDTHH:MM:SS+09:00 (UTC, ISO8601)
accepted_at	acceptedAt	YYYY-MM-DDTHH:MM:SS+09:00 (UTC, ISO8601)

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

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

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

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

ドキュメント更新日	リリース日	種別	セクション	変更箇所
2024.07.09	2024.08.01	Documentation Fix	API名称	APIの名称を「残高API」から「PayPayポイントAPI」に変更しました
2023.01.12	2023.01.13	説明	キャッシュバック残高の確認と支払い	キャッシュバック残高の確認や支払いにはPayPay側に設定変更依頼が必要であることを明記しました
2023.01.23	Released	Feature	Reverse a given cashback	merchantCashbackReversalId、merchantCashbackIdの説明を修正しました。
2023.01.23	Released	Feature	Check Cashback Reversal Details	status:ACCEPTEDの説明を修正しました。
2023.03.24	Released	Documentation Fix	認証オブジェクトに必要なパラメータ	Request URIの説明を修正しました。
2023.04.07	Released	Feature	突合ファイル連携仕様	通知時間の説明を変更しました。
2023.07.04	Released	Documentation Fix	Give Cashback to User, Check Cashback Details, Reverse a given cashback, Check Cashback Reversal Details	metadataの説明を変更しました。
2023.08.16	Released	Documentation Fix	VALIDATION_FAILED_EXCEPTIONの関する説明を修正しました。
2023.11.10	2023.11.13	Feature	merchantCashbackIdとmerchantCashbackReversalIdに使用可能な文字のバリデーションを追加しました。
2024.03.12	Released	Documentation Fix	Give Cashback to User, Check Cashback Details, Reverse a given cashback, Check Cashback Reversal Details	metadataは廃止であることを追加しました。
2024.09.17	2024.10.21	Feature	Give Cashback to User, Reverse a given cashback	requestedAtのバリデーションに関する説明を追加しました。
2024.10.08	TBD	Description	Webhook Setup	Webhookリトライに関する記述を追加