PreAuth & Capture (1.0)

Many of our merchants need to block money in the users wallet which is captured later. These include Ondemand taxi's, on-demand services, ecommerce websites, etc. The goal here is to ensure the merchant can block the money at the time of creating an order and take the money at the time of fulfilling the order thereby reducing the risk in the system.

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.

Access from users to the PayPay app and PayPay web screen from outside Japan is restricted. Please contact us for details.

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.

Set "preauth_capture_native" for SCOPE. Specify "preauth_capture_native, get_balance" only when using Get user wallet balance.

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
401	OP_OUT_OF_SCOPE	The operation is not permitted.
400	MISSING_REQUEST_PARAMS	The set parameter is invalid.
401	UNAUTHORIZED	No valid api key and secret provided
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 payment authorization

Status	Code	Description
400	CANCELED_USER	Canceled user
400	INVALID_PARAMS	Invalid parameters received
400	NO_SUFFICIENT_FUND	The user's balance is insufficient to make payment.
400	UNSUPPORTED_PAYMENT_METHOD	Payment method is not supported.
400	PRE_AUTH_CAPTURE_UNSUPPORTED_MERCHANT	Merchant does not support Pre-Auth-Capture.
400	PRE_AUTH_CAPTURE_INVALID_EXPIRY_DATE	Provided Expiry Date is above the allowed limit of Max allowed expiry days.
400	NO_SUFFICIENT_FUND	No sufficient fund
400	SUSPECTED_DUPLICATE_PAYMENT	If a merchant tries collect same amount money from same user again within 5 minutes, the request would be rejected with this very error code. This design is mainly to prevent the duplicated payments which are usually caused by design flaws in client code. However, sometimes, the merchant would intentionally collect multiple same amount payments from a single user. In such case, the client need to send a specific parameter in order to bypass the duplication check. This is detailed in the payment creation api spec.
400	UNACCEPTABLE_OP	The requested operation is not able to be processed due to the current condition, e.g., the user is suspicious.
400	LIMIT_EXCEEDED	The payment amount exceeded upper limit.
400	USER_DEFINED_DAILY_LIMIT_EXCEEDED	The payment amount exceeded user 24 hours defined limit.
400	USER_DEFINED_MONTHLY_LIMIT_EXCEEDED	The payment amount exceeded user 30 days defined limit.
400	USER_DAILY_LIMIT_FOR_MERCHANT_EXCEEDED	Payment amount exceeded merchant defined restriction.
401	USER_STATE_IS_NOT_ACTIVE	Inactive user
401	INVALID_USER_AUTHORIZATION_ID	If the user authorization id is expired or revoked by the use. The client need to go through the authorization flow again to get the user authorization id
401	EXPIRED_USER_AUTHORIZATION_ID	The user authorization ID expired
404	NO_VALID_PAYMENT_METHOD	No available payment method
404	PAYMENT_METHOD_NOT_FOUND	Payment method not found
500	TRANSACTION_FAILED	This code means the transaction is failed in PayPay side. You can create new transaction for the same purpose with reasonable backoff time.

Below error could occur if merchant requires user to be KYCed but the user hasn't completed KYC

Status	Code	Description
400	NON_KYC_USER	User has not completed KYC.

Below are some additional errors which can occur if the payment method is PAY_LATER_CC or CREDIT_CARD.

Status	Code	Description
400	CC_LIMIT_EXCEEDED	The credit card limit is exceeded.
400	PPC_BAD_REQUEST	The PayPay card process be issued something error.
400	PPC_EXPIRED	PayPay card is expired.
400	PPC_LIMIT_EXCEEDED	PayPay card limit is exceeded.
429	INTERNAL_SERVICE_RATE_LIMIT	Too many requests. The client has sent too many requests in a given amount of time for the payment method that depends on external system outside PayPay, e.g. when the payment method type is PAY_LATER_CC or CREDIT_CARD. In case of this error, since the transaction already failed in PayPay, the client need to specify a new merchantPaymentId and retry later.

Cancel a payment authorization

