Get balance (1.0)
PayPay Open Payment APIでは、セキュリティ対策としてTLS 1.2以上の使用が必須となっております。TLS1.0およびTLS1.1では接続できませんのでご注意ください。
PayPay OPAの利用を開始するには、事前に定められたプロセスに従ってPayPay加盟店の登録を行なってください。 このプロセスは 情報収集、手動検証、契約確認、およびクレデンシャル情報の発行から構成されます。
PayPayの加盟店として登録された後、以下の項目が設定されます。
- api key と secret
- webhookの通知先となるエンドポイント
- クライアントIPのホワイトリスト
これらの設定を管理するには、マーチャントパネルを使用するか、弊社営業担当までご連絡ください。
PayPayユーザーのウォレットから決済を回収できるようにするには、ユーザーの認可を明示的に取得する必要があります。
ユーザー認可を取得する方法については、 こちら をご参照ください。
また、SCOPEには"get_balance"を指定して下さい。
OPA API認証に関わることは全て API認証のページ にあります。
PayPay OPAはhttpレスポンスステータスコードとOPAエラーコードを使用してリクエストの成功または失敗を示します。 これらの情報を使用して、どのようなエラー対応をするかを判断できます。 PayPay OPAは以下のhttpレスポンスステータスコードを返します。
400
このステータスコードは、リクエストで提供された情報を処理できないことによるエラーを示します。 以下のOPAエラーコードが返される可能性があります。
MISSING_REQUEST_PARAMS
リクエストに必要なデータが含まれていません。
INVALID_USER_AUTHORIZATION_ID
ユーザー認可IDが期限切れになったか、または取り消された場合に発生するエラーです。 クライアントはユーザー認可IDを取得するために、再度認可フローを通過する必要があります。
BAD_REQUEST
その他の場合。
401
このステータスコードは、認証エラーを示します。 以下のOPAエラーコードが返される可能性があります。
- UNAUTHORIZED
有効なapi keyとsecretがセットされていません.
- OP_OUT_OF_SCOPE
対象APIを呼び出す権限がありません。
- INVALID_USER_AUTHORIZATION_ID
指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です.
- EXPIRED_USER_AUTHORIZATION_ID
指定したuserAuthorizationId(PayPayのユーザー認可ID)が期限切れです.
404
このステータスコードは、リクエストされたリソースがシステムに存在しないことを示しています。
429
この状態コードは、クライアントが一定期間内に送信したリクエストが多すぎたため、速度制限に達したことを示します。 リクエストの送信を遅くするか、上限を引き上げるためにPayPay株式会社に連絡してください。
500
この状態コードは、PayPay側で何か問題が発生したことを示します。 下記のOPAエラーコードが返却される可能性があります。
INTERNAL_SERVER_ERROR
このコードは何かがうまくいかなかったことを意味します。 しかし、トランザクションが発生したかどうか正確にはわかりません。 状態が不明な決済として扱ってください。
502,503,504
不明な決済の失敗として扱われます。
基本的に、すべてのAPIレスポンスには X-REQUEST-ID がレスポンスヘッダーとして含まれます（一部例外を除きます）。
PayPayへお問い合わせの際は、このリクエストIDをご提示ください。
フォーマット: 英数字とハイフン（最大64文字）
例:
OPA45F681001AEF4605B2A50939F611F4B8
Get user wallet balance
ユーザーの残高を参照します。残高参照については、別途PayPay側に申請が必要となります。
Timeout: 15s
query Parameters
| userAuthorizationId required | string (UserAuthorizationId) <= 64 characters ユーザー認可フローによって返却されたPayPayユーザー認可ID |
| currency required | string Value: "JPY" |
| productType | string (ProductTypeForWalletBalance) Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT" "PAYLATER_PAYMENT_ALLOCATION" PayPayシステムのプロダクトタイプ。通常、このパラメータはオプションです。
一部の加盟店は、特定のプロダクトタイプのみの使用に制限されているため、プロダクトタイプを適切に設定する必要があります。
|
| onetimeUseCashback | string (OnetimeUseCashbackForGetBalance) Enum: "ENABLED" "DISABLED" Example: onetimeUseCashback=ENABLED NOTE: このパラメータを利用するためには 照会する残高にユーザーのPayPayポイントを含めるか否かを指定します。
例えば このパラメータが指定されていない場合はユーザーのPayPayポイント利用設定に従って計算します。 |
Responses
Response samples
- 200
- 401
- 404
- 500
{- "resultInfo": {
- "code": "string",
- "message": "string",
- "codeId": "string"
}, - "data": {
- "userAuthorizationId": "string",
- "totalBalance": {
- "amount": 0,
- "currency": "JPY"
}, - "balanceDetails": [
- {
- "account": "CASHBACK",
- "balance": {
- "amount": 0,
- "currency": "JPY"
}, - "usable": true
}
], - "preference": {
- "useCashback": false,
- "cashbackAutoInvestment": false
}
}
}Get masked user profile
マスクされたユーザーの電話番号を取得します。
query Parameters
| userAuthorizationId required | string (UserAuthorizationId) <= 64 characters ユーザー認可フローによって返却されたPayPayユーザー認可ID |
Responses
Response samples
- 200
- 401
- 404
- 500
{- "resultInfo": {
- "code": "string",
- "message": "string",
- "codeId": "string"
}, - "data": {
- "phoneNumber": "*******1234"
}
}| ドキュメント更新日 | リリース日 | 種別 | セクション | 変更箇所 |
|---|---|---|---|---|
| 2023.01.12 | 2023.01.13 | 機能 | ユーザーキャッシュバック残高の取得 | productTypeにVIRTUAL_BONUS_INVESTMENTまたはPOINTを設定した場合、ユーザーのキャッシュバック設定状況に関係なく、現在のPayPayポイントを返します。 |
| 2024.10.03 | TBD | 機能 | ユーザーキャッシュバック残高の取得 | レスポンスボディにbalanceDetailsの追加。 |
| 2024.11.05 | TBD | Feature | Get user wallet balance | CASHBACK_EXPIRABLE をaccountsから削除しました。 |
| 2024.11.18 | TBD | Feature | Get user wallet balance | Product type PAYLATER_PAYMENT_ALLOCATION を追加しました。 |