PayPay Open Payment Api
API docs by Redocly

Retrieve the user's KYC information (1.0)

Introduction

This service allows merchants to retrieve user KYC information.

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 user's KYC info from PayPay KYC Service, you need to obtain the user’s authorization explicitly.

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

Set "get_kyc_info" for scope. Specify "get_kyc_info" only when using the Get user kycInfo endpoint.

To retrieve "Status of Residence" and "Period of Stay" information, the additional scope "kyc_foreign_status" is required.

API Authentication

Everything related to OPA API Authorization is described here.

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.
400 MISSING_REQUEST_PARAMS The set parameter is invalid.
400 INVALID_PARAMS The set parameter is invalid.
400 CANCELED_USER The user has canceled PayPay account.
401 UNAUTHORIZED No valid api key and secret provided
401 OP_OUT_OF_SCOPE The operation is not permitted.
401 INVALID_USER_AUTHORIZATION_ID The specified user authorization ID is invalid.
401 EXPIRED_USER_AUTHORIZATION_ID The user authorization ID expired
401 USER_STATE_IS_NOT_ACTIVE The request cannot be accepted because the user status is inactive.
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.

Below error could occur if merchant requires user eKYC information but the user is not done KYC with EKYC.

Status Code Description
400 KYC_NOT_COMPLETED The user has not completed KYC.
400 NON_EKYC_USER User KYC not happened with using EKYC.

KYC Passport APIs

Below error could occur if the user is flagged due to certain risks.

Status Code Description
400 UNACCEPTABLE_OP The requested operation cannot be processed due to a current condition. For example, the user is suspicious.
400 KYC_UPDATE_REQUIRED This user needs to update the KYC documents.

Fetch KYC info of completed KYC Passport QR

Status Code Description
404 SESSION_NOT_FOUND The requested code ID is not found or it is already expired.
400 KYC_PASSPORT_NOT_COMPLETED The user has not started or completed KYC passport process.

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

KYC APIs

Retrieve the user's KYC Information.

Get the user's KYC information.

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

The PayPay user reference id returned by the user authorization flow

requiredKycType
string (RequiredKycType)

The type of KYC information to include in the response, client must have the appropriate configuration to use this.

If client does not have the correct configuration, it will return 401 Response and OP_OUT_OF_SCOPE error.

Possible values: EKYC

If not passed or left blank, request will return the latest KYC information that the client has the correct configuration for.

Responses

Response samples

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

KYC Passport APIs

Retrieve the user's KYC Information for KYC Passport clients.

Get the user's KYC information for KYC Passport clients.
mini_app_kyc_passport scope is required in order to access this API.

header Parameters
X-USER-AUTHORIZATION-ID
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": {
    }
}

KYC Passport QR APIs

Create Account Linking QR Code

Create account linking QR code with KYC Passport flow.
For more details about account linking, please refer to this.

Timeout: 10s

Request Body schema: application/json
scopes
required
Array of strings

Scope of the user authorization.Please select only the required SCOPEs.
For SCOPE, specify the SCOPE described in "Acquire user authorization" in the API documentation of the API to be used.
If you do not know which SCOPE to specify, please contact us.

nonce
required
string <= 255 characters

Random generated string

redirectType
string
Default: "WEB_LINK"
Enum: "APP_DEEP_LINK" "WEB_LINK"

Parameter to decide whether to redirect to merchant app or merchant web application

redirectUrl
required
string <= 255 characters

The callback endpoint provided by client. For WEB_LINK it must be HTTPS, and its domain should be in the allowed authorization callback domains

referenceId
string <= 255 characters

The id used to identify the user in merchant system. It will be stored in the PayPay db for reconciliation purpose

phoneNumber
string

The user mobile phone number. When you open the login screen with a browser, it will be set as the initial value of the phone number.

deviceId
string <= 255 characters

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

userAgent
string <= 255 characters

The User agent of the web browser. When redirectType is WEB_LINK this parameter is provided, on mobile devices PayPay tries to open the browser that the merchant website is using.

object

KYC data to be verified during account link

accountLinkFlow
string
Default: null
Value: "KYC_PASSPORT"

The flow of account link.

object

This field is required when accountLinkFlow is KYC_PASSPORT.

Responses

Request samples

Content type
application/json
{
  • "scopes": [
    ],
  • "nonce": "string",
  • "redirectType": "APP_DEEP_LINK",
  • "redirectUrl": "string",
  • "referenceId": "string",
  • "phoneNumber": "string",
  • "deviceId": "string",
  • "userAgent": "string",
  • "kycData": {
    },
  • "accountLinkFlow": "KYC_PASSPORT",
  • "kycPassport": {
    }
}