Status	Code	Description
400	ORDER_NOT_REVERSIBLE	This code is returned in the following cases: 1) If the status of the target order is REFUNDED, EXPIRED, COMPLETED, or CANCELED. This error code will not be returned for anything other than shipping sales, even if the order status is COMPLETED. 2) If the cancellation window has passed.

Update a payment authorization

Status	Code	Description
201	USER_CONFIRMATION_REQUIRED	When higher amount reauthorize is initiated successfully.
400	REAUTHORIZE_REJECTED	1. When the order state is not AUTHORIZED 2. When the order type is not supported 3. When paymentMethod is not supported 4. When idempotent response is initiated
400	PAY_METHOD_INVALIDATED	When paymentMethod is no longer valid. User should be guided to use a different paymentMethod.
400	REAUTH_AMOUNT_UNCHANGED	When the amount of reauthorize is the same as the amount during authorization
400	REAUTH_MAX_LIMIT_EXCEEDED	Maximum number of reauthorize attempts exceeded. The maximum number of attempts is set to be 10(ten) times.
400	REAUTHORIZE_FAILED	When the order state is failed to be updated
404	RESOURCE_NOT_FOUND	Order does not exist

Capture a payment authorization

Status	Code	Description
202	USER_CONFIRMATION_REQUIRED	User confirmation required as requested amount is above allowed limit.
400	HIGHER_AMOUNT_CAPTURE_NOT_ALLOWED	It is returned only when merchant captures with higher amount than merchant's allowed capture threshold for the preauth order having product type
400	ORDER_NOT_CAPTURABLE	Order is not capturable.
400	CANCELED_USER	Canceled user
400	INVALID_PARAMS	Invalid parameters received
400	NO_SUFFICIENT_FUND	The user's balance is insufficient to make payment.
400	ORDER_EXPIRED	Order cannot be captured or updated as it has already expired.
400	REAUTHORIZATION_IN_PROGRESS	Order is being reauthorized.
400	ALREADY_CAPTURED	Cannot capture already captured acquiring order.
400	TOO_CLOSE_TO_EXPIRY	Order cannot be reauthorized as request is too close to expiry time.
400	NO_SUFFICIENT_FUND	No sufficient fund
400	UNACCEPTABLE_OP	The requested operation is not able to be processed due to the current condition. E.g. the user is suspicious.
400	LIMIT_EXCEEDED	The payment amount exceeded upper limit. It is possible to occur in case capture amount exceeded preauthorized amount.
400	USER_DEFINED_DAILY_LIMIT_EXCEEDED	The payment amount exceeded user 24 hours defined limit. It is possible to occur in case capture amount exceeded preauthorized amount.
400	USER_DEFINED_MONTHLY_LIMIT_EXCEEDED	The payment amount exceeded user 30 days defined limit. It is possible to occur in case capture amount exceeded preauthorized amount.
401	USER_STATE_IS_NOT_ACTIVE	Inactive user
404	RESOURCE_NOT_FOUND	Order not found
500	BACKEND_TIMEOUT	Timeout occurred while accessing external service.

Below is an additional error which only occur if the used payment method was PayPay credit card | 429 | INTERNAL_SERVICE_RATE_LIMIT | Too many requests. |

Revert a payment authorization

Status	Code	Description
400	INVALID_PARAMS	Invalid parameters received
400	ORDER_NOT_CANCELABLE	Order is not cancelable.
404	RESOURCE_NOT_FOUND	Order not found

Refund a payment

Status	Code	Description
400	INVALID_PARAMS	Invalid parameters received
400	UNACCEPTABLE_OP	Order cannot be refunded, e.g., the user is suspicious.
400	CANCELED_USER	Target user does not exist.
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.
401	USER_STATE_IS_NOT_ACTIVE	The request cannot be accepted because the user status is inactive.
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

Create a topup QR Code

Status	Code	Description
400	DUPLICATE_TOPUP_QR_REQUEST	Topup QR with same merchantTopUpId exists.

Get topup status

Status	Code	Description
404	TOPUP_DETAILS_NOT_FOUND	Invalid merchantTopUpId.

Delete QR code

