Merchant Top Up (1.0)

はじめに

Merchant Top Upは加盟店からユーザーに残高を付与する仕組みとなります。

TLSの実装

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

加盟店を登録する

PayPay OPAの利用を開始するには、事前に定められたプロセスに従ってPayPay加盟店の登録を行なってください。

このプロセスは情報収集、手動検証、契約確認、およびクレデンシャル情報の発行から構成されます。

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

api keyとsecret
許可された認可コールバックドメイン
ユーザー認可有効期間
Webhookエンドポイント
クライアントIPホワイトリスト

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

ユーザー認可を取得する

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

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

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

API認証

OPA API認証に関わることは全て API認証のページにあります。

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

APIのリクエスト時に加盟店識別子をセットする必要があります。加盟店識別子をセットするには2つの方法があります。

クエリの中にセットする:

?assumeMerchant={MerchantId}

HTTPヘッダにセットする:

X-ASSUME-MERCHANT: {MerchantId}

両方を指定した場合、クエリにセットしたパラメーターが優先されます。

エラー処理

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

レスポンスコード一覧

各API共通レスポンスコード

Status	Code	Description
200	SUCCESS	Success
400	INVALID_REQUEST_PARAMS	リクエストにより提供された情報に無効なデータが含まれています。例: サポートされていない通貨
400	MISSING_REQUEST_PARAMS	設定されたパラメータが無効です。
401	UNAUTHORIZED	有効なapi keyとsecretが提供されていません。
401	INVALID_USER_AUTHORIZATION_ID	指定したuserAuthorizationId(PayPayのユーザー認可ID)が無効です。
401	EXPIRED_USER_AUTHORIZATION_ID	ユーザー認証IDの有効期限が切れています。
401	OP_OUT_OF_SCOPE	The operation is not permitted.
404	OPA_CLIENT_NOT_FOUND	OPAクライアントが見つかりません。
429	RATE_LIMIT	リクエスト制限数超過。
500	SERVICE_ERROR	サービスエラーが発生しました。
500	INTERNAL_SERVER_ERROR	このコードは問題が発生したことを意味しますが、トランザクションが発生したかどうか正確にはわかりません。不明な支払いステータスとして処理する必要があります。
503	MAINTENANCE_MODE	メンテナンス中です。

Merchant Top Up

Status	Code	Description
400	INVALID_PARAMS	設定されたパラメータが無効です。
400	CANCELED_USER	対象のユーザーが存在しません。
400	SUSPECTED_DUPLICATE_ORDER	同じオーダーが複数回行われています。
400	UNACCEPTABLE_OP	リクエストされた操作は現状では処理できません。例: 不審なユーザー
400	NO_SUFFICIENT_FUND	トランザクションのための十分な資金がありません。
400	KYC_NOT_COMPLETED	対象アカウントタイプ (targetAccount) がEMONEYでユーザーがKYCを完了していない場合に返されるレスポンスコードです。
400	LIMIT_EXCEEDED	トップアップ可能最大金額を超過、またはトップアップ金額がマーチャントウォレット残高を超過しています。
400	DUPLICATE_TOPUP_REQUEST	既に同一のmerchantTopupIdで異なる金額のトップアップリクエストをしています。
401	USER_STATE_IS_NOT_ACTIVE	ユーザーのステータスが非アクティブなので、リクエストを受け入れることができません。
404	RESOURCE_NOT_FOUND	アカウントが見つかりません。
500	TRANSACTION_FAILED	処理に失敗しました。

Get topup details

Status	Code	Description
404	RESOURCE_NOT_FOUND	オーダーが見つかりません。

Unlink user

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

Get user authorization status

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

タイムアウト

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

状態が不明な決済の処理

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

取引の状況を照会するには、照会APIを使用してください。 PayPayにおいて元の取引が失敗になっているか存在しない場合は、同じ取引として新しいトランザクションを開始できます。
キャンセルAPIが提供されている場合は、取引をキャンセルすることもできます。キャンセルが承認された後、同じ取引として新しいトランザクションを開始できます。

ユーザー認可のステータス変更に伴うAPI実行結果

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

Merchant Top up

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

Get user authorization status

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

API共通リクエストID

基本的に、すべてのAPIレスポンスには X-REQUEST-ID がレスポンスヘッダーとして含まれます（一部例外を除きます）。 PayPayへお問い合わせの際は、このリクエストIDをご提示ください。

フォーマット: 英数字とハイフン（最大64文字）

例:

OPA45F681001AEF4605B2A50939F611F4B8

ウォレット

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

Merchant Top up

ユーザーに残高を付与します。

Timeout: 50s

query Parameters

agreeSimilarTransaction

string

（オプション）パラメータが「true」に設定されている場合、決済重複チェックはバイパスされます。

Request Body schema: application/json

CreateTopUp

merchantTopUpId required	string (MerchantTopUpId) <= 64 characters 加盟店発番の一意のトップアップ取引ID
userAuthorizationId required	string (UserAuthorizationId) <= 64 characters ユーザー認可フローによって返却されたPayPayユーザー認可ID
required	object (MoneyAmount)
requestedAt required	integer (EpochTime) エポックタイムスタンプ（秒単位）
targetAccount	string Enum: "PREPAID" "EMONEY" 設定する残高の種別。 PayPayマネーライトを付与する場合、"PREPAID"を設定して下さい。 PayPayマネーを付与する場合、"EMONEY"を設定して下さい。ユーザーが本人確認を完了している必要があります。それ以外の場合（targetAccountが指定されていない場合）、設定する残高の種別はユーザーの本人確認ステータスにより決定されます。
orderDescription	string <= 255 characters トップアップの説明

