PayPay Open Payment Api
API docs by Redocly

App Invoke (1.1)

Introduction

PayPay Open Payment API (OPA) is designed to be used by our payment partners to make payment-related operations in different scenarios, so as to deliver the best payment experience to end users. After being onboarded as a PayPay OPA client, depending on the contract, you will have the capability on one or more of the below:

  • Collect payment by directly debiting from PayPay user’s wallet
  • Create a Code and collect payments via PayPay's App using App Invoke
  • Use pre-authorization and capture payment flow to facilitate your purchase procedure
  • Easy web application integration with PayPay cashier page to collect payment
  • Build your own checkout experience with rich APIs provided by PayPay

This document will be focusing on APIs that support the second solution for Payment using App Invloke.

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.

App Invoke Flow

In this flow we empower merchants to create a code which can be used as a deeplink to invoke PayPay app and receive Payments. The user can makes the payment using PayPay App. The merchant can query the status of the payment as well as be notified of the payment to process the order. Details of the flow are shown in the slides here.
If there is no redirect from PayPay, please use Get Payment Details to check the payment result. You may not be able to redirect from PayPay, such as when the user closes the app. In this case, regardless of whether or not you have paid with PayPay, the member store will be in an unsettled state, and there is a possibility that users will complain.
The polling interval should be about 2 to 3 seconds.

Onboard merchant

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
  • webhook endpoints
  • client IP whitelist
  • merchant identifier (merchant_id) (for agent client)

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.

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 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.

Response code list

Common response code

Status Code Description
200 SUCCESS Success
202 REQUEST_ACCEPTED Request accepted
400 INVALID_REQUEST_PARAMS The infomation provide 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 required parameter is not set
400 INVALID_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 Something went wrong on PayPay service side
500 INTERNAL_SERVER_ERROR Something went wrong on PayPay service side
503 MAINTENANCE_MODE Sorry, we are down for scheduled maintenance.

Create a Code

Status Code Description
400 DUPLICATE_DYNAMIC_QR_REQUEST Duplicate Dynamic QR request error
400 PRE_AUTH_CAPTURE_UNSUPPORTED_MERCHANT Merchant do not support Pre-Auth-Capture. This can only occur if the request parameter isAuthorization is set to true.
400 PRE_AUTH_CAPTURE_INVALID_EXPIRY_DATE Provided Expiry Date is above the allowed limit of Max allowed expiry days. This can only occur if the request parameter isAuthorization is set to true.
400 DYNAMIC_QR_BAD_REQUEST Indicates that the request header, query parameter, or request body is invalid.

Delete a Code

Status Code Description
400 DYNAMIC_QR_BAD_REQUEST Indicates that the request header, query parameter, or request body is invalid.
404 DYNAMIC_QR_NOT_FOUND The specified QR code cannot be found.

Get payment details

Status Code Description
400 DYNAMIC_QR_PAYMENT_NOT_FOUND The specified transaction is not found. This error is returned when QR code is no longer available and no payment found with given merchantPaymentId, hence payment for the code cannot be triggered. In such case, merchants can create another a code using Create a Code API and start over again.
400 DYNAMIC_QR_BAD_REQUEST Indicates that the request header, query parameter, or request body is invalid.

Cancel a payment

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 UNACCEPTABLE_OP The requested operation is not able to be processed due to the current condition, e.g., the user is suspecious.
400 LIMIT_EXCEEDED The payment amount exceeded upper limit. It is possible to occur in case capture amount exceeded preauthorized amount. *1
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. *1
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. *1
400 ALREADY_CAPTURED Cannot capture already captured acquiring order.
400 CANCELED_USER Canceled user
400 ORDER_EXPIRED Order cannot be captured or updated as it has already expired.
400 ORDER_NOT_CAPTURABLE Order is not capturable.
400 REAUTHORIZATION_IN_PROGRESS Order is being reauthorized.
400 TOO_CLOSE_TO_EXPIRY Order cannot be reauthorized as request is too close to expiry time.
400 NO_SUFFICIENT_FUND The user's balance is insufficient to make payment.
404 RESOURCE_NOT_FOUND Order not found

