PayPay Open Payment API Documentation

• Introduction
• TLS implementation
• Onboard merchant
• Acquire user authorization
• General
  • API Authentication
  • Specify merchant in request
  • Error Handling
    • Response code list
    • Timeout
    • Handle unknown payment status
    • API execution result associated with user authorization status change
  • API General Request ID
• Apis
  • Payment
    • postCreate a continuous payment
    • getGet payment details
    • delCancel a payment
    • postRefund a payment
    • getGet refund details
    • getGet payment methods
  • Wallet
    • getCheck user wallet balance
  • User
    • delUnlink user
    • getGet user authorization status
    • getGet masked user profile
• Notify users
  • Notify users when events occur
• status transition
  • Basic status transition
• Webhooks
  • Webhook Setup
  • Customer Events
    • customer.authroization.succeeded
    • customer.authroization.failed
    • customer.authroization.revoked
    • customer.authroization.extended
    • customer.authroization.canceled
• Recon file
  • Transaction Recon File
    • File linkage specifications
    • File layout
    • Webhook notifications
• FAQ
  • FAQ
• Changelog
  • Changelog

API docs by RedoclyContinuous Payment (1.0)

Introduction

There are many online merchants which provide features which need regular payments in the form of subscriptions. These include and are not limited to content providers like Netflix, Hulu, subscription products on Amazon, gaming services like Sony, etc. The goal here is not just to provide continuous payments but also to allow the merchant to go live with minimum integration and ensure low failure rate by providing features where the merchant can request money from the user.

TLS implementation

The PayPay Open Payment API requires that you use TLS 1.2 or higher as a security measure. Note that you cannot connect with TLS1.0 and TLS1.1.

Onboard merchant

To start utilizing our Open Payment API platform, at first the 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.

Acquire user authorization

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

Acquiring user authorization can be achieved using our simple account linking flow here.

Specify "continuous_payments" for SCOPE.

API Authentication

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 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	Something went wrong on PayPay service side.
503	MAINTENANCE_MODE	Sorry, we are down for scheduled maintenance.

Create a continuous payment

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.
400	INVALID_PARAMS	The requested operation is not able to be processed due to the current condition, e.g., thetransaction limit exceeded.
400	SUSPECTED_DUPLICATE_PAYMENT	Similar transaction exist in a short time.
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	NON_KYC_USER	User has not completed KYC.
400	USER_DAILY_LIMIT_FOR_MERCHANT_EXCEEDED	Payment amount exceeded merchant defined restriction.
400	NO_SUFFICIENT_FUND	The user's balance is insufficient to make payment.
400	CANCELED_USER	The user has canceled PayPay account.
401	USER_STATE_IS_NOT_ACTIVE	The request cannot be accepted because the user status is inactive.
401	INVALID_USER_AUTHORIZATION_ID	The specified user authorization ID is invalid.
401	EXPIRED_USER_AUTHORIZATION_ID	The user authorization ID expired
404	RESOURCE_NOT_FOUND	Order not found
500	TRANSACTION_FAILED	This code means the transactions is failed in PayPay side. You can create 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 is not able to be processed due to the current condition. E.g. the user is suspicious.
400	INVALID_PARAMS	The requested operation is not able to be processed due to the current condition. E.g. thetransaction limit exceeded.
400	CANCELED_USER	The user has canceled PayPay account.
400	THROTTLED_MULTIPLE_REFUND_REJECTED	Rejected refund request as similar request is in progress, you can retry after 1 minute.
400	REFUND_LIMIT_EXCEEDED	Order has reached maximum number of allowed refunds. This can only occur if the multiple refund feature is enabled for merchant.
400	REFUND_WINDOW_EXCEED	Refund window exceeded.
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

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.

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

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 PayPay	user authorization expired	Deauthorization in app operation
http status:400Code="CANCELED_USER"	http status:200data.expiresAt < current date	http status:200data.status="inactive"

Create a continuous payment、Get payment methods、Check user wallet balance、Get masked user profile

