PayPay Open Payment Api
API docs by Redocly

Native Payment (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 to do one or more of the below:

  • Collect payment by directly debiting from a PayPay user’s wallet
  • Use the pre-authorization and capture payment flow to facilitate your purchase procedure
  • Easily integrate your web application 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 first solution, which we have designed especially for our trusted partners.

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, 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 set up 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 or by getting in touch with a sales representative.

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

Acquire user authorization

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

User authorization can be acquired using our simple account linking flow here.

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

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 codes to indicate the success or failure of requests. With this information, you can decide what error handling strategy to use. In general, PayPay OPA returns the following HTTP response status codes.

Response code list

Common response code

Status Code Description
200 SUCCESS Success
202 REQUEST_ACCEPTED Request accepted
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.
400 INVALID_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
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 means 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

Status Code Description
400 SUSPECTED_DUPLICATE_PAYMENT Similar transaction exists in a short time.
400 UNACCEPTABLE_OP The requested operation cannot be processed due to a current condition. For example, the user is suspicious.
400 LIMIT_EXCEEDED The payment amount exceeded the upper limit.
400 USER_DEFINED_DAILY_LIMIT_EXCEEDED The payment amount exceeded the user's 24 hours defined limit.
400 USER_DEFINED_MONTHLY_LIMIT_EXCEEDED The payment amount exceeded the user's 30 days defined limit.
400 NO_SUFFICIENT_FUND The user's balance is insufficient to make payment.
400 CANCELED_USER The user has canceled their PayPay account.
400 USER_DAILY_LIMIT_FOR_MERCHANT_EXCEEDED Payment amount exceeded merchant defined restriction.
401 USER_STATE_IS_NOT_ACTIVE The request cannot be accepted because the user status is inactive.
404 RESOURCE_NOT_FOUND Order not found
404 PAYMENT_METHOD_NOT_FOUND The user's payment method not found
500 TRANSACTION_FAILED This code means the transaction has failed on PayPay's side. You can create a new transaction for the same purpose with reasonable backoff time.

The below error could occur if the merchant requires users to be KYCed, but the user is not.

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.

Get payment details

Status Code Description
404 RESOURCE_NOT_FOUND Order not found

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.

Refund a payment

Status Code Description
400 UNACCEPTABLE_OP The requested operation cannot be processed due to a current condition. For example, the user is suspicious.
400 CANCELED_USER The user has canceled their PayPay account.
400 THROTTLED_MULTIPLE_REFUND_REJECTED Rejected the refund request because a 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 The specified refund payment could not be 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 QR codeId.
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.

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 Unauthorized access

Get payment methods

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

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 be at least 30 seconds. When a 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 failed or was 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 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.


Get user authorization status

user status
terminate PayPayuser authorization expiredDeauthorization 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、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 PayPayuser authorization expiredDeauthorization 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 PayPayuser authorization expiredDeauthorization in app operation
http status:400
Code="CANCELED_USER"		 http status:200
Code="SUCCESS"		 http status:200
Code="SUCCESS"

Payment

Everything involved in the payment life cycle

Create a payment

Designate an available payment method (PayPay Balance or PAY_LATER_CC or CREDIT_CARD) for a user, create a direct debit payment and start the money transfer.

When a timeout error happens, we recommend to cancel the payment immediately, or if that is not possible, refund them. See 'Cancel a payment' endpoint and 'Refund a payment' for more detail.

Timeout: 30s

query Parameters
agreeSimilarTransaction
string

(Optional) If the parameter is set to "true", the payment duplication check will be bypassed.

Request Body schema: application/json

Payment

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

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

storeId
string (StoreId) <= 255 characters

Id to identify store under merchant

terminalId
string (TerminalId) <= 255 characters

Id to identify terminal device under store

orderReceiptNumber
string (OrderReceiptNumber) <= 255 characters

Receipt number provided by merchant

orderDescription
string (OrderDescription) <= 255 characters

Description of the order

Array of objects (MerchantOrderItem)
metadata
object (Metadata)

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

paymentMethodType
string (PaymentMethodType) <= 64 characters

Payment method type. Possible values are the followings:

  • "WALLET"
  • "PAY_LATER_CC"
    • This is available for merchants who accept Credit (Pay Later) in online payment.
  • "CREDIT_CARD"
    • This is available for merchants who accept Credit Card in online payment.

Merchant can make use of this field to designate the payment method to be used for a payment transaction.

If "PAY_LATER_CC", "WALLET" or "CREDIT_CARD" is passed, a payment transaction is expected to happen with Credit (Pay Later), PayPay Balance or Credit Card as payment method and there will be no fallback payment triggered if a failure is detected on the designated payment method.

If not set, PayPay will define the payment method the transaction will be tried on.
If user has enabled payment method priority, PayPay will try the available payment method from the top of the priority list of user and fallback to the second available payment method if the first one fails.
If user hasn't enabled payment method priority, PayPay will try Balance by default.

"POINT" is not supported as a single payment method.

paymentMethodId
string (PaymentMethodId) <= 64 characters

paymentMethodId is used together with paymentMethodType to designate a payment instrument under a paymentMethodType (It is particularly for the paymentMethodType which has multiple payment instruments attached to it such as "CREDIT_CARD" or PAY_LATER_CC, to tackle the case when a user can have multiple credit cards). Its value can be fetched from Get payment methods API.

It is not required to send paymentMethodId if "WALLET" or "PAY_LATER_CC" is passed as paymentMethodType.
For "PAY_LATER_CC" when a paymentMethodId is not specified and the user has multiple payment instruments, the one registered earlier will be selected automatically.

You may regard paymentMethodId as a string representation of a numeric value, with a maximum length of approximately 20 digits.

productType
string (ProductTypeWithPoint)
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT" "PAYLATER_PAYMENT_ALLOCATION"

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.

onetimeUseCashback
string (OnetimeUseCashbackForCreatePayment)
Enum: "ENABLED" "DISABLED"

NOTE: To use this parameter, onetime_use_cashback scope is required.

Whether to use cashback for this transaction. For example, if it's "ENABLED" PayPay will use cashback even if user's master settings is "Save". Likewise, PayPay will disable to use cashback for this payment when it's "DISABLED".

This parameter will be ignored when the master setting is "Earn Points"

If it is not provided, PayPay will apply user's master settings.

Responses

Request samples

Content type
application/json
Example
{
  • "merchantPaymentId": "string",
  • "userAuthorizationId": "string",
  • "amount": {
    },
  • "requestedAt": 1704112496,
  • "storeId": "string",
  • "terminalId": "string",
  • "orderReceiptNumber": "string",
  • "orderDescription": "string",
  • "orderItems": [
    ],
  • "metadata": { },
  • "paymentMethodType": "string",
  • "paymentMethodId": "string",
  • "productType": "VIRTUAL_BONUS_INVESTMENT",
  • "onetimeUseCashback": "ENABLED"
}

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

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.

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

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

Get Sets of Cashback Information

  • This is a query REST API that returns all cashback information for each supported payment methods.
  • It will give customer available cashback information before customer places an order.

Timeout: 15s

Request Body schema: application/json
required

request params

requestId
required
string <= 64 characters

The unique id to identify expected cashback request by merchant.

merchantPaymentId
string <= 64 characters

The unique payment transaction id provided by merchant. Pass same merchantPaymentId in both Get Sets of Cashback Information and Create Payment APIs to verify cashback amount in Get Sets of Cashback Information API and granted cashback amount after payment transaction.

userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

merchantId
string

ID of merchant issued by PayPay.

storeId
string (StoreId) <= 255 characters

Id to identify store under merchant

requestedAt
integer <int64>

UNIX epoch timestamp

Array of objects (MerchantOrderItem)

Either this value or amount is required.

object (MoneyAmount)
productType
string (ProductTypeWithPoint)
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT" "PAYLATER_PAYMENT_ALLOCATION"

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.

Responses

Request samples

Content type
application/json
{
  • "requestId": "string",
  • "merchantPaymentId": "string",
  • "userAuthorizationId": "string",
  • "merchantId": "string",
  • "storeId": "string",
  • "requestedAt": 1234567890,
  • "orderItems": [
    ],
  • "amount": {
    },
  • "productType": "VIRTUAL_BONUS_INVESTMENT"
}

Response samples

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

Get payment methods

The Get payment methods API allows the merchant to know a user's payment methods before a payment is made, and use specific payment methods in a transaction.

This API returns the available payment method type and payment method id of a user, which could be "PAY_LATER_CC" (learn more about PAY_LATER_CC) or "CREDIT_CARD".

This API does not return the user's wallet payment method id, because it is the default payment-method when no paymentMethodId is passed to the payment API.

This API also returns walletInfo if the user granted permission to view balance information, by providing the get_balance scope during account linking.

If the user has multiple payment instruments for "PAY_LATER_CC", this API will return all the payment instruments sorted by highest rank (Gold, Regular, Family) and earliest registered date.

Timeout: 30s

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

productType
string (ProductTypeForPaymentMethodsMixin)
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "PAYLATER_PAYMENT_ALLOCATION"

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.

Responses

Response samples

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

Wallet

Everything related to user wallet balance

Check user wallet balance.

Check if user has enough balance to make a payment

Timeout: 15s

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

amount
required
integer <= 255 characters
currency
required
string
Value: "JPY"
productType
string (ProductTypeWithPoint)
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT" "PAYLATER_PAYMENT_ALLOCATION"

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.

onetimeUseCashback
string (OnetimeUseCashbackForGetBalance)
Enum: "ENABLED" "DISABLED"
Example: onetimeUseCashback=ENABLED

Note: To use this parameter, onetime_use_cashback scope is required.

Whether to include cashback. For example, PayPay will take cashback balance into account if it's "ENABLED". Likewise, PayPay will exclude cashback amount when it's "DISABLED".

This parameter will be ignored when the master setting is "Earn Points"

If it is not provided, PayPay will apply user's master settings.

Responses

Response samples

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

Get user wallet balance

Retrieve the total amount in a user's Wallet. Application to PayPay is separately required to get user wallet balance. Timeout: 15s

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

currency
required
string
Value: "JPY"
productType
string
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT" "PAYLATER_PAYMENT_ALLOCATION"

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.
When merchant passes productType either VIRTUAL_BONUS_INVESTMENT or POINT, PayPay returns the user's current point balance regardless of the setting status of useCashback flag.

onetimeUseCashback
string
Enum: "ENABLED" "DISABLED"
Example: onetimeUseCashback=ENABLED

To use this parameter, onetime_use_cashback scope is required.

Whether to include cashback. For example, PayPay will take cashback balance into account if it's "ENABLED". Likewise, PayPay will exclude cashback amount when it's "DISABLED".

Note: This parameter will be ignored when the master setting is "Earn Points"

If it is not provided, PayPay will apply user's master settings.

Responses

Response samples

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

Create topup QR code

This service will allow a merchant to create a QR code for the user. The user can scan the QR code to top up their account.

Timeout: 30s

Request Body schema: application/json

QRCode

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 (MoneyAmountForTopUpQR)

The minimum topup amount for this transaction(minimum: 1,000 Japanese yen, maximum: 500,000 Japanese yen)

metadata
object

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

codeType
required
string
Value: "TOPUP_QR"

Pass string as "TOPUP_QR"

requestedAt
required
integer (EpochTime)

Epoch timestamp in seconds

redirectType
string (RedirectTypeTopUp)
Enum: "WEB_LINK" "APP_DEEP_LINK"

The type of redirect after complete of the topup

redirectUrl
string

The URL to redirect the user to after completing the payment

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.

Responses

Request samples

Content type
application/json
{
  • "merchantTopUpId": "string",
  • "userAuthorizationId": "string",
  • "minimumTopUpAmount": {
    },
  • "metadata": { },
  • "codeType": "TOPUP_QR",
  • "requestedAt": 1704112496,
  • "redirectType": "WEB_LINK",
  • "redirectUrl": "string",
  • "userAgent": "string"
}

Response samples

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

Get topup details

Get the details of topup done using QR Code

Timeout: 30s

path Parameters
merchantTopUpId
string (MerchantTopUpId) <= 64 characters

The unique user credit transaction id provided by merchant

Responses

Response samples

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

Delete QR code

Delete the topup QR code

Timeout: 30s

path Parameters
codeId
required
string

unqiue ID of generated QR Code

Responses

Response samples

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

User

Everything related to user management

Unlink user

Unlink a user from the client

Timeout: 15s

path Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "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

Response samples

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

Get masked user profile

Get the masked phone number of the user

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

Responses

Response samples

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

Get PayPaySTEP rate

Get user's cashback rate details details for current month and/or next month, based on the progress of PayPaySTEP.

To use this API, cashback scope is required, and user permission is also required.

Timeout: 10s

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

period
required
string
Enum: "current_month" "next_month" "current_month,next_month"

specify necessary periods in response, separate by comma.

Responses

Response samples

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

Notify users when events occur

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 payment:API(COMPLETED) Push notification 取引が完了しました。
金額：100円
取引番号：xxxxxxxxxxxxxxxxxxxx
店舗名：テスト加盟店
Refund a payment:API Push notification 取引番号: xxxxxxxxxxxxxxxxxxxx
100円の返金が完了しました。
Create a payment:API(FAILED) Push notification 取引が失敗しました。
金額：1000円
取引番号：xxxxxxxxxxxxxxxxxxxx
店舗名：テスト加盟店
Create a payment:API(Insufficient fund) In-app notification 取引が失敗しました。
金額：1000円
取引番号：xxxxxxxxxxxxxxxxxxxx
店舗名：テスト加盟店

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.

Event Before After
Create a payment:API - COMPLETED
Create a payment:API - FAILED
Refund a payment:API COMPLETED REFUNDED
Cancel a payment:API COMPLETED FAILED

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 the notifications that we are currently sending to webhook.

Customer Events

Events related to user state changes.

Events related to user state changes. The authroization comes as is.

attribute type is_required? description
notification_type string yes Type of the notification. Possible values: customer.authroization.succeeded, customer.authroization.failed, customer.authroization.revoked, customer.authroization.extended, customer.authroization.canceled
notification_id string yes The ID used to identify the notification
createdAt number yes The time at which the notification is created, epoch timestamp in seconds
referenceId string no The ID used to identify the user on the merchant's system
nonce string yes if notification_type is customer.authroization.succeeded, customer.authroization.failed The same nonce in the request for client side to validate the response
scopes string yes if notification_type is customer.authroization.succeeded, customer.authroization.extended Scopes of the user authorization
userAuthorizationId string yes if notification_type is customer.authroization.succeeded, customer.authroization.revoked, customer.authroization.canceled, customer.authroization.extended PayPay user reference id which you should store in your db and use it in the api calls. Max length: 64 characters
profileIdentifier string yes if notification_type is customer.authroization.succeeded Masked phone number or email e.g. "5678", "abc@example.com"
expiry number yes if notification_type is customer.authroization.extended, customer.authroization.succeeded The authorization ID's expiration epoch timestamp in seconds
result string yes if notification_type is customer.authroization.failed The result of the operation that the client is trying to do. Possible values: declined, bad_request, kyc_not_completed, kyc_data_mismatch
reason string yes if notification_type is customer.authroization.failed The reason for the result of the operation

The following are examples of the possible notification types:

customer.authroization.succeeded

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": "direct_debit",
  "userAuthorizationId": "xxxxx",
  "profileIdentifier": "*******5678",
  "expiry": 1234567  // the authorization id expiration epoch timestamp in seconds
}