Response samples

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

Fetch KYC info of completed KYC Passport QR

Fetch KYC info of completed KYC Passport QR.
kyc_passport_qr scope is required in order to access this API.

path Parameters
codeId
required
string

Code ID which was returned when creating KYC Passport QR code.

Request Body schema: application/json
codeVerifier
string <= 64 characters

The PKCE code verifier that was used when creating the KYC Passport QR code.

userAuthorizationId
string <= 64 characters

The PayPay user reference id returned by the user authorization flow.
This is required to get the KYC info if the user has completed KYC.

Responses

Request samples

Content type
application/json
{
  • "codeVerifier": "string",
  • "userAuthorizationId": "string"
}

Response samples

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

Changelog

Date of Documentation Update Date of Release Type of Change Section Updates
2023.01.25 released Documentation Fix Retrieve the user's KYC Information Update the description of status in response data
2024.06.04 released Documentation Fix Retrieve the user's KYC Information Update the description of eKycDocument in response data
2025.03.18 TBD Feature Retrieve the user's KYC Information Add a new API to get KYC passport information
2025.08.13 TBD Feature KYC Passport Events Add information about KYC passport events webhook
2025.08.13 TBD Feature KYC Passport Risk Events Add information about KYC passport risk events webhook
2025.11.28 TBD Feature Retrieve the user's KYC Information Add residenceType and expiryDate fields. Add new scope kyc_foreign_status
2026.01.26 TBD Feature Create Account Linking QR Code, Fetch KYC info of completed KYC Passport QR Added the API to the documentation
2026.02.10 TBD Documentation Fix Fetch KYC info of completed KYC Passport QR Update the description
2026.02.24 TBD Feature Webhooks, Recon File Add new webhook / recon file notifications for KYC passport
2026.02.17 TBD Feature Common response code Removed 404 OPA_CLIENT_NOT_FOUND.
2026.03.09 TBD Feature Webhooks, Recon File Revised descriptions
2026.03.27 TBD Feature Fetch KYC info of completed KYC Passport QR Add selfieImageUrl field
2026.04.01 TBD Feature Fetch KYC info of completed KYC Passport QR Change HTTP method from GET to POST

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.

Webhook URL types

Each webhook notification type is delivered to a separate webhook URL. The URLs are configured during onboarding.

Notification type Webhook URL
KYC Events Dedicated webhook URL for KYC events
KYC Passport Risk Events Dedicated webhook URL for KYC passport risk events
Account Status Events Dedicated webhook URL for account status events
Recon File Notifications Dedicated webhook URL for recon file notifications (shared by all recon file types)

KYC Events

This notification will be triggered when a user's KYC is updated. This notification is delivered to the dedicated webhook URL for KYC events.

attribute type is_required? description
notification_type string yes Type of the notification. Possible values: kyc_passport.kyc_info.updated
notification_id string yes The ID used to identify the notification
user_authorization_id string yes PayPay user reference id which you should store in your db and use it in the api calls. Max length: 64 characters 
{
  "notification_type": "kyc_passport.kyc_info.updated",
  "notification_id": "evt_aXnbdeFt2Ke",
  "user_authorization_id": "a85fe9e9-b4c9-45cf-a392-834c57d83af7"
}

KYC Passport Risk Events

This notification will be triggered when a user has been flagged for a certain risk. This notification is delivered to the dedicated webhook URL for KYC passport risk events.

attribute type is_required? description
notification_type string yes Type of the notification. Possible values: kyc_passport.risk.update
notification_id string yes The ID used to identify the notification
user_authorization_id string yes PayPay user reference id which you should store in your db and use it in the api calls. Max length: 64 characters 
{
  "notification_type": "kyc_passport.risk.update",
  "notification_id": "evt_aXnbdeFt2Ke",
  "user_authorization_id": "a85fe9e9-b4c9-45cf-a392-834c57d83af7"
}

Account Status Events

This notification will be triggered when a user's account status is updated. This notification is delivered to the dedicated webhook URL for account status events.

attribute type is_required? description
notification_type string yes Type of the notification. Possible values: kyc_passport.account_status.updated
notification_id string yes The ID used to identify the notification
user_authorization_id string yes PayPay user reference id which you should store in your db and use it in the api calls. Max length: 64 characters 
{
  "notification_type": "kyc_passport.account_status.updated",
  "notification_id": "evt_aXnbdeFt2Ke",
  "user_authorization_id": "a85fe9e9-b4c9-45cf-a392-834c57d83af7"
}

