PayPay残高API (1.1)

はじめに

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

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

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

TLSの実装

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

加盟店を登録する

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

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

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

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

ユーザー認可を取得する

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

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

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

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

リクエスト時に加盟店(ブランド)を指定する

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)が無効です。
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実行結果は下記の通りとなります。他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側での設定が必要なため、ご利用を希望される場合は弊社担当までご連絡ください。)

キャッシュバック付与・取消

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

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

Give Cashback to User

ユーザーに残高の付与を行います。このAPIでは残高付与の受付のみを行い、PayPay側の非同期処理にて付与を実施しています。
付与の結果については、Check Cashback Detailsにてご確認下さい。

timeout: 30秒

Request Body schema: application/json

CreateCashback

merchantCashbackId
required
string (MerchantCashbackIdForGiveCashbackToUser) <= 64 characters

加盟店側で発行したCashbackのトランザクションを一意に特定するコード。
同じmerchantCashbackIdを指定した場合、Responseはエラーとなります。
使用可能な文字:a-z, A-Z, 0-9, -, _

userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

PayPay内でユーザーを識別するID。

required
object (MoneyAmount)
requestedAt
required
integer (EpochTime)

エポックタイムスタンプ(秒単位)

orderDescription
string <= 255 characters

注文の説明

walletType
string
Enum: "CASHBACK" "PREPAID"

ユーザーに付与する残高種別を指定する。
CASHBACK:PayPayポイント
PREPAID:PayPayマネーライト
省略時はCASHBACKが設定されます。

metadata
object

このパラメータは廃止となりました。
下位互換性のために項目が残されていますが、将来のリリースでは削除される予定です。

Responses

Request samples

Content type
application/json
{
  • "merchantCashbackId": "string",
  • "userAuthorizationId": "string",
  • "amount": {
    },
  • "requestedAt": 0,
  • "orderDescription": "string",
  • "walletType": "CASHBACK",
  • "metadata": { }
}

Response samples

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

Check Cashback Details

付与されたCashbackのトランザクションの状態を参照します

timeout: 10秒

Responses

Response samples

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

Reverse a given cashback

ユーザーに付与されたCashbackをキャンセルします。
キャンセルの受付のみを行い、PayPay側の非同期処理にて付与のキャンセルを実施しています。
PayPayポイントのキャンセルのみが許可され、PayPayマネーライトはキャンセルできません。
キャンセルの結果については、Check Cashback Reversal Detailsにてご確認下さい。

timeout: 40秒

Request Body schema: application/json

CreateCashbackReversal

merchantCashbackReversalId
required
string (MerchantCashbackReversalId) <= 64 characters

Cashbackをキャンセルする際に、加盟店側で発行したCashbackのトランザクションを一意に特定するコード。
同じmerchantCashbackReversalIdを指定した場合、Responseはエラーとなります。
使用可能な文字:a-z, A-Z, 0-9, -, _

merchantCashbackId
required
string (MerchantCashbackIdForReverseAGivenCashback) <= 64 characters

加盟店側で発行したCashbackのトランザクションを一意に特定するコード。
使用可能な文字:a-z, A-Z, 0-9, -, _

required
object (MoneyAmount)
requestedAt
required
integer (EpochTime)

エポックタイムスタンプ(秒単位)

reason
string <= 255 characters

Cashback がキャンセルされた理由

metadata
object

このパラメータは廃止となりました。
下位互換性のために項目が残されていますが、将来のリリースでは削除される予定です。

Responses

Request samples

Content type
application/json
{
  • "merchantCashbackReversalId": "string",
  • "merchantCashbackId": "string",
  • "amount": {
    },
  • "requestedAt": 0,
  • "reason": "string",
  • "metadata": { }
}

Response samples

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

Check Cashback Reversal Details

Cashbackのキャンセルトランザクションの状態を参照します

timeout: 10秒

Responses

Response samples

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

ユーザーステータス

ユーザー管理に関して

Get user authorization status

ユーザーから認可を得ている情報を参照します

Timeout: 15s

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

PayPay内でユーザーを識別するID。

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": {
    }
}

Unlink user

クライアントからユーザーのリンクを解除します。

Timeout: 15s

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

PayPay内でユーザーを識別するID。

Responses

Response samples

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

Webhookの設定

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

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

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

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

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

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

カスタマーイベント

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

customer.authroization.succeeded

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

{
  "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
}

customer.authroization.failed

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

{
  "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(不正な要求)のいずれかになります。

customer.authroization.revoked

この通知は、ユーザーがPayPayアプリから、認可を取り消した場合に送信されます。

{
  "notification_type": "customer.authroization.revoked",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "userAuthorizationId": "xxxxx",
  "referenceId": "yyyy"
}

customer.authroization.extended

この通知は、ユーザー認可の期限がPayPayによって延長された場合に送信されます。

支払いの実施/認可の取得をした場合にユーザー認可の期限を延長します。 これにより、ユーザー操作による認可の取得を減らすことができるため、ユーザーへの負担を減らすことができます。

{
    "notification_type": "customer.authroization.extended",
    "notification_id": "evt_aXnbdeFt2Ke",
    "createdAt": "1349654313",
    "scopes": "cashback",
    "userAuthorizationId": "xxxxx",
    "expiry": 1234567  // 秒単位の認証ID有効期限エポックタイムスタンプ
}

customer.authroization.canceled

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

サンプル・イベント:

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

キャッシュバックイベント

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

give cashback

この通知は、加盟店にキャッシュバック結果を知らせるために送信されます。 リクエストボディは、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": {}
  }
}

reverse cashback

この通知は、加盟店に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での通知

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

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

FAQ

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

変更履歴

ドキュメント更新日 リリース日 種別 セクション 変更箇所
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 merchantCashbackIdmerchantCashbackReversalIdに使用可能な文字のバリデーションを追加しました。
2024.03.12 Released Documentation Fix Give Cashback to User, Check Cashback Details, Reverse a given cashback, Check Cashback Reversal Details metadataは廃止であることを追加しました。