user status
terminate PayPay	user authorization expired	Deauthorization in app operation
http status:401Code="INVALID_USER_AUTHORIZATION_ID"	http status:401Code="EXPIRED_USER_AUTHORIZATION_ID"	http status:401Code="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:400Code="CANCELED_USER"	http status:200Code="SUCCESS"	http status:200Code="SUCCESS"

API General Request ID

In principle, all API responses include an X-REQUEST-ID in the response header (with some exceptions). When contacting PayPay support, please provide this request ID.

Format: Alphanumeric characters and hyphens (maximum 64 characters)

Example:

OPA45F681001AEF4605B2A50939F611F4B8

Payment

Everything involved in the payment life cycle

Create a continuous payment

Create a continuous 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

Request Body schema: application/json

Payment

merchantPaymentIdrequired	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.
userAuthorizationIdrequired	string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow
amountrequired	object (MoneyAmount)
requestedAtrequired	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
orderType	string (OrderType) <= 255 characters Value: "REMITTANCE" Type of the order
orderItems	Array of objects (MerchantOrderItem)
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 Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "PAYLATER_PAYMENT_ALLOCATION" "DONATION" "REMITTANCE" 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

200

Success

400

The request has invalid parameters or missing required parameters.

401

Unauthorized

500

Something went wrong on PayPay service side.

post/v1/subscription/payments

Production server

https://api.paypay.ne.jp/v1/subscription/payments

Staging server

https://stg-api.paypay.ne.jp/v1/subscription/payments

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v1/subscription/payments

Request samples

• Payload

Content typeapplication/jsonCopy Expand all Collapse all {

• "merchantPaymentId": "string",
• "userAuthorizationId": "string",
• "amount": {
  • "amount": 0,
  • "currency": "JPY"
  },
• "requestedAt": 1704112496,
• "storeId": "string",
• "terminalId": "string",
• "orderReceiptNumber": "string",
• "orderDescription": "string",
• "orderType": "REMITTANCE",
• "orderItems": [
  • {
    • "name": "string",
    • "category": "string",
    • "quantity": 1,
    • "productId": "string",
    • "unitPrice": {
      • "amount": 0,
      • "currency": "JPY"
      }
    }
  ],
• "paymentMethodType": "string",
• "paymentMethodId": "string",
• "productType": "VIRTUAL_BONUS_INVESTMENT",
• "onetimeUseCashback": "ENABLED"

}

Response samples

• 200
• 400
• 401
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "paymentId": "string",
  • "status": "CREATED",
  • "acceptedAt": 0,
  • "refunds": {
    • "data": [
      • {
        • "status": "CREATED",
        • "acceptedAt": 0,
        • "merchantRefundId": "string",
        • "paymentId": "string",
        • "amount": {
          • "amount": 0,
          • "currency": "JPY"
          },
        • "requestedAt": 1704112496,
        • "reason": "string"
        }
      ]
    },
  • "merchantPaymentId": "string",
  • "userAuthorizationId": "string",
  • "amount": {
    • "amount": 0,
    • "currency": "JPY"
    },
  • "requestedAt": 1704112496,
  • "storeId": "string",
  • "terminalId": "string",
  • "orderReceiptNumber": "string",
  • "orderDescription": "string",
  • "orderItems": [
    • {
      • "name": "string",
      • "category": "string",
      • "quantity": 1,
      • "productId": "string",
      • "unitPrice": {
        • "amount": 0,
        • "currency": "JPY"
        }
      }
    ],
  • "paymentMethods": [
    • {
      • "amount": {
        • "amount": 0,
        • "currency": "JPY"
        },
      • "type": "WALLET",
      • "breakdown": {
        • "points": [
          • {
            • "amount": 0,
            • "type": "REGULAR"
            }
          ]
        }
      }
    ]
  }

}

Get payment details

Get payment details.

Timeout: 15s

path Parameters

merchantPaymentIdrequired

string (MerchantPaymentIdSimple) <= 64 characters Transaction ID provided by merchant that uniquely identifies the transaction.

Responses

200

Success

401

Unauthorized

404

The requested resource doesn't exist.

500

Something went wrong on PayPay service side.

get/v2/payments/{merchantPaymentId}

Production server

https://api.paypay.ne.jp/v2/payments/{merchantPaymentId}

