Request Money (1.0)

This document will be focusing on Pending Payment APIs Merchant can send a push notification requesting payment to a specific user for whom the merchant already has a user UserAuthorizationId.

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 onboard 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 "pending_payments" 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 information provided by the request contains invalid data, e.g., unsupported currency.
400	MISSING_REQUEST_PARAMS	The set parameter is invalid.
400	UNACCEPTABLE_OP	The requested operation is not able to be processed due to the current condition, e.g., the user is suspicious.
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.

Create a pending payment

Status	Code	Description
201	SUCCESS	Success
400	DUPLICATE_REQUEST_ORDER	Request order with same payment ID exists.
400	SUSPECTED_DUPLICATE_ORDER	The same order is created multiple times.

Get payment details

Status	Code	Description
400	INVALID_PARAMS	The set parameter is invalid.
404	REQUEST_ORDER_NOT_FOUND	Request order not found

Cancel a pending order

Status	Code	Description
404	REQUEST_ORDER_NOT_FOUND	Request order not found
409	INVALID_REQUEST_ORDER_STATE	Request order not in valid state

Refund a payment

Status	Code	Description
400	UNACCEPTABLE_OP	The requested operation is not able to be processed due to the current condition. E.g. the user is suspecious.
400	CANCELED_USER	The user has canceled PayPay account.
400	THROTTLED_MULTIPLE_REFUND_REJECTED	Rejected refund request as similar request is in progress, you can retry after 1 minute.
400	REFUND_LIMIT_EXCEEDED	Order has reached maximum number of allowed refunds. This can only occur if the multiple refund feature is enabled for merchant.
400	REFUND_WINDOW_EXCEED	Refund window exceeded.
403	MERCHANT_MULTIPLE_REFUND_REJECTED	Merchant multiple refund not enabled.
404	NO_SUCH_REFUND_ORDER	The specified refund payment could not be found.
404	RESOURCE_NOT_FOUND	Order not found

Get refund details

Status	Code	Description
404	NO_SUCH_REFUND_ORDER	Refund not found

Get masked user profile

Status	Code	Message
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.

Create a pending payment

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 Create a pending payment for users who terminated by 2022/2/25,
　The error code will be "VALIDATION_FAILED_EXCEPTION".

Refund a payment

user status
terminate PayPay	user authorization expired	Deauthorization in app operation
http status:400 Code="CANCELED_USER"	http status:200 Code="SUCCESS"	http status:200 Code="SUCCESS"

This screen transition describes the display screen and screen transition in payment.

The contents of the description are as follows.

・Payment screen transition flow in PayPay application after receiving notification.

・Relationship between API Request Parameter and display screen.

Details of the flow are shown in the here.

Everything involved in the payment life cycle

If the user allows notification from the PayPay app, the following will be notified to the user.

Push Notification

Events	Category	Message（example）
Create a pending payment:API	Push notification	〇〇から5555円の支払い依頼が届きました.
Create a pending payment:API	Action bar	You have a payment request for 5555 yen from XX
On-PayPay screen payment	Push notification	取引が完了しました。 金額：1000円 取引番号：xxxxxxxxxxxxxxxxxxxx 店舗名：テスト加盟店
Refund a payment:API	Push notification	取引番号: xxxxxxxxxxxxxxxxxxxx 1000円の返金が完了しました。

Currently, push notifications and in-app notifications are only available in Japanese. There is no English version.

The basic status transition for each event and WEBHOOK notification are as follows.

Event	Before	After	Webhook Notification
Create a pending payment:API	-	CREATED	none
On-PayPay screen payment	CREATED	COMPLETED	COMPLETED
Expired payment	CREATED	EXPIRED	none
Cancel a pending order:API	CREATED	CANCELED	none
Refund a payment:API	COMPLETED	REFUNDED	none

PayPay can send webhook events that notify your application at the time when event happens on your account. To receive the notification, the client needs to set up a webhook url where we will use HTTP POST to send data to the client. Each notification event will have one notification_type field which can be used by clients to determine which event has happened. When your application receives the notification via webhook, it should respond with a HTTP 200 OK status code. Although not required, a response body with a short text description (like "OK") is recommended. With the security concerns, it is highly recommended that clients whitelist PayPay IP address to receive notifications. Please keep reading to learn for which events we currently send webhook notifications. Events related to transaction.

Events related to user state changes.

This notification is sent after the client successfuly acuqired the user's authorization.

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

This notification is sent after the client failed to acuqire after going through the user authorization flow.

{
  "notification_type": "customer.authroization.failed",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "result": "declined",  // or bad_request
  "reason": "invalid scope"
}

