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

Acquiring user authorization is achieved through a simple web redirect flow, similar with OAuth/OpenID Connect style WebView authentication & authorization flow.

Upon successful authorization, a user authorization id will be issued to you per user. You should store this id in your backend and link it to your internal user. Please ensure this user authorization id is not stored on the client side. This id will be used as the user identifier in the Payment, Cashback and Topup requests. It will be automatically extended each time you make a payment, grant a balance or re-authorize.
You can check the expiry date of the user authorization ID with "expiry" in the customer event webhook or "expireAt" in the response data of Get user authorization status.

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:

• api key and secret
• webhook endpoints
• client IP whitelist

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.

To acquire user's authorization, the host app should direct user to the PayPay authorization web page along with the parameters apiKey and a requestToken. In this page, user is able to login to PayPay and grant the direct debit permission to merchant or scan the QR code with PayPay application and link to the merchant.

Authorization page URL：Production server

https://www.paypay.ne.jp/app/opa/user_authorization?apiKey={apiKey}&requestToken={jwtToken}

Authorization page URL：Sandbox server

https://stg-www.sandbox.paypay.ne.jp/app/opa/user_authorization?apiKey={apiKey}&requestToken={jwtToken}

Required parameters

• apiKey is the api key issued during the onboarding process

• requestToken is a JWT token signed with the corresponding api key secret

{
  "alg": "HS256",
}
.
{
  "aud" : "paypay.ne.jp",
  "iss" : "<merchant organization id>",
  "exp": 1638198000,
  "scope" : "direct_debit,get_balance",
  "nonce" : "<random case sensitive string>",
  "redirectUrl": "https://<merchant service auth redirect endpoint>",
  "referenceId": "<merchant user reference id>",
  "deviceId": ""
}
.
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  base64Decode(API SECRET)
)

cliam	type	description
aud	string	"paypay.ne.jp"
iss	string	the merchant name
exp	number	The expiration date of the authorization page URL. Set with epoch time stamp (seconds).
scope	array of string	Scopes of the user authorization. Please select only what you need. direct_debit：Native Payment preauth_capture_native：Native Payment(Block and take money) get_balance：Get balance continuous_payments：Continuous payment pending_payments：Request Money merchant_topup：Transfer money to user balance Transfer money to user balance The following is only available at some special merchants. quick_pay user_notification user_topup user_profile push_notification notification_center_og notification_center_ab notification_center_tl bank_registration
nonce	string	will be sent back with response for the client side validation
redirectUrl	url string	The callback endpoint provided by client. Must be HTTPS, and its domain should be in the allowed authorization callback domains
referenceId	string	The id used to identify the user in merchant system. It will be stored in the PayPay db for reconsilliation purpose
deviceId	string	(Optional) The user mobile phone device id. If it is provided, we can use it to verify the user and skip the SMS verification, so as to provide more fluent UX

On PayPay's authorization page the user can choose to accept/ decline giving the merchant the authorization. Depending on the user action, the request to acquire user authorization could succeed or fail. We will encode the result into the JWT token and pass it back to the redirect url provided in the requestToken mentioned earlier. The specific parameters we will pass to the redirct url are as follows:

• apiKey is the api key issued during the onboarding process

• responseToken is a JWT token signed with the corresponding api key secret

  {
    "typ": "JWT",
    "alg": "HS256",
  }
  .
  {
    "aud" : "<merchant organization id>",
    "iss" : "paypay.ne.jp",
    "exp" : 1638198000,
    "result": "succeeded",
    "profileIdentifier": "*******5678",
    "nonce" : "<the same nonce in the request>",
    "userAuthorizationId" : "<PayPay user reference id>",
    "referenceId": "<merchant user reference id>"
  }
  .
  signature

claim	type	description
aud	string	the merchant name
iss	string	"paypay.ne.jp"
exp	number	The expiration date of the authorization page URL. Set with epoch time stamp (seconds).
result	string	succeeded, declined or bad_request
profileIdentifier	string	Masked phone number or email e.g. "*******5678", "abc*******@example.com"
nonce	string	the same nonce in the request for client side to validate the response
userAuthorizationId	string	PayPay user reference id which you should store in your db and use it in the api calls. Max length 64 chars
referenceId	string	the same referenceId in the request

So, after the user accepted or declined the authorization request, we will redirect the webview to the following URL.

https://<redirect url>?apiKey={apiKey}&responseToken={jwtToken}