Merchant Top Up's provides a service that allows users topup their wallet using merchant wallet balance.

The PayPay Open Payment API requires that you use TLS 1.2 or higher as a security measure. Note that you cannot connect with TLS1.0 and TLS1.1.

To start utilizing our Open Payment API platform, at first the business needs to be onboarded as a PayPay merchant.

This process usually consists of information collection, manual verification, contract confirmation and credentials issuance.

After becoming a merchant on PayPay, the following items would be setup for the client:

• api key and secret
• allowed authorization callback domains
• user authorization validity time
• webhook endpoints
• client IP whitelist

This setup can be managed using our merchant panel/ getting in touch with the sales representative.

To be able to collect payment from PayPay user’s wallet, you need to obtain user’s authorization explicitly.

Acquiring user authorization can be achieved using our simple account linking flow here.

Specify "merchant_topup" for SCOPE.

Everything related to OPA API Authorization is described here.

Every time an API is called, the merchant identifier needs to be passed along with the request. There are two ways to pass the merchant identifier:

In a query string parameter:

?assumeMerchant={MerchantId}

Or in HTTP headers:

X-ASSUME-MERCHANT: {MerchantId}

If both are provided, the query string parameter would take precedence.

PayPay OPA uses HTTP response status codes and OPA error code to indicate the success or

failure of the requests. With these information, you can decide what error handling strategy

to use. In general, PayPay OPA return the following http status codes.

Common response code

Status	Code	Description
200	SUCCESS	Success
400	INVALID_REQUEST_PARAMS	The infomation provided by the request contains invalid data, e.g., unsupported currency.
400	MISSING_REQUEST_PARAMS	The set parameter is invalid.
401	UNAUTHORIZED	No valid api key and secret provided
401	INVALID_USER_AUTHORIZATION_ID	The specified user authorization ID is invalid.
401	EXPIRED_USER_AUTHORIZATION_ID	The user authorization ID expired
401	OP_OUT_OF_SCOPE	The operation is not permitted.
404	OPA_CLIENT_NOT_FOUND	OPA Client not found
429	RATE_LIMIT	Too many requests
500	SERVICE_ERROR	A service error has occurred.
500	INTERNAL_SERVER_ERROR	This code indicates that something went wrong, but we don't know exactly if the transaction has happened or not. It should be treated as unknown payment status.
503	MAINTENANCE_MODE	Sorry, we are down for scheduled maintenance.

Merchant Top Up

Status	Code	Description
400	INVALID_PARAMS	The set parameter is invalid.
400	CANCELED_USER	Canceled user
400	SUSPECTED_DUPLICATE_ORDER	The same order is created multiple times.
400	UNACCEPTABLE_OP	The requested operation is not able to be processed due to the current condition, e.g., the user is suspecious.
400	USER_STATE_IS_NOT_ACTIVE	The request cannot be accepted because the user status is inactive.
400	NO_SUFFICIENT_FUND	There is no sufficient fund for the transaction.
400	KYC_NOT_COMPLETED	This is returned if user has not completed KYC in case of target account type (targetAccount) EMONEY.
400	LIMIT_EXCEEDED	This is returned when the topup amount is not under the limit or merchant wallet balance exceeded.
400	DUPLICATE_TOPUP_REQUEST	This is returned when there is a topup request of same merchantTopupId with different amount.
404	RESOURCE_NOT_FOUND	Account not found
500	TRANSACTION_FAILED	Transaction failed

Get topup details

Status	Code	Description
404	RESOURCE_NOT_FOUND	Order not found

Unlink user

Status	Code	Description
401	INVALID_USER_AUTHORIZATION_ID	The specified user authorization ID is invalid.

Get user authorization status

Status	Code	Description
400	CANCELED_USER	The user has canceled their PayPay account.
401	INVALID_USER_AUTHORIZATION_ID	The specified user authorization ID is invalid.

The recommended timeout setting is specified in each API. The most important one is for the

payment creation api, where the read timeout should not be less than 30 seconds. When timeout

happens, it should be treated as unknown payment status.

There are two ways to react with this situation

1. Use the query api to query the transaction status. If the original transaction was failed or not found in PayPay, you can start a new transaction for the same purpose.

2. Or, you can cancel the transaction, if the cancel api is provided. After the cancellation is accepted, you can start a new transaction for the same purpose.

API execution may fail due to user authorization status change. The assumed user status and the corresponding API execution results are as follows. In other APIs, no error occurs due to status change.

Merchant Top up

user status
terminate PayPay	user authorization expired	Deauthorization in app operation
http status:401 Code="INVALID_USER_AUTHORIZATION_ID"	http status:401 Code="EXPIRED_USER_AUTHORIZATION_ID"	http status:401 Code="INVALID_USER_AUTHORIZATION_ID"

*If you execute Merchant Top up for users who terminated by 2022/2/25,
　The error code will be "VALIDATION_FAILED_EXCEPTION".

Get user authorization status

user status
terminate PayPay	user authorization expired	Deauthorization in app operation
http status:400 Code="CANCELED_USER"	http status:200 data.expiresAt < current date	http status:200 data.status="inactive"

Everything related to PayPay Wallet balance

PayPay generates a topup file by daily processing and notifies it by Webhook.

Click here for the latest FAQ.

Date of Documentation Update	Date of Release	Type of Change	Section	Updates
2023.07.04	Released	Documentation Fix	Merchant Top up, Get top up details	Updated the description of metadata.
2024.03.12	Released	Documentation Fix	Merchant Top up, Get top up details	Added that the metadata is obsolete.

Category	Description	Note
File linkage method	Webhook
File Name	topup_＜merchant_id＞_＜from＞_＜to＞.csv
File creation unit	merchant_id
Processing cycle (JST)	Daily	Transactions from 00:00:00 to 23:59:59.
Notification time (JST)	Between 2:00 and 10:00
format	CSV
File retention period	20 days	If the recon file cannot be obtained due to a merchant failure, etc., PayPay will be able to resend the webhook. Please contact us if you would like to be notified again.
File acquisition period	2hours
character code（Contents）	Shift_JIS
character code（file name）	UTF-8
newline code	CRLF

Key	Value from	Note
topup_id	order_id	Order ID issued by PayPay.
merchant_topup_id	merchantTopUpId	Merchant topup id issued by Merchant.
transaction_type	TOPUP / TOPUP_REVERSE	Transactions success and reversed types
merchant_id	merchant_id	Merchant ID issued by PayPay.
amount	amount	Topup amount
currency	currency	JPY
target_account	target_account	target_account specified by merchant, default PREPAID.
requested_at	requested_at	topup requested time
processed_at	paidAt	Topup processed time successfully
state	state	COMPLETED. For reversed transactions, there will be two records in the file, TOPUP and TOPUP_REVERSE, the state of both is COMPLETED. Failed topup transactions are not included in recon file

Download Sample File

Get the file from the path notified by the webhook.

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