On PayPay, to have smooth account linking process QR code based flow is added. Here merchant will create a ACCOUNT LINK QR and display it to the user. User will have to scan QR code with login to his/her PayPay account or login with credentials to authorise OPA client.
Detailed design flow described here
The PayPay Open Payment API requires that you use TLS 1.2 or higher as a security measure. Note that you cannot connect with TLS 1.0 and TLS 1.1.
To start utilizing our Open Payment API platform, at first the business needs to be onboarded as a PayPay merchant.
This process usually consists of information collection, manual verification, contract confirmation and credentials issuance.
After becoming a merchant on PayPay, the following items would be setup for the client:
This setup can be managed using our merchant panel/ getting in touch with the sales representative.
Access from users to the PayPay app and PayPay web screen from outside Japan is restricted. Please contact us for details.
Everything related to OPA API Authorization is described here.
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.
status | code | message |
---|---|---|
400 | INVALID_REQUEST_PARAMS | the information provided by the request contains invalid data, e.g., unsupported currency. |
401 | UNAUTHORIZED | no valid api key and secret provided. |
429 | RATE_LIMIT | too many requests |
500 | INTERNAL_SERVER_ERROR | this code indicates that something went wrong during account link qr code creation, can be tried once again. |
status | code | message |
---|---|---|
201 | SUCCESS | success for creation |
400 | EXPECTATION_FAILED | when the scopes passed or callback url is invalid |
Status | Code | Message |
---|---|---|
200 | SUCCESS | Success |
404 | SESSION_NOT_FOUND | The requested resource is not found in the case given a wrong URL or the session get expired already. |
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.
Create an ACCOUNT LINK QR and display it to the user.
Timeout: 10s
Create account link QR
scopes required | Array of strings Scope of the user authorization.Please select only the required SCOPEs. |
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 |
referenceId | string <= 255 characters The id used to identify the user in merchant system. It will be stored in the PayPay db for reconsilliation 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. |
userAgent | string <= 255 characters The User agent of the web browser. When redirectType is |
object (KYCData) KYC data to be verified during account link |
{- "scopes": [
- "direct_debit",
- "get_balance"
], - "nonce": "string",
- "redirectType": "APP_DEEP_LINK",
- "redirectUrl": "string",
- "referenceId": "string",
- "phoneNumber": "string",
- "deviceId": "string",
- "userAgent": "string",
- "kycData": {
- "firstNameKana": "ジョン",
- "lastNameKana": "スズキ",
- "dateOfBirth": "string"
}
}
{- "resultInfo": {
- "code": "string",
- "message": "string",
- "codeId": "string"
}, - "data": {
- "linkQRCodeURL": "string"
}
}
Fetch the status of a ACCOUNT LINK QR code. This endpoint is intended to be used for polling, and the interval should be 2–3 seconds. Before start polling, wait half a minute so that the user can complete the linking process.
The polling itself is an optional solution and not required to use. See the "3 methods to get the account linking status" section below for detail.
Timeout: 10s
linkQRCodeURL required | string <urlencoded> Example: linkQRCodeURL=https://www.paypay-corp.co.jp/app/opa/web/link?code=https%3A%2F%2Fqr-stg.paypay-corp.co.jp%2F2818010757vFsOLzaglGjvtE The URL retrieved from the |
{- "resultInfo": {
- "code": "string",
- "message": "string",
- "codeId": "string"
}, - "data": {
- "status": "ACCEPTED",
- "referenceId": "string",
- "nonce": "string",
- "scopes": [
- "direct_debit",
- "get_balance"
], - "userAuthorizationId": "string",
- "profileIdentifier": "string",
- "expiry": 0
}
}
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.
For security, it is highly recommended that clients whitelist PayPay IP address to receive notifications.
Please keep reading to learn for which events we currently send webhook notifications.
Events related to user state changes. The authroization
comes as is.
attribute | type | is_required? | description |
---|---|---|---|
notification_type | string | yes | Type of the notification. Possible values: customer.authroization.succeeded , customer.authroization.failed , customer.authroization.revoked , customer.authroization.extended , customer.authroization.canceled |
notification_id | string | yes | The ID used to identify the notification |
createdAt | number | yes | The time at which the notification is created, epoch timestamp in seconds |
referenceId | string | no | The ID used to identify the user on the merchant's system |
nonce | string | yes if notification_type is customer.authroization.succeeded , customer.authroization.failed |
The same nonce in the request for client side to validate the response |
scopes | string | yes if notification_type is customer.authroization.succeeded , customer.authroization.extended |
Scopes of the user authorization |
userAuthorizationId | string | yes if notification_type is customer.authroization.succeeded , customer.authroization.revoked , customer.authroization.canceled , customer.authroization.extended |
PayPay user reference id which you should store in your db and use it in the api calls. Max length: 64 characters |
profileIdentifier | string | yes if notification_type is customer.authroization.succeeded |
Masked phone number or email e.g. "5678", "abc@example.com" |
expiry | number | yes if notification_type is customer.authroization.extended , customer.authroization.succeeded |
The authorization ID's expiration epoch timestamp in seconds |
result | string | yes if notification_type is customer.authroization.failed |
The result of the operation that the client is trying to do. Possible values: declined , kyc_not_completed , kyc_data_mismatch |
reason | string | yes if notification_type is customer.authroization.failed |
The reason for the result of the operation |
The following are examples of the possible notification types:
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": "direct_debit",
"userAuthorizationId": "xxxxx",
"profileIdentifier": "*******5678",
"expiry": 1669734000
}
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",
"reason": "invalid scope"
}
The result
will have declined
, kyc_not_completed
or kyc_data_mismatch
.
declined
if the request is rejected by userkyc_not_completed
if user has not completed kyckyc_data_mismatch
if user kyc data is mismatchedThis 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"
}
In order to ease third party account linking experience, we will increase user authorization expiry from the date of last transaction/ grant. So merchants and users will have to give authorization less often.
This notification is sent after user's authorization is extended from PayPay side.
{
"notification_type": "customer.authroization.extended",
"notification_id": "evt_aXnbdeFt2Ke",
"createdAt": 1349654313,
"scopes": "direct_debit",
"userAuthorizationId": "xxxxx",
"expiry": 1669734000
}
This notification will be sent after a user has been deleted.
sample event:
{
"notification_type": "customer.authorization.canceled",
"notification_id": "evt_aXnbdeFt2Ke",
"createdAt": 1349654313,
"userAuthorizationId": "xxxxx"
}
Click here for the latest FAQ.
Date of Change | Date of Release | Type of Change | Section | Updates |
---|---|---|---|---|
2022.12.21 | Released | Feature | Receive-the-user-authorization-result | Added redirect when authentication screen expires. |
2023.01.19 | Released | Feature | Create Account Link QR Code | Added that the deviceId is obsolete. |
2023.03.28 | Released | Feature | Receive-the-user-authorization-result | Changed the description of nonce. Changed signature description for JWT tokens. |
2023.03.28 | Released | Feature | Create Account Link QR Code | Changed the description of scopes. |
2023.03.28 | Released | Feature | Response code list | Changed the message of EXPECTATION_FAILED. |
2023.04.28 | 2023.05.25 | Feature | Create Account Link QR Code | Changed referenceId to optional |
2023.09.11 | Released | Feature | Receive the user authorization result | Changed signature description for JWT tokens. Changed the description of exp. |