Staging server

https://stg-api.paypay.ne.jp/v2/payments/{merchantPaymentId}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/payments/{merchantPaymentId}

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "paymentId": "string",
  • "status": "CREATED",
  • "acceptedAt": 0,
  • "refunds": {
    • "data": [
      • {
        • "status": "CREATED",
        • "acceptedAt": 0,
        • "merchantRefundId": "string",
        • "paymentId": "string",
        • "amount": {
          • "amount": 0,
          • "currency": "JPY"
          },
        • "requestedAt": 1704112496,
        • "reason": "string"
        }
      ]
    },
  • "merchantPaymentId": "string",
  • "userAuthorizationId": "string",
  • "amount": {
    • "amount": 0,
    • "currency": "JPY"
    },
  • "requestedAt": 1704112496,
  • "storeId": "string",
  • "terminalId": "string",
  • "orderReceiptNumber": "string",
  • "orderDescription": "string",
  • "orderItems": [
    • {
      • "name": "string",
      • "category": "string",
      • "quantity": 1,
      • "productId": "string",
      • "unitPrice": {
        • "amount": 0,
        • "currency": "JPY"
        }
      }
    ],
  • "paymentMethods": [
    • {
      • "amount": {
        • "amount": 0,
        • "currency": "JPY"
        },
      • "type": "WALLET",
      • "breakdown": {
        • "points": [
          • {
            • "amount": 0,
            • "type": "REGULAR"
            }
          ]
        }
      }
    ]
  }

}

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

merchantPaymentIdrequired

string (MerchantPaymentIdSimple) <= 64 characters Transaction ID provided by merchant that uniquely identifies the transaction.

Responses

202

The request is accepted.

400

The request has invalid parameters or missing required parameters.

500

Something went wrong on PayPay service side.

delete/v2/payments/{merchantPaymentId}

Production server

https://api.paypay.ne.jp/v2/payments/{merchantPaymentId}

Staging server

https://stg-api.paypay.ne.jp/v2/payments/{merchantPaymentId}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/payments/{merchantPaymentId}

Response samples

• 202
• 400
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "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. This API cannot be used for product type DONATION or REMITTANCE. 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

merchantRefundIdrequired	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.
paymentIdrequired	string (PaymentId) <= 64 characters The payment transaction id provided by PayPay
amountrequired	object (MoneyAmount)
requestedAtrequired	integer (EpochTime) Epoch timestamp in seconds
reason	string (Reason) <= 255 characters

Responses

200

Success

4XX

Client Error

5XX

Server Error

post/v2/refunds

Production server

https://api.paypay.ne.jp/v2/refunds

Staging server

https://stg-api.paypay.ne.jp/v2/refunds

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/refunds

Request samples

• Payload

Content typeapplication/jsonCopy Expand all Collapse all {

• "merchantRefundId": "string",
• "paymentId": "string",
• "amount": {
  • "amount": 0,
  • "currency": "JPY"
  },
• "requestedAt": 1704112496,
• "reason": "string"

}

Response samples

• 200
• 4XX
• 5XX

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "status": "CREATED",
  • "acceptedAt": 0,
  • "merchantRefundId": "string",
  • "paymentId": "string",
  • "amount": {
    • "amount": 0,
    • "currency": "JPY"
    },
  • "requestedAt": 1704112496,
  • "reason": "string"
  }

}

Get refund details

Get refund details. 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.

Timeout: 15s

path Parameters

merchantRefundIdrequired

string (MerchantRefundIdSimple) <= 64 characters Transaction ID provided by merchant to uniquely identify a refund of a transaction.

query Parameters

paymentIdrequired

string (PaymentId) <= 64 characters The payment transaction id provided by PayPay

Responses

200

Success

401

Unauthorized

404

The requested resource doesn't exist.

500

Server Error

get/v2/refunds/{merchantRefundId}?paymentId={paymentId}

Production server

https://api.paypay.ne.jp/v2/refunds/{merchantRefundId}?paymentId={paymentId}

Staging server