*1 : PayPay will add this in production on September 1st.

Revert a payment authorization

Status Code Description
400 ORDER_NOT_CANCELABLE Order is not cancelable.
400 UNACCEPTABLE_OP Transaction error
404 RESOURCE_NOT_FOUND Order not found

Refund a payment

Status Code Description
400 INVALID_PARAMS Invalid parameters received
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 Canceled user
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

Timeout

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.

Handle 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.

Payment

Everything involved in the payment life cycle

Create a Code

Create a Code to receive payments.The expiration date of the created code is set to "expiryDate".
Please manage merchantPaymentId to make it unique on merchant side.

Timeout: 30s

Request Body schema: application/json

Code Creation

merchantPaymentId
required
string (MerchantPaymentId) <= 64 characters

Transaction ID provided by merchant that uniquely identifies the transaction.
When the same merchantPaymentId is specified, the previous result is returned.

required
object (MoneyAmount)
orderDescription
string <= 255 characters

Description of the order

Array of objects (MerchantOrderItem)
metadata
object

This parameter is obsolete.
The item is retained for backward compatibility and will be removed in a future release.

codeType
required
string

Please pass the fixed string "ORDER_QR"

storeInfo
string <= 255 characters

Store info for the merchant

storeId
string (StoreId) <= 255 characters

Id to identify store under merchant

productType
string (ProductType) <= 255 characters

The product type in PayPay system. Generally, this request parameter is optional. For some merchants that are restricted to use only certain product types, the product type must be properly set.
Example: VIRTUAL_BONUS_INVESTMENT, PAY_LATER_REPAYMENT, REAL_INVESTMENT

terminalId
string <= 255 characters

Id to identify terminal device under store

requestedAt
integer (EpochTime)

Epoch timestamp in seconds

redirectUrl
string

The url of the page/app to open after the payment is complete

redirectType
string
Enum: "WEB_LINK" "APP_DEEP_LINK" "WEBVIEW_IN_PAYPAY"

The type of redirect url

userAgent
string (UserAgentQrCode)

When this parameter is set, please set redirectType as WEB_LINK

The User agent of the web browser. When this parameter is provided, on mobile devices PayPay tries to open the browser that the merchant website is using. This value can be found by using the Javascript function navigator.userAgent.

This parameter supports WEB browsers as follows. If a browser other than below is set, user's default browser starts up after transaction. However, you cannot redirect correctly in private browsing or incognito.

  • Android - Chrome, Firefox, UC Browser, Yahoo Browser
  • iOS - Chrome, Firefox, UC Browser, Yahoo Browser

Even if this parameter is not specified, user's default browser starts up after transaction.

isAuthorization
boolean

By default it will be false, please set true if the amount will be captured later

authorizationExpiry
integer <EpochTime> (AuthorizationExpiry)

Epoch timestamp in seconds. The expiry duration must be less than the expiry granted to the merchant.

Note: The expiry, in case of authorization with PAY_LATER_CC, is subject to be shortened under special circumstances such as user has cancelled PayLater, etc. In such cases, PayPay will notify merchant in advance of an updated (shortened) the expiry before merchant's authorization period expires via webhook notification (see the section Transaction Events > AUTHORIZED | Create a payment authorization). It is suggested for merchant to implement proper handling after consuming such an event to avoid capture failure.

Responses

Request samples

Content type
application/json
{
  • "merchantPaymentId": "string",
  • "amount": {
    },
  • "orderDescription": "string",
  • "orderItems": [
    ],
  • "metadata": { },
  • "codeType": "string",
  • "storeInfo": "string",
  • "storeId": "string",
  • "productType": "string",
  • "terminalId": "string",
  • "requestedAt": 1704112496,
  • "redirectUrl": "string",
  • "redirectType": "WEB_LINK",
  • "userAgent": "string",
  • "isAuthorization": true,
  • "authorizationExpiry": 0
}

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Delete a Code

Delete a created dynamic QR Code.

Timeout: 15s

path Parameters
codeId
required
string

The ID of the Code

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Get payment details

Get payment details.

Timeout: 15s