The result in the payload could be either declined if the the request is rejected by user, or bad_request if there are invalid info in the request.

This notification is sent after a user revoked the ever granted authorization from the PayPay app.

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

In order to ease third party account linking experience, we will increase user authorization expiry from the date of last transaction/ grant. So merchants and users will have to give authorization less often.

This notification is sent after user's authorizations is extended from PayPay side.

{
  "notification_type": "customer.authroization.extended",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "scopes": "preauth_capture_native",
  "userAuthorizationId": "xxxxx",
  "expiry": 1234567  // the authorization id expiration epoch timestamp in seconds
}

This notification will be sent after a user has been deleted.

sample event:

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

Events related to order transaction state changes.

This notification is sent after the order status changes to COMPLETED.

{
  "merchant_id": "01234567890123456789",
  "merchant_order_id": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "notification_type": "Transaction",
  "order_amount": "1000",
  "order_id": "00000111112222233333",
  "paid_at": "2020-08-07T13:58:03+09:00",
  "state": "COMPLETED"
}

This notification will be sent when the order status changes to FAILED.
Depending on the type of error, you may not be notified.

{
  "merchant_id": "01234567890123456789",
  "merchant_order_id": "01234567-89AB-CDEF-0123-456789ABCDEF",
  "notification_type": "Transaction",
  "order_amount": "1000",
  "order_id": "00000111112222233333",
  "paid_at": null,
  "state": "FAILED"
}

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

Category	Description	Note
File linkage method	Webhook
File Name	transaction_＜merchant_id＞_＜from＞_＜to＞_v2.csv
File creation unit	merchant_id
Processing cycle (JST)	Daily	Transactions from 00:00:00 to 23:59:59.
Notification time (JST)	Between 1:30 and 10:00
format	CSV
File acquisition period	2hours
File retention period	1 week	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.
character code (Contents)	Shift_JIS
character code (file name)	UTF-8
newline code	CRLF

Key	Value from	Note
Order ID	order_id	Order ID issued by PayPay.
Merchant ID	merchant_id	Merchant ID issued by PayPay.
Brand name	brandName	Brand name registered with PayPay.
Store ID	storeId	Store ID set in the request.
Store name	storeName	Store name registered with PayPay.
Terminal ID / Pos ID	terminalId	Terminal ID set in the request.
Status	"取引完了" , "取引失敗" , "返金完了" , "返金失敗"	Status of transaction data managed by PayPay
Transaction date	acceptedAt
Amount	amount	There is a minus sign for cancellation.
Receipt number	orderReceiptNumber	Receipt number
Payment method	"PayPay残高", "クレジットカード", "あと払い", "PayPayポイント"	Comma separated payment methods.
Merchant payment ID	merchantPaymentId	Merchant payment ID issued by Merchant.
Payment details	[{"paymentMethod":"PayPayポイント", "amount":5, "breakdown":[{"type":"REGULAR", "amount":5}]}, {"paymentMethod":"PayPay残高", "amount":5}]	This is the payment amount for each payment method.

Download Sample File

Get the file from the path notified by the webhook.

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

Click here for the latest FAQ.

Date of Change	Date of Release	Type of Change	Section	Updates
2023.03.30	Released	Documentation Fix	File linkage specifications	Fixed the description of Notification time.
2023.04.03	2023.06.06	Feature	Create a pending payment	Added new request and response parameter productType
2023.04.13	Released	Documentation Fix	Recon file	Added that for "Status": "取引失敗", it may not be output to the recon file depending on the cause of the error.
2023.06.16	Released	Documentation Fix	Refund a payment	Changed the description of Refund a payment.
2023.07.04	Released	Documentation Fix	Create a pending payment, Get payment details	Updated the description of metadata.
2023.07.04	Released	Documentation Fix	Create a pending payment, Get payment details	Updated the description of metadata.
2023.08.24	2023.11.13	Feature	Get payment details	Returning the payment methods used to complete order in the Get payment details api.
2023.11.15	2023.11.15	Feature	Recon file	Added PayPayポイント payment type in methodOfPayment and new column paymentDetails.
2023.12.19	TBD	Feature	Get Refund details	Added new query param paymentId for the request and updated Get Refund details api description.
2024.03.12	Released	Documentation Fix	Create a pending payment, Get payment details	Added that the metadata is obsolete.
2024.09.05	TBD	Feature	Recon file	Added breakdown to paymentDetails.
2024.10.28	Released	Documentation Fix	File linkage specifications	Updated the file name of the recon file