https://stg-api.paypay.ne.jp/v2/refunds/{merchantRefundId}?paymentId={paymentId}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/refunds/{merchantRefundId}?paymentId={paymentId}

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "status": "CREATED",
  • "acceptedAt": 0,
  • "merchantRefundId": "string",
  • "paymentId": "string",
  • "amount": {
    • "amount": 0,
    • "currency": "JPY"
    },
  • "requestedAt": 1704112496,
  • "reason": "string"
  }

}

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

userAuthorizationIdrequired	string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow
productType	string (ProductTypeForPaymentMethods) Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "PAYLATER_PAYMENT_ALLOCATION" "DONATION" "REMITTANCE" 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.
orderType	string (OrderType) <= 255 characters Value: "REMITTANCE" Type of the order

Responses

200

Success

401

Unauthorized

404

The requested resource doesn't exist.

500

Something went wrong on PayPay service side.

get/v4/paymentMethods

Production server

https://api.paypay.ne.jp/v4/paymentMethods

Staging server

https://stg-api.paypay.ne.jp/v4/paymentMethods

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v4/paymentMethods

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "walletInfo": {
    • "userAuthorizationId": "string",
    • "totalBalance": {
      • "amount": 0,
      • "currency": "JPY"
      }
    },
  • "paymentMethods": [
    • {
      • "paymentMethodType": "CREDIT_CARD",
      • "id": "string",
      • "issuerName": "string",
      • "accountNo": "string",
      • "logoUrl": "string",
      • "disabled": true,
      • "underMaintenance": true,
      • "authenticated": true,
      • "limited": true,
      • "paymentMethodStatus": "string",
      • "membership": "PRIMARY",
      • "creditCardRank": "GOLD",
      • "brand": "V",
      • "cardIconUrl": "string",
      • "cardBrandUrl": "string",
      • "cardName": "string"
      }
    ]
  }

}

Wallet

Check user wallet balance

Check if user has enough balance to make a payment.

Timeout: 15s

query Parameters

userAuthorizationIdrequired	string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow
amountrequired	integer <= 255 characters
currencyrequired	string Value: "JPY"
productType	string (ProductType) 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.
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

200

Success

401

Unauthorized

404

The requested resource doesn't exist.

500

Something went wrong on PayPay service side.

get/v2/wallet/check_balance?userAuthorizationId={userAuthorizationId}&amount={amount}&currency={currency}

Production server

https://api.paypay.ne.jp/v2/wallet/check_balance?userAuthorizationId={userAuthorizationId}&amount={amount}&currency={currency}

Staging server

https://stg-api.paypay.ne.jp/v2/wallet/check_balance?userAuthorizationId={userAuthorizationId}&amount={amount}&currency={currency}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/wallet/check_balance?userAuthorizationId={userAuthorizationId}&amount={amount}&currency={currency}

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "hasEnoughBalance": true
  }

}

User

Everything related to user management

Unlink user

Unlink a user from the client

Timeout: 15s

path Parameters

userAuthorizationIdrequired

string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow

Responses

200

The request succeeded.

401

Unauthorized

404

The requested resource doesn't exist.

500

Something went wrong on PayPay service side.

delete/v2/user/authorizations/{userAuthorizationId}

Production server

https://api.paypay.ne.jp/v2/user/authorizations/{userAuthorizationId}

Staging server

https://stg-api.paypay.ne.jp/v2/user/authorizations/{userAuthorizationId}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/user/authorizations/{userAuthorizationId}

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": { }

}

Get user authorization status

Get the authorization status of a user

Timeout: 15s

query Parameters

userAuthorizationIdrequired

string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow

Responses

200

Success

401

Unauthorized

404

The requested resource doesn't exist.

500

Something went wrong on PayPay service side.

get/v2/user/authorizations?userAuthorizationId={userAuthorizationId}

Production server

https://api.paypay.ne.jp/v2/user/authorizations?userAuthorizationId={userAuthorizationId}

Staging server

https://stg-api.paypay.ne.jp/v2/user/authorizations?userAuthorizationId={userAuthorizationId}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/user/authorizations?userAuthorizationId={userAuthorizationId}

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "userAuthorizationId": "string",
  • "referenceIds": [
    • "string"
    ],
  • "status": "ACTIVE",
  • "scopes": [
    • "string"
    ],
  • "expireAt": 0,
  • "issuedAt": 0
  }

}

