PayPay Open Payment APIでは、セキュリティ対策としてTLS 1.2以上の使用が必須となっております。TLS1.0およびTLS1.1では接続できませんのでご注意ください。
PayPay OPAの利用を開始するには、事前に定められたプロセスに従ってPayPay加盟店の登録を行なってください。 このプロセスは 情報収集、手動検証、契約確認、およびクレデンシャル情報の発行から構成されます。
PayPayの加盟店として登録された後、以下の項目が設定されます。
これらの設定を管理するには、マーチャントパネルを使用するか、弊社営業担当までご連絡ください。
PayPayユーザーのウォレットから決済を回収できるようにするには、ユーザーの認可を明示的に取得する必要があります。
ユーザー認可を取得する方法については、 こちら をご参照ください。
また、SCOPEには"get_balance"を指定して下さい。
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とヘッダーで渡ってきた値が一致しているかを検証します。
PayPay OPAはhttpレスポンスステータスコードとOPAエラーコードを使用してリクエストの成功または失敗を示します。 これらの情報を使用して、どのようなエラー対応をするかを判断できます。 PayPay OPAは以下のhttpレスポンスステータスコードを返します。
このステータスコードは、リクエストで提供された情報を処理できないことによるエラーを示します。 以下のOPAエラーコードが返される可能性があります。
MISSING_REQUEST_PARAMS
リクエストに必要なデータが含まれていません。
INVALID_USER_AUTHORIZATION_ID
ユーザー認可IDが期限切れになったか、または取り消された場合に発生するエラーです。 クライアントはユーザー認可IDを取得するために、再度認可フローを通過する必要があります。
BAD_REQUEST
その他の場合。
このステータスコードは、認証エラーを示します。 以下のOPAエラーコードが返される可能性があります。
有効なapi keyとsecretがセットされていません.
対象APIを呼び出す権限がありません。
指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です.
指定したuserAuthorizationId(PayPayのユーザー認可ID)が期限切れです.
このステータスコードは、リクエストされたリソースがシステムに存在しないことを示しています。
この状態コードは、クライアントが一定期間内に送信したリクエストが多すぎたため、速度制限に達したことを示します。 リクエストの送信を遅くするか、上限を引き上げるためにPayPay株式会社に連絡してください。
この状態コードは、PayPay側で何か問題が発生したことを示します。 下記のOPAエラーコードが返却される可能性があります。
INTERNAL_SERVER_ERROR
このコードは何かがうまくいかなかったことを意味します。 しかし、トランザクションが発生したかどうか正確にはわかりません。 状態が不明な決済として扱ってください。
不明な決済の失敗として扱われます。
ユーザーの残高を参照します。残高参照については、別途PayPay側に申請が必要となります。
Timeout: 15s
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システムのプロダクトタイプ。
特定の加盟店以外はこのパラメータはオプションです。
特定のプロダクトタイプのみを使用するよう制限されている一部の加盟店の場合、プロダクトタイプを適切に設定する必要があります。
|
onetimeUseCashback | string Enum: "ENABLED" "DISABLED" Example: onetimeUseCashback=ENABLED NOTE: このパラメータを利用するためには 照会する残高にユーザーのPayPayポイントを含めるか否かを指定します。
例えば このパラメータが指定されていない場合はユーザーのPayPayポイント利用設定に従って計算します。 |
{- "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
}
}
}
マスクされたユーザーの電話番号を取得します。
userAuthorizationId required | string (UserAuthorizationId) <= 64 characters ユーザー認可フローによって返却されたPayPayユーザー認可ID |
{- "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から削除しました。 |