Responses

Request samples

Payload

Content type

application/json

{"merchantTopUpId": "string",
"userAuthorizationId": "string",
"amount": {"amount": 0,
"currency": "JPY"
},
"requestedAt": 1704112496,
"targetAccount": "PREPAID",
"orderDescription": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"resultInfo": {"code": "string",
"message": "string",
"codeId": "string"
},
"data": {"topUpId": "string",
"status": "COMPLETED",
"acceptedAt": 1704112496,
"merchantTopUpId": "string",
"userAuthorizationId": "string",
"amount": {"amount": 0,
"currency": "JPY"
},
"requestedAt": 1704112496,
"targetAccount": "PREPAID",
"orderDescription": "string"
}
}

Get top up details

残高付与の詳細を取得します。

Timeout: 15s

path Parameters

merchantTopUpId

required

string (MerchantTopUpId) <= 64 characters

加盟店発番の一意のトップアップ取引ID

Responses

Response samples

200
401
404
500

Content type

application/json

{"resultInfo": {"code": "string",
"message": "string",
"codeId": "string"
},
"data": {"topUpId": "string",
"status": "COMPLETED",
"acceptedAt": 1704112496,
"merchantTopUpId": "string",
"userAuthorizationId": "string",
"amount": {"amount": 0,
"currency": "JPY"
},
"requestedAt": 1704112496,
"targetAccount": "PREPAID",
"orderDescription": "string"
}
}

ユーザー

ユーザー管理に関して

Unlink user

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

タイムアウト: 15秒

path Parameters

userAuthorizationId

required

string (UserAuthorizationId-2) <= 64 characters

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

Responses

Response samples

200
401
404
500

Content type

application/json

{"resultInfo": {"code": "string",
"message": "string",
"codeId": "string"
},
"data": { }
}

Get user authorization status

ユーザー認可状態を取得します。

Timeout: 15s

path Parameters

userAuthorizationId

required

string (UserAuthorizationId) <= 64 characters

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

Responses

Response samples

200
401
404
500

Content type

application/json

{"resultInfo": {"code": "string",
"message": "string",
"codeId": "string"
},
"data": {"userAuthorizationId": "string",
"referenceIds": ["string"
],
"status": "ACTIVE",
"scopes": ["direct_debit"
],
"expireAt": 0,
"issuedAt": 0
}
}

突合ファイル

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

突合ファイル連携仕様

Category	Description	Note
ファイル連携仕様	Webhook
ファイル名	topup_＜merchant_id＞_＜from＞_＜to＞.csv
ファイル作成単位	merchant_id
実行サイクル (JST)	毎日	00:00:00から23:59:59までの取引
通知時間 (JST)	毎日 2:00 から 10:00 の間
フォーマット	CSV
ファイル取得可能期間	2時間程度
ファイル保持期間	20日	加盟店障害などにより突合ファイルを取得できなかった場合に、PayPay側でwebhookを再送可能な期間となります。再通知をご希望の際はお問い合わせください。
文字コード（ファイル本文）	Shift_JIS
文字コード（ファイル名）	UTF-8
改行コード	CRLF

ファイルレイアウト

キー	APIで対応するフィールド	備考
topup_id	topUpId	PayPayが発行したOrder ID
merchant_topup_id	merchantTopUpId	加盟店が発行したMerchant topup ID
transaction_type	TOPUP / TOPUP_REVERSE	残高付与か付与取消かを指します。
merchant_id	merchant_id	PayPayが発行したMerchant ID
amount	amount	金額
currency	currency	"JPY"
target_account	targetAccount	加盟店が指定したtargetAccountの値。デフォルトはPREPAIDです。
requested_at	requestedAt	Topupリクエストを送信した時刻
processed_at	acceptedAt	Topupが正常に処理された時刻
state	status	出力値は"COMPLETED"固定です。残高付与を取り消した場合、「TOPUP」と「TOPUP_REVERSE」の2つのレコードが出力されます。それらのstateはCOMPLETEDです。失敗した取引は突合ファイルには出力されません。

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

Webhook通知

Webhookで通知されたパスからファイルを取得します。
なお、Webhookを再送した際、「"notification_id"」と「"path"のparameters」は都度別の値に変更されます。

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

FAQ

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

変更履歴

ドキュメント更新日	リリース日	種別	セクション	変更箇所
2023.03.24	Released	Documentation Fix	認証オブジェクトに必要なパラメータ	Request URIの説明を修正しました。
2023.07.04	Released	Documentation Fix	Merchant Top up, Get top up details	metadataの説明を修正しました。
2024.10.24	Released	Feature	Check balance for top up	新しいAPIを追加しました。
2024.12.10	Released	Document Fix	Recon File	突合ファイルのレイアウト説明を Get top up details API を参照するよう修正しました。
2025.03.04	Released	Feature	Merchant Top up, Get top up details	metadataを削除しました。
2025.09.11	TBD	Feature	Check balance for top up	APIを削除しました。