PayPay Open Payment Api
API docs by Redocly

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

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 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., the
transaction 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 suspecious.
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 transaciton 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 suspecious.
400 INVALID_PARAMS The requested operation is not able to be processed due to the current condition. E.g. the
transaction 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
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 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 continuous payment、Get payment methods、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 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

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 (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 (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
{
  • "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 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

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

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

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 successfuly acuqired 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 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": "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ポイント" 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.