Introduction
Merchant Top Up's provides a service that allows users topup their wallet using merchant wallet balance.
TLS implementation
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.
Onboard merchant
To start utilizing our Open Payment API platform, at first the businessneeds to be onboarded as a PayPay merchant.
This process usually consists of information collection, manualverification, contract confirmation and credentials issuance.
After becoming a merchant on PayPay, the following items would be setup forthe 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.
Acquire user authorization
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.
OPA API Authorization
Everything related to OPA API Authorization is described here.
Specify merchant in request
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.
Error Handling
PayPay OPA uses HTTP response status codes and OPA error code to indicatethe success or
failure of the requests. With these information, you can decide what errorhandling strategy
to use. In general, PayPay OPA return the following http status codes.
Response code list
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. |
Timeout
The recommended timeout setting is specified in each API. The mostimportant one is for the
payment creation api, where the read timeout should not be less than 30seconds. When timeout
happens, it should be treated as unknown payment status.
Handle unknown payment status
There are two ways to react with this situation
Use the query api to query the transaction status. If the originaltransaction was failed or not found in PayPay, you can start a new transaction for the same purpose.
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 result associated with user authorization status change
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" |
Wallet
Everything related to PayPay Wallet balance
Merchant Top up
Transfer money to user balance
Timeout: 50s
query Parameters
| agreeSimilarTransaction | string (Optional) If the parameter is set to "true", the payment duplication check will be bypassed. |
Request Body schema: application/json
CreateTopUp
| merchantTopUpId required | string (MerchantTopUpId) <= 64 characters The unique user credit transaction id provided by merchant |
| userAuthorizationId required | string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow |
required | object (MoneyAmount) |
| requestedAt required | integer (EpochTime) Epoch timestamp in seconds |
| targetAccount | string Enum: "PREPAID" "EMONEY" The user account type.If you want to put money into PREPAID account explicitly, please set "PREPAID".If you want to put money into EMONEY account explicitly, please set "EMONEY" and the user's KYC must be completed.Otherwise(targetAccount is not specified), the account will be decided depend on user's KYC status. |
| orderDescription | string <= 255 characters Description of the topup |
| metadata | object This parameter is obsolete. |
Responses
Production server
https://api.paypay.ne.jp/v2/wallet/topups
Staging server
https://stg-api.paypay.ne.jp/v2/wallet/topups
Sandbox server
https://stg-api.sandbox.paypay.ne.jp/v2/wallet/topups
Request samples
- Payload
Content type
application/json
"merchantTopUpId": "string", "userAuthorizationId": "string", "amount": { "amount": 0, "currency": "JPY" }, "requestedAt": 1704112496, "targetAccount": "PREPAID", "orderDescription": "string", "metadata": { }{
}
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", "metadata": { } }{
}
Get top up details
Get topup details
Timeout: 15s
path Parameters
| merchantTopUpId required | string (MerchantTopUpId) <= 64 characters The unique user credit transaction id provided by merchant |
Responses
Production server
https://api.paypay.ne.jp/v2/wallet/topups/{merchantTopUpId}
Staging server
https://stg-api.paypay.ne.jp/v2/wallet/topups/{merchantTopUpId}
Sandbox server
https://stg-api.sandbox.paypay.ne.jp/v2/wallet/topups/{merchantTopUpId}
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", "metadata": { } }{
}
User
Unlink user
Unlink a user from the client
Timeout: 15s
path Parameters
| userAuthorizationId required | string (UserAuthorizationId-2) <= 64 characters The PayPay user reference id returned by the user authorization flow |
Responses
Production server
https://api.paypay.ne.jp/v2/user/authorizations/{userAuthorizationId}
Staging server
https://stg-api.paypay.ne.jp/v2/user/authorizations/{userAuthorizationId}
Sandbox server
https://stg-api.sandbox.paypay.ne.jp/v2/user/authorizations/{userAuthorizationId}
Response samples
- 200
- 401
- 404
- 500
Content type
application/json
"resultInfo": { "code": "string", "message": "string", "codeId": "string" }, "data": { }{
}
Get user authorization status.
Get the authorization status of a user
Timeout: 15s
path Parameters
| userAuthorizationId required | string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow |
Responses
Production server
https://api.paypay.ne.jp/v2/user/authorizations?userAuthorizationId={userAuthorizationId}
Staging server
https://stg-api.paypay.ne.jp/v2/user/authorizations?userAuthorizationId={userAuthorizationId}
Sandbox server
https://stg-api.sandbox.paypay.ne.jp/v2/user/authorizations?userAuthorizationId={userAuthorizationId}
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 }{
}
Recon file
PayPay generates a topup file by daily processing and notifies it by Webhook.
FAQ
Click here for the latest FAQ.
Changelog
| 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. |
File linkage specifications
| 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 |
File layout
| 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
Webhook notifications
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>"}