Get masked user profile

Get the masked phone number of the user

query Parameters

userAuthorizationIdrequired

string (UserAuthorizationId) <= 64 characters The PayPay user reference id returned by the user authorization flow

Responses

200

Success

401

Unauthorized

404

The requested resource doesn't exist.

500

Something went wrong on PayPay service side.

get/v2/user/profile/secure?userAuthorizationId={userAuthorizationId}

Production server

https://api.paypay.ne.jp/v2/user/profile/secure?userAuthorizationId={userAuthorizationId}

Staging server

https://stg-api.paypay.ne.jp/v2/user/profile/secure?userAuthorizationId={userAuthorizationId}

Sandbox server

https://stg-api.sandbox.paypay.ne.jp/v2/user/profile/secure?userAuthorizationId={userAuthorizationId}

Response samples

• 200
• 401
• 404
• 500

Content typeapplication/jsonCopy Expand all Collapse all {

• "resultInfo": {
  • "code": "string",
  • "message": "string",
  • "codeId": "string"
  },
• "data": {
  • "phoneNumber": "*******1234"
  }

}

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 continuous payment:API(COMPLETED)	Push notification	取引が完了しました。 金額：1000円 取引番号：xxxxxxxxxxxxxxxxxxxx 店舗名：テスト加盟店
Refund a payment:API	Push notification	取引番号: xxxxxxxxxxxxxxxxxxxx 1000円の返金が完了しました。
Insufficient funds	In-app notification	PayPay残高が不足しているためお支払いが失敗しました。PayPay残高にチャージするか他のお支払い方法を選択してください。
Create a continuous payment:API(FAILED)	Push 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 continuous payment:API	-	COMPLETED
Create a continuous 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 for which events we currently send webhook notifications.

Customer Events

Events related to user state changes.

customer.authroization.succeeded

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": "continuous_payments", "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 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.

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": "continuous_payments", "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ポイント", "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 continuous payment	Updated the description of request parameter "paymentMethodType"
2022.10.19	2022.10.27	Feature	Create a continuous payment	Added new error code USER_DAILY_LIMIT_FOR_MERCHANT_EXCEEDED
2022.11.17	2022.12.02	Feature	Create a continuous payment	Added a new request parameter productType
2022.12.17	2023.01.31	Feature	Create a continuous payment	Returned acceptedAt as zero when state is CREATED in Create a Continuous Payment api and Get payment details
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.13	Released	Documentation Fix	Recon file	Added that for "Status": "取引失敗", it may not be output to the recon file depending on the cause of the error.
2023.04.26	2023.06.12	Feature	Create a continuous payment, Get payment details	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 continuous payment, Get payment details	Updated the description of metadata.
2023.08.01	Released	Documentation Fix	Create a continuous payment, Get payment details	Updated the description of acceptedAt.
2023.09.01	2023.09.12	Feature	Create a continuous 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 continuous payment, Get payment details	Added POINT to paymentMethods.type.
2023.11.15	2023.12.04	Feature	Recon file	Added POINT/PayPayポイント payment type in methodOfPayment and new column paymentDetails.
2023.12.19	TBD	Feature	Get Refund details	Added new query param paymentId for the request and updated Get Refund details api description.
2024.03.12	Released	Documentation Fix	Create a continuous payment, Get payment details	Added that the metadata is obsolete.
2024.04.19	TBD	Feature	Create a continuous payment	paymentMethodId is no longer required for PAY_LATER_CC.
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	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.19	TBD	Feature	Get payment methods, Create a continuous payment, Check user wallet balance	Added a product type PAYLATER_PAYMENT_ALLOCATION.
2025.03.04	TBD	Feature	Create a continuous payment, Get payment details	Deleted the metadata.
2025.07.22	2025.07.22	Documentation Fix	Get refund details	Updated the description of Get refund details.
2025.07.30	TBD	Feature	Create a continuous payment, Get payment methods	Added new param orderType for the request.