path Parameters
merchantPaymentId
required
string (MerchantPaymentIdSimple) <= 64 characters

Transaction ID provided by merchant that uniquely identifies the transaction.

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Cancel a payment

This API is used when, while creating a payment, the client cannot determine the status of the payment. For example, the client receives a timeout or the response does not indicate the exact payment status.

If the request is accepted, PayPay will guarantee the money eventually goes back to user's account. Please note this is an asynchronous API and hence there can be a lag in processing the cancellation.


Note: You can utilize the Cancel API within the specified timeframe.
By default, the window is opened until 00:14:59 AM on the following day after the transaction took place.
Once this window is closed, kindly use the refund API to initiate refund.

For orderType REMITTANCE, the window is opened until 25 minutes after PayPay accepted the transaction.
You're not able to initiate refund request for REMITTANCE.

When you use PreAuth, you can cancel the payment only when the status is AUTHORIZED.
Once the payment status becomes COMPLETED or the payment is expired and the status is EXPIRED, you cannot cancel the payment.

When a timeout error happens, we recommend to keep calling until it succeeds with an adequate interval, or till the specified window above comes to an end.

Timeout: 15s

path Parameters
merchantPaymentId
required
string (MerchantPaymentIdSimple) <= 64 characters

Transaction ID provided by merchant that uniquely identifies the transaction.

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": { }
}

Update a payment authorization

This API is used to change the blocked amount of money during authorization with the same payment method.

During this API call, a new AUTHORIZED event webhook will be triggered, and the state of the transaction will remain as AUTHORIZED.

If lower amount of reauthorization is initiated, this API will return 200 for successful call and the process will be completed.

If higher amount of reauthorization is initiated, this API will return 201 code for successful call to ask for user's confirmation.

In the reconcilliation file, it is expected to have multiple records of AUTHORIZED transactions with the same order ID. The overview of how the reconcillation file will be is shown below:

orderId merchantId brandName storeId terminalId transactionStatus acceptedAt amount orderReceiptNumber methodOfPayment merchantPaymentId paymentDetails
xx123456 yy08181 〇〇加盟店 1234567 0 COMPLETED 2020-01-30T10:53:25+09:00 480 000-0001 wallet, point 000-0001 [{"paymentMethod":"POINT", "amount":80}, {"paymentMethod":"wallet", "amount":400}]
xx123456 yy08181 〇〇加盟店 1234567 0 REFUNDED 2020-01-30T16:53:25+09:00 -480 000-0001 wallet refund_000-0001 [{"paymentMethod":"wallet", "amount":-480}]
xx567890 yy08181 〇〇加盟店 1234567 0 AUTHORIZED 2020-01-30T13:31:43+09:00 2924 000-0005 wallet 000-0005 [{"paymentMethod":"wallet", "amount":2924}]
xx567890 yy08181 〇〇加盟店 1234567 0 AUTHORIZED 2020-01-31T13:50:43+09:00 1000 000-0005 wallet 000-0005 [{"paymentMethod":"wallet", "amount":1000}]

Timeout: 30 s

Request Body schema: application/json

Reauthorize

requestId
required
string (ReauthRequestId) <= 255 characters

Identifier reauth request generated by merchant

paymentId
required
string (PaymentId) <= 64 characters

The payment transaction id provided by PayPay

required
object (MoneyAmount)
requestedAt
integer (EpochTime)

Epoch timestamp in seconds

merchantComment
string <= 255 characters

The reason why a reauth is required. Will be shown in post transaction screen timeline if passed

redirectUrl
string

Url that Paypay can redirect to after reauthorize is successfully executed. Required for higher amount reauthorization

redirectType
string
Enum: "APP_DEEP_LINK" "WEB_LINK"

Type of redirection after reauthorize is successfully executed. Required for higher amount reauthorization

userAgent
string

Full string of browser user agent. Required for higher amount reauthorization

Responses

Request samples

Content type
application/json
{
  • "requestId": "string",
  • "paymentId": "string",
  • "updatedAmount": {
    },
  • "requestedAt": 1704112496,
  • "merchantComment": "string",
  • "redirectUrl": "string",
  • "redirectType": "APP_DEEP_LINK",
  • "userAgent": "string"
}

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Capture a payment authorization