KYC Passport Recon File

This recon file contains a daily summary of users whose KYC information was updated. This corresponds to the real-time "KYC Events" webhook (kyc_passport.kyc_info.updated), delivered as a daily summary. PayPay generates this file by daily processing and delivers the notification via the Webhook URL for recon files.

File linkage specifications

Category Description Note
File linkage method Webhook
Webhook URL Webhook URL for recon files Recon file notifications are sent to the webhook for recon files, which is separate from the event webhook URLs.
File Name kyc_passport_＜merchant_id＞_＜from＞_＜to＞.csv
File creation unit merchant_id
Processing cycle (JST) Daily userAuthorizationId of users whose KYC is updated from 00:00:00 to 23:59:59 will be listed in the file.
Notification time (JST) Between 1:30 and 10:00
format CSV
File acquisition period 2 hours
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） UTF-8
character code（file name） UTF-8
newline code CRLF

File layout

Key Value from Note
userAuthorizationId userAuthorizationId userAuthorizationId of a user whose KYC is updated during the processing cycle period.

Webhook notifications

This notification is sent to the webhook for recon files when the recon file is generated. Download the file from the path included in the notification payload.

{
  "notification_type":"file.created",
  "notification_id": "<UUID>",
  "fileType":"kyc_passport_sync_recon",
  "path":"https://<server_path>/<filename>?parameters",
  "requestedAt":"<epoch time>"
}

Risk Recon File

This recon file contains a daily summary of users who have been flagged for a certain risk. This corresponds to the real-time "KYC Passport Risk Events" webhook (kyc_passport.risk.update), delivered as a daily summary. For clients enabling the risk recon file setting, PayPay generates this file by daily processing and delivers the notification via the Webhook URL for recon files.

File linkage specifications

Category Description Note
File linkage method Webhook
Webhook URL Webhook URL for recon files Recon file notifications are sent to the webhook for recon files, which is separate from the event webhook URLs.
File Name kyc_passport_risk_＜client_id＞_＜from＞_＜to＞.csv
File creation unit client_id
Processing cycle (JST) Daily userAuthorizationId of users who become flagged for a certain risk from 00:00:00 to 23:59:59 will be listed in the file.
Notification time (JST) Between 1:30 and 10:00
format CSV
File acquisition period 2 hours
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） UTF-8
character code（file name） UTF-8
newline code CRLF

File layout

Key Value from Note
userAuthorizationId userAuthorizationId userAuthorizationId of a user who becomes flagged for a certain risk during the processing cycle period.

Webhook notifications

This notification is sent to the webhook for recon files when the recon file is generated. Download the file from the path included in the notification payload.

{
  "notification_type":"file.created",
  "notification_id": "<UUID>",
  "fileType":"kyc_passport_risk_sync_recon",
  "path":"https://<server_path>/<filename>?parameters",
  "requestedAt":"<epoch time>"
}

Account Status Recon File

This recon file contains a daily summary of users whose account status was updated. This corresponds to the real-time "Account Status Events" webhook (kyc_passport.account_status.updated), delivered as a daily summary. For clients enabling the account status recon file setting, PayPay generates this file by daily processing and delivers the notification via the Webhook URL for recon files.

File linkage specifications

Category Description Note
File linkage method Webhook
Webhook URL Webhook URL for recon files Recon file notifications are sent to the webhook for recon files, which is separate from the event webhook URLs.
File Name kyc_passport_account_status_＜client_id＞_＜from＞_＜to＞.csv
File creation unit client_id
Processing cycle (JST) Daily userAuthorizationId of users whose account status is updated from 00:00:00 to 23:59:59 will be listed in the file.
Notification time (JST) Between 1:30 and 10:00
format CSV
File acquisition period 2 hours
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） UTF-8
character code（file name） UTF-8
newline code CRLF

File layout

Key Value from Note
userAuthorizationId userAuthorizationId userAuthorizationId of a user whose account status is updated during the processing cycle period.

Webhook notifications

This notification is sent to the webhook for recon files when the recon file is generated. Download the file from the path included in the notification payload.

{
  "notification_type":"file.created",
  "notification_id": "<UUID>",
  "fileType":"kyc_passport_account_status_sync_recon",
  "path":"https://<server_path>/<filename>?parameters",
  "requestedAt":"<epoch time>"
}