Status	Code	Description
404	TOPUP_QR_CODE_NOT_FOUND	Invalid QR codeId.
400	TOPUP_ALREADY_DONE	The topup has been done for given qrCodeId.

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 PayPay account.
401	INVALID_USER_AUTHORIZATION_ID	The specified user authorization ID is invalid.

Get masked user profile

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

Check user wallet balance

Status	Code	Description
400	CANCELED_USER	Canceled user

Expected cashback

Status	Code	Description
400	VALIDATION_FAILED_EXCEPTION	Input data is wrong.
500	UNAUTHORIZED_ACCESS	Un-authorised access

Get payment methods

Status	Code	Description
400	NO_VALID_PAYMENT_METHOD	User does not have any payment methods.

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.

Please check here for additional FAQs for OPA

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.

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"

Create a payment authorization、Get payment methods、Get Sets of Cashback Information、Create topup QR code、Get user wallet balance、Check user wallet balance、Get masked user profile

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 above APIs 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 diagram describes the display of the application after the purchase operation.

Mapping of API Request Parameter and display screen are shown in here

Display of the application after payment are shown in here

Everything involved in the payment life cycle

Everything related to user wallet balance

Everything related to user management

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

Notifications

Events	Category	Message（example）
Create a payment authorization:API	Push notification	〇〇が注文を受け付けました。 注文が完了しなかった場合、YYYY/MM/DD hh:mmに返戻されます。 金額: ￥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx
Update a payment authorization:API	Push notification	〇〇が支払い依頼金額を変更しました 注文が完了しなかった場合、YYYY/MM/DD hh:mmに返金されます 変更後の金額: ￥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx
Capture a payment authorization:API	Push notification	〇〇への支払いが完了しました。 金額: ￥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx
Revert a payment authorization:API	Push notification	支払い受付が〇〇によって取り消されました。 金額: ￥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx
Asking for approval of the increase	Push notification	〇〇から追加の支払いリクエストが届きました。 確認のうえお手続きください。 追加支払い金額: ¥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx
Asking for approval of the increase	Action bar	An additional payment request has arrived for XX
Payment authorization expired	Push notification	支払い受付が取り消されました。 金額: ￥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx
Refund a payment:API	Push notification	〇〇から返金が行われました。 金額: ￥1,000 取引番号: xxxxxxxxxxxxxxxxxxxx

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 payment authorization:API	-	AUTHORIZED	AUTHORIZED
Update a payment authorization:API	AUTHORIZED	AUTHORIZED	AUTHORIZED
Capture a payment authorization:API	AUTHORIZED	COMPLETED	COMPLETED
Payment authorization expired	AUTHORIZED	EXPIRED	EXPIRED
Revert a payment authorization:API	AUTHORIZED	CANCELED	CANCELED
Cancel a payment:API	AUTHORIZED	FAILED	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 user state changes.

This notification is sent after the client successfully acquired the user's authorization.

{
  "notification_type": "customer.authroization.succeeded",
  "notification_id": "evt_aXnbdeFt2Ke",
  "createdAt": "1349654313",
  "referenceId": "yyyy",
  "nonce": "12345",
  "scopes": "preauth_capture_native",
  "userAuthorizationId": "xxxxx",
  "profileIdentifier": "*******5678",
  "expiry": 1234567  // the authorization id expiration epoch timestamp in seconds
}

This notification is sent after the client failed to acquire 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 authorization 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 triggered under 2 cases:

1. a payment authorization is created successfully;
2. the expiration of a payment authorization is unexpectedly shortened due to uncontrollable events at PayLater end (only applicable for PAY_LATER_CC authorization).

In case 2, an updated expiration will be included in the payload. Merchant is expected to implement proper handling after consuming such an event to avoid capture failure.

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "state": "AUTHORIZED"
}

This notification is sent after the reauthorization process is completed successfully. The state of transaction is still maintained as AUTHORIZED.

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "reauth_request_id": "123456789",
  "state": "AUTHORIZED"
}

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

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": "2020-04-13T13:35:29Z",
  "order_amount": 12345,
  "state": "COMPLETED"
}

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

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": 12345,
  "state": "CANCELED"
}