This api is used to capture the payment authorization for a payment.
If you want to increase the amount, we will send a notification to the user asking for consent.

Even when a timeout error happens, we recommend to keep calling until it succeeds with an adequate interval, with different merchantCaptureId.

Timeout: 30s

Request Body schema: application/json
merchantPaymentId
required
string (MerchantPaymentIdSimple) <= 64 characters

Transaction ID provided by merchant that uniquely identifies the transaction.

required
object (MoneyAmount)
merchantCaptureId
required
string (MerchantCaptureId) <= 64 characters

Transaction ID provided by merchant to uniquely identify Capture by transaction.

requestedAt
required
integer (EpochTime)

Epoch timestamp in seconds

orderDescription
required
string <= 255 characters

Description for Capture

Responses

Request samples

Content type
application/json
{
  • "merchantPaymentId": "string",
  • "amount": {
    },
  • "merchantCaptureId": "string",
  • "requestedAt": 1704112496,
  • "orderDescription": "string"
}

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Revert a payment authorization

This API is used when the merchant wants to cancel the payment authorization because of the user has cancelled the order.

Timeout: 30s

Request Body schema: application/json

Revert Authorized Order Request

merchantRevertId
required
string (MerchantRevertId) <= 64 characters

Transaction ID provided by merchant to uniquely identify Revert by transaction.

paymentId
required
string (PaymentId) <= 64 characters

The payment transaction id provided by PayPay

requestedAt
required
integer (EpochTime)

Epoch timestamp in seconds

reason
string (Reason) <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "merchantRevertId": "string",
  • "paymentId": "string",
  • "requestedAt": 1704112496,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Refund a payment

Refund the payment to the user.
This API only accepts payment refunds, and refunds are performed asynchronously on the PayPay side.
Please see Get refund details for the results of your refund.

Timeout: 30s

Request Body schema: application/json

Refund

merchantRefundId
required
string (MerchantRefundId) <= 64 characters

Transaction ID provided by merchant to uniquely identify a refund of a transaction.
For multiple refunds, a unique merchantRefundId must be set for each refund transaction.
When the same merchantRefundId is specified for multiple refunds, the previous result is returned.

paymentId
required
string (PaymentId) <= 64 characters

The payment transaction id provided by PayPay

required
object (MoneyAmount)
requestedAt
required
integer (EpochTime)

Epoch timestamp in seconds

reason
string (Reason) <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "merchantRefundId": "string",
  • "paymentId": "string",
  • "amount": {
    },
  • "requestedAt": 1704112496,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Get refund details

Optional paymentId as request query param in the GET Refund Details API: There is no need to pass this field if you don't use same merchantRefundId for two different paymentIds in the POST Refund API.

In case you use same merchantRefundId for the different paymentIds (different payment transaction IDs) in the POST Refund API. PayPay has multiple refund data for the same merchantRefundId in the system. PayPay maintains the merchantId, merchantRefundId, paymentId as idem key to identify the unique refund transaction details. Pass paymentId along with merchantRefundId to allow PayPay uniquely identify the refund transactions and return them when there are multiple refund transactions exists. If you don't pass paymentId in this case, the latest refund data is returned from the system.

Timeout: 15s

path Parameters
merchantRefundId
required
string (MerchantRefundIdSimple) <= 64 characters

Transaction ID provided by merchant to uniquely identify a refund of a transaction.

query Parameters
paymentId
string (PaymentId) <= 64 characters

The payment transaction id provided by PayPay

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

About Payment judgment

Please judge the payment result that on the GetPaymentDetails API or Webhook (transaction event) described later.

Notify users when events occur

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

The amount will be captured later

Events Category Message（example）
On-PayPay screen payment 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

Instant payment

Events Category Message（example）
On-PayPay screen payment (success) Push notification 取引が完了しました。
金額：100円
取引番号：xxxxxxxxxxxxxxxxxxxx
店舗名：テスト加盟店
On-PayPay screen payment (failure) Push notification 取引が失敗しました。
金額：100円
取引番号：xxxxxxxxxxxxxxxxxxxx
店舗名：テスト加盟店
Refund a payment:API Push notification 取引番号: xxxxxxxxxxxxxxxxxxxx
1,000円の返金が完了しました。

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

Basic status transition

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

The amount will be captured later

Event Before After Webhook Notification
Create a Code:API - CREATED none
On-PayPay screen payment CREATED 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

Instant payment

Event Before After Webhook Notification
Create a Code:API - CREATED none
On-PayPay screen payment CREATED COMPLETED COMPLETED
Refund a payment:API COMPLETED REFUNDED none
Cancel a payment:API COMPLETED FAILED none

Webhook Setup

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.

Transaction Events

Events related to order transaction state changes.

AUTHORIZED | Create a payment authorization

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

AUTHORIZED | Update a payment authorization

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

COMPLETED

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": "A12345",
  "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"
}

CANCELED

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": "A12345",
  "authorized_at": "2020-03-13T13:35:30Z",
  "expires_at": "2020-04-13T13:35:29Z",
  "paid_at": null,
  "order_amount": "12345",
  "state": "CANCELED"
}

EXPIRED

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

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

EXPIRED_USER_CONFIRMATION

This notification is sent when your request to approve the increase has expired. The increase approval request expires 6 hours after the request.

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

FAILED

This notification will be sent when there are no balance blocks and the order status changes to FAILED.
Depending on the type of error, you may not be notified.

{
  "notification_type": "Transaction",
  "merchant_id": "123456789",
  "store_id": "123456",
  "pos_id": "123",
  "order_id": "123456789123456",
  "merchant_order_id": "A12345",
  "order_amount": "12345",
  "state": "FAILED"
}

Transaction Recon File with Capture

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

File linkage specifications

The amount will be captured later

Category Description Note
File linkage method Webhook
File Name preauth_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 retention 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

Instant payment

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

File layout

The amount will be captured later

Key Value from Note
orderId paymentId paymentId issued by PayPay.
merchantId merchant_id merchantId issued by PayPay.
brandName brandName Brand name registered with PayPay.
storeId storeId storeId set in the request.
storeName storeName Store name registered with PayPay.
terminalId terminalId terminalId set in the request.
transactionStatus "AUTHORIZED" , "CANCELED" , "COMPLETED" , "EXPIRED", "FAILED", "REFUNDED" Status of transaction data managed by PayPay
acceptedAt Described in the attached table below
amount amount Absolute value notation only
orderReceiptNumber "" Cannot be set with this function.
methodOfPayment "wallet", "pay_later_cc", "point" Comma separated payment methods.
merchantPaymentId Described in the attached table below merchantPaymentId issued by Merchant.
paymentDetails [{"paymentMethod":"POINT", "amount":80, "breakdown":[{"type":"REGULAR", "amount":80}]}, {"paymentMethod":"WALLET", "amount":400}] This is the payment amount for each payment method. It will only be provided when transactionStatus is COMPLETED or REFUNDED.

Since the acquisition source of the value of merchantPaymentId and acceptedAt changes for each transactionStatus, they are described below.

transactionStatus merchantPaymentId acceptedAt
AUTHORIZED merchantPaymentId Create a payment authorization request: acceptedAt
Update a payment authorization: acceptedAt
Get payment details response: acceptedAt
CANCELED merchantRevertId Revert a payment authorization request: acceptedAt
Get payment details response: revert.data.[].acceptedAt
COMPLETED merchantCaptureId Capture a payment authorization response: acceptedAt
Get payment details response: captures.data.[].acceptedAt
EXPIRED merchantPaymentId Get payment details response: expiresAt
FAILED merchantPaymentId Get payment details response: failedAt
REFUNDED merchantRefundId Refund a payment response: acceptedAt
Get payment details response: refunds.data.[].acceptedAt

Download Sample File

Instant payment

Key Value from Note
決済番号 paymentId paymentId issued by PayPay.
加盟店ID merchant_id merchantId issued by PayPay.
屋号 brandName Brand name registered with PayPay.
店舗ID storeId storeId set in the request.
店舗名 storeName Store name registered with PayPay.
端末番号/PosID terminalId terminalId set in the request.
取引ステータス "取引完了", "取引失敗", "返金完了", "返金失敗" Status of transaction data managed by PayPay
取引日時 acceptedAt
取引金額 amount Minus sign for refunds
レシート番号 "" Cannot be set with this function.
支払い方法 "PayPay残高", "クレジットカード", "あと払い", "PayPayポイント" Comma separated payment methods.
マーチャント決済ID merchantPaymentId merchantPaymentId issued by Merchant.
支払い詳細 [{"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

Webhook notifications

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

FAQ

Click here for the latest FAQ.

Changelog

Date of Change Date of Release Type of Change Section Updates
2022.08.23 2022.12.05 Feature Update a payment authorization 1. Removed the error code of HIGHER_AMOUNT_REAUTH_NOT_SUPPORTED
2. Added the sequence diagram of Update a Payment Authorization for both lower and higher amount reauthorization
3. Added redirectUrl, redirectType, and userAgent of Update a Payment Authorization for higher amount reauthorization
4. Added 201 response of Update a Payment Authorization in higher reauthorize case
2022.09.10 2022.12.05 Feature Update a payment authorization 1. Changed the code of for USER_CONFIRMATION_REQUIRED to 08300104.
2. Deleted qrCodeId and deeplink for USER_CONFIRMATION_REQUIRED on Update a payment authorization API.
3. Adjusted the response for USER_CONFIRMATION_REQUIRED to return url and expiresAt instead of echoing back merchant's request
2022.09.21 2022.12.05 Feature Update a payment authorization 1. Changed the redirectType from APP_DEEPLINK to APP_DEEP_LINK.
2022.10.27 Released Documentation Fix Get payment details 1. Changed Description of acceptedAt.
2022.11.04 2022.12.05 Feature Update a payment authorization 1. Added acceptedAt attribute to 200 OK response
2023.03.10 TBD Documentation Fix Update status code description 1. Changed description of ORDER_NOT_REVERSIBLE status code
2023.03.30 Released Documentation Fix File linkage specifications Fixed the description of Notification time.
2023.04.03 2023.06.06 Feature Create a code Added new request and response parameter productType
2023.04.13 Released Documentation Fix Recon file Added that for "取引ステータス": "取引失敗" or "transactionStatus": "FAILED", it may not be output to the recon file depending on the cause of the error.
2023.04.26 2023.06.12 Feature Get payment details, Update a payment authorization Add paymentMethods response field
2023.06.16 Released Documentation Fix Refund a payment Changed the description of Refund a payment.
2023.07.04 Released Documentation Fix Create a Code, Get payment details Updated the description of metadata.
2023.10.10 Released Documentation Fix Error handling Add new error code PAY_METHOD_INVALIDATED.
2023.11.15 2023.11.15 Feature Recon file Added POINT/PayPayポイント payment type in methodOfPayment and new column paymentDetails and recon structure changes in Update a payment authorization.
2023.11.28 TBD Documentation Fix Update status code description Updated description of ORDER_NOT_REVERSIBLE to include more detailed cancellation conditions.
2023.12.19 TBD Feature Get Refund details Added new query param paymentId for the request and updated Get Refund details api description.
2024.02.20 Released Documentation Fix Get payment Details, Create a Code APIs and Error Handling section Updated the expiryDate field description for Get payment Details, Create a Code and DYNAMIC_QR_PAYMENT_NOT_FOUND error description under Get payment details API.
2024.03.12 Released Documentation Fix Create a Code, Get payment details Added that the metadata is obsolete.
2024.05.27 Released Documentation Fix Create a Code Updated the description of userAgent.
2024.06.14 TBD Feature Get payment details Added HIVEX as supported value in data.paymentMethods.type
2024.08.19 2024.08.19 Feature Cancel a payment. Error Handling Added Cancel acceptable window description for REMITTANCE order type.
2024.09.05 2024.09.05 Feature Recon file Updated condition for showing paymentDetails in recon file.
2024.09.05 TBD Feature Get payment details, Capture a payment authorization Added a field breakdown under paymentMethods in the response.
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