customer.authroization.failed

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.

customer.authroization.revoked

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

customer.authroization.extended

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": "direct_debit",
  "userAuthorizationId": "xxxxx",
  "expiry": 1234567  // the authorization id expiration epoch timestamp in seconds
}

customer.authroization.canceled

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

Transaction Recon File

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

File linkage specifications

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

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

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 Documentation Update Date of Release Type of Change Section Updates
2022.09.07 2022.12.07 Feature Create a payment Updated the description of request parameter "paymentMethodType"
2022.10.19 2022.10.27 Feature Create a payment Added new error code USER_DAILY_LIMIT_FOR_MERCHANT_EXCEEDED
2022.12.17 2023.01.31 Feature Create a payment Returned acceptedAt as zero when state is CREATED in Create a Payment api and Get payment details
2023.01.25 Released Documentation Fix Create a topup QR Code Fixed the description of minimumTopUpAmount parameter
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.05 2023.04.17 Deprecation Consult Expected Cashback Info Removed Consult Expected Cashback Info V1 API.
2023.04.13 Released Documentation Fix Recon file Added that for "Status": "Payment failed", it may not be output to the recon file depending on the cause of the error.
2023.04.26 2023.06.12 Feature Create a payment, Get payment details Added paymentMethods response field.
2023.04.28 2023.05.25 Feature Create Account Link QR Code Changed referenceId to optional
2023.06.16 Released Documentation Fix Refund a payment Changed the description of Refund a payment.
2023.06.26 2023.08.01 Feature Get payment methods Change PayPayあと払い to PayPay（クレジット）in issuerName field in the response
2023.08.01 Released Documentation Fix Create a payment, Get payment details Changed the description of acceptedAt.
2023.09.01 2023.09.12 Feature Create a payment, Get user wallet balance, Check user wallet balance Add description of onetimeUseCashback parameter.
2023.09.08 2023.10.05 Feature Get payment methods Adding a new field membership in Get payment methods api response for PAY_LATER_CC payment method type.
2023.11.06 2023.12.04 Feature Create a payment, Get payment details Added POINT to paymentMethods.type
2023.11.15 2023.12.04 Feature Recon file Added PayPayポイント payment type in methodOfPayment and new column paymentDetails.
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.01.18 TBD Feature Get PayPaySTEP rate Adding new API interface for Get cashback rate details
2024.03.12 Released Documentation Fix Get payment details Added that the metadata is obsolete.
2024.04.08 TBD Feature Create a payment PaymentMethodId is no longer encrypted.
2024.04.19 TBD Feature Create a payment paymentMethodId is no longer required for PAY_LATER_CC.
2024.05.13 2024.08.05 Feature Create a payment Added schema for multiple payment methods.
2024.05.27 Released Documentation Fix Create a Code Updated the description of userAgent.
2024.08.19 2024.08.19 Feature Cancel a payment. Error Handling Added Cancel acceptable window description for REMITTANCE order type.
2024.09.05 TBD Feature Create a payment, Get payment details 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
2024.11.05 TBD Feature Get user wallet balance Remove CASHBACK_EXPIRABLE from accounts.
2024.11.19 TBD Feature Get payment methods, Create a payment, Get user wallet balance, Check user wallet balance, Get Sets of Cashback Information Added product type PAYLATER_PAYMENT_ALLOCATION.