Get balance (1.0)

はじめに

ユーザーのウォレットの合計残高を取得するためのAPIです。

TLSの実装

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

加盟店を登録する

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

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

  • api key と secret
  • webhookの通知先となるエンドポイント
  • クライアントIPのホワイトリスト

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

ユーザー認可を取得する

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

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

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

API認証

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

HMAC authヘッダーの生成ステップ

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とヘッダーで渡ってきた値が一致しているかを検証します。

エラー処理

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

HTTP 2xx

200

すべてが期待通りに動作しています。

HTTP 4xx

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株式会社に連絡してください。

HTTP 5xx

500

この状態コードは、PayPay側で何か問題が発生したことを示します。 下記のOPAエラーコードが返却される可能性があります。

  • INTERNAL_SERVER_ERROR

    このコードは何かがうまくいかなかったことを意味します。 しかし、トランザクションが発生したかどうか正確にはわかりません。 状態が不明な決済として扱ってください。

502,503,504

不明な決済の失敗として扱われます。

ウォレット

ユーザーのウォレット残高に関して

Get user wallet balance

ユーザーの残高を参照します。残高参照については、別途PayPay側に申請が必要となります。

Timeout: 15s

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

ユーザー認可フローによって返却されたPayPayユーザー認可ID

currency
required
string
Value: "JPY"
productType
string
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT"

PayPayシステムのプロダクトタイプ。 特定の加盟店以外はこのパラメータはオプションです。 特定のプロダクトタイプのみを使用するよう制限されている一部の加盟店の場合、プロダクトタイプを適切に設定する必要があります。
productTypeにVIRTUAL_BONUS_INVESTMENTまたはPOINTを設定した場合、ユーザーのキャッシュバック設定状況に関係なく、現在のPayPayポイントを返します。

onetimeUseCashback
string
Enum: "ENABLED" "DISABLED"
Example: onetimeUseCashback=ENABLED

NOTE: このパラメータを利用するためにはonetime_use_cashbackスコープが必要です。

照会する残高にユーザーのPayPayポイントを含めるか否かを指定します。 例えば"ENABLED"を指定した場合、ユーザーのPayPayポイント利用設定が「貯める」となっていた場合でもPayPayポイントを含めた残高で計算します。 同様に"DISABLED"を指定した場合、ユーザーのPayPayポイント利用設定が「支払いに使う」となっていた場合でもPayPayポイントを除いた残高で計算します。 ただし、設定が「ポイント運用に自動追加」の場合はこのパラメータは無視されます。

このパラメータが指定されていない場合はユーザーのPayPayポイント利用設定に従って計算します。

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

ユーザー

Get masked user profile

マスクされたユーザーの電話番号を取得します。

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

ユーザー認可フローによって返却されたPayPayユーザー認可ID

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

変更履歴

ドキュメント更新日 リリース日 種別 セクション 変更箇